Class Database<D>

constructor

• new Database<D>(config?): Database<D>

• Create a Database instance with the specified connection configuration.

  Type Parameters

  • D = unknown

  Parameters

  • config: Partial<ReadConfig & SignerConfig> & Partial<AutoWaitConfig> = {}

    The connection configuration. These keys are evaluated lazily, so it is possible to omit the baseUrl or signer, depending on your query needs. For a read-only Database for instance, only the baseUrl needs to be provided.

  Returns Database<D>

Readonly config

batch

• batch<T>(statements, opts?): Promise<Result<T>[]>

• Execute a set of Statements in batch mode. Batching sends multiple SQL statements inside a single call to the network. This can have a huge performance impact, as it only sends one transaction to the Tableland smart contract, thereby reducing gas costs. Batched statements are similar to SQL transactions. If a statement in the sequence fails, then an error is returned for that specific statement, and it aborts or rolls back the entire sequence.

  Type Parameters

  • T = D

  Parameters

  • statements: Statement<unknown>[]

    A set of Statement objects to batch and submit.

  • opts: Signal = {}

    Additional options to control execution.

  Returns Promise<Result<T>[]>

  An array of run results.

dump

• dump(_opts?): Promise<ArrayBuffer>

• Export a (set of) tables to the SQLite binary format. Not implemented yet!

  Parameters

  • _opts: Signal = {}

    Additional options to control execution.

  Returns Promise<ArrayBuffer>

exec

• exec<T>(statementStrings, opts?): Promise<Result<T>>

• Executes one or more queries directly without prepared statements or parameters binding. This method can have poorer performance (prepared statements can be reused in some cases) and, more importantly, is less safe. Only use this method for maintenance and one-shot tasks (example: migration jobs). The input can be one or multiple queries separated by the standard ;. If an error occurs, an exception is thrown with the query and error messages (see below for Errors). Currently, the entire string of statements is submitted as a single transaction. In the future, more "intelligent" transaction planning, splitting, and batching may be used.

  Type Parameters

  • T = D

  Parameters

  • statementStrings: string

    A set of SQL statement strings separated by semi-colons.

  • opts: Signal = {}

    Additional options to control execution.

  Returns Promise<Result<T>>

  A single run result.

prepare

• prepare<T>(sql): Statement<T>

• Create a new prepared statement. Both static and prepared statements are supported. In the current implementation, the prepared statements are prepared locally, and executed remotely (on-chain).

  Type Parameters

  • T = D

  Parameters

  • sql: string

    The SQL statement string to prepare.

  Returns Statement<T>

  A Statement object constructed with the given SQL string.

Static forSigner

• forSigner(signer): Promise<Database<unknown>>

• Create a Database that is connected to the given Signer.

  Parameters

  • signer: Signer

    An ethersjs Signer to use for mutating queries.

  Returns Promise<Database<unknown>>

  A Database with a Signer, and a default baseUrl.

Static readOnly

• readOnly(chainNameOrId): Database<unknown>

• Create a Database that uses the default baseUrl for a given chain.

  Parameters

  • chainNameOrId: number | keyof TablelandNetworkConfig

    The name or id of the chain to target.

  Returns Database<unknown>

  A Database without a signer configured.

  Deprecated

  since 4.0.1, will be deleted in 5.0.0