Skip to main content

Class: Database<D>

Database is the primary API for accessing the Tabeland network as a database. This class provides a small and simple API that will feel very familiar to web2 database users. It includes the concept of prepared statements, SQL parameter binding, execution and query modes, and more. It is actually similar to the better-sqlite3, and D1 APIs in many respects.

Type parameters

NameType
Dunknown

Constructors

constructor

new Database<D>(config?)

Create a Database instance with the specified connection configuration.

Type parameters

NameType
Dunknown

Parameters

NameTypeDescription
configPartial<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.

Defined in

@tableland/sdk/src/database.ts:36

Properties

config

Readonly config: Partial<ReadConfig & SignerConfig> & Partial<AutoWaitConfig>

Defined in

@tableland/sdk/src/database.ts:27

Methods

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

NameType
TD

Parameters

NameTypeDescription
statementsStatement<unknown>[]A set of Statement objects to batch and submit.
optsSignalAdditional options to control execution.

Returns

Promise<Result<T>[]>

An array of run results.

Defined in

@tableland/sdk/src/database.ts:93


dump

dump(_opts?): Promise<ArrayBuffer>

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

Parameters

NameTypeDescription
_optsSignalAdditional options to control execution.

Returns

Promise<ArrayBuffer>

Defined in

@tableland/sdk/src/database.ts:218


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

NameType
TD

Parameters

NameTypeDescription
statementStringsstringA set of SQL statement strings separated by semi-colons.
optsSignalAdditional options to control execution.

Returns

Promise<Result<T>>

A single run result.

Defined in

@tableland/sdk/src/database.ts:192


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

NameType
TD

Parameters

NameTypeDescription
sqlstringThe SQL statement string to prepare.

Returns

Statement<T>

A Statement object constructed with the given SQL string.

Defined in

@tableland/sdk/src/database.ts:72


forSigner

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

Create a Database that is connected to the given Signer.

Parameters

NameTypeDescription
signerSignerAn ethersjs Signer to use for mutating queries.

Returns

Promise<Database<unknown>>

A Database with a Signer, and a default baseUrl.

Defined in

@tableland/sdk/src/database.ts:59


readOnly

Static readOnly(chainNameOrId): Database<unknown>

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

Deprecated

since 4.0.1, will be deleted in 5.0.0

Parameters

NameTypeDescription
chainNameOrIdnumber | keyof TablelandNetworkConfigThe name or id of the chain to target.

Returns

Database<unknown>

A Database without a signer configured.

Defined in

@tableland/sdk/src/database.ts:46