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
| Name | Type |
|---|---|
D | unknown |
Constructors
constructor
• new Database<D>(config?)
Create a Database instance with the specified connection configuration.
Type parameters
| Name | Type |
|---|---|
D | unknown |
Parameters
| Name | Type | Description |
|---|---|---|
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. |
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
| Name | Type |
|---|---|
T | D |
Parameters
| Name | Type | Description |
|---|---|---|
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.
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
| Name | Type | Description |
|---|---|---|
_opts | Signal | Additional 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
| Name | Type |
|---|---|
T | D |
Parameters
| Name | Type | Description |
|---|---|---|
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.
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
| Name | Type |
|---|---|
T | D |
Parameters
| Name | Type | Description |
|---|---|---|
sql | string | The 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
| Name | Type | Description |
|---|---|---|
signer | Signer | An 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
| Name | Type | Description |
|---|---|---|
chainNameOrId | number | keyof TablelandNetworkConfig | The 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