NitroSQLite
TypeScriptSource files: TypeScript
const NitroSQLite: object
Database entry point. Prefer open for a managed connection.
native exposes the Nitro object directly and bypasses the JavaScript queue.
Type Declaration
execute
execute: <Row>(dbName, query, params?) => QueryResult<Row>
Execute one SQL statement synchronously by database name. Uses the managed queue when the database has an open managed connection.
Type Parameters
Row
Row extends QueryResultRow = never
Parameters
dbName
string
Name of an open native database.
query
string
SQL statement with optional positional placeholders.
params?
Values bound to the placeholders.
Returns
QueryResult<Row>
The query result with typed rows.
executeAsync
executeAsync: <Row>(dbName, query, params?) => Promise<QueryResult<Row>>
Execute one SQL statement asynchronously by database name. Uses the managed queue when the database has an open managed connection.
Type Parameters
Row
Row extends QueryResultRow = never
Parameters
dbName
string
Name of an open native database.
query
string
SQL statement with optional positional placeholders.
params?
Values bound to the placeholders.
Returns
Promise<QueryResult<Row>>
A promise of the complete query result after all row batches arrive.
executeBatch
executeBatch: (dbName, commands, queueKey) => BatchQueryResult
Execute a batch synchronously in one exclusive transaction. Requires an open managed connection; throws if it is busy or the batch is empty.
Parameters
dbName
string
Name of the open database.
commands
SQL commands and optional parameter sets.
queueKey?
DatabaseQueueKey = dbName
Returns
Total affected row count.
executeBatchAsync
executeBatchAsync: (dbName, commands, queueKey) => Promise<BatchQueryResult>
Queue a batch in one exclusive transaction. Requires an open managed connection; a failed command rolls back the batch.
Parameters
dbName
string
Name of the open database.
commands
SQL commands and optional parameter sets.
queueKey?
DatabaseQueueKey = dbName
Returns
Promise<BatchQueryResult>
A promise of the total affected row count.
native
native: NitroSQLiteNative = HybridNitroSQLite
open
open: (options) => NitroSQLiteConnection
Open a database and return a managed connection. The default connection is
addressed by its name, and opening it twice throws. Set connection to
'independent' to open another native handle to the same file. Async calls
on each connection run in call order. An optional encryptionKey requires
a native build with SQLite SEE; it does not encrypt an existing plaintext file.
Parameters
options
Database name, optional directory, connection mode, read-only setting, and SEE key.
Returns
A connection bound to the opened native handle.
Throws
NitroSQLiteError with type EncryptionNotEnabled when a key is
supplied without SEE, or DatabaseCannotBeDecrypted for an invalid key,
wrong key, or existing plaintext database.
See
prepare
prepare: (dbName, query, queueKey) => PreparedStatement
Prepare one SQL statement on an open managed connection for repeated execution. Synchronous preparation throws if the connection is busy. Finalize the returned statement before closing the connection.
Parameters
dbName
string
Database name or independent connection ID.
query
string
SQL statement with optional positional placeholders.
queueKey?
DatabaseQueueKey = dbName
Internal managed queue key; omit when using the public API.
Returns
A statement whose executions use the same connection queue.
transaction
transaction: <Result>(dbName, transactionCallback, isExclusive, queueKey) => Promise<Result>
Queue a transaction for an open managed connection.
Use only the supplied tx for work on this database inside the callback.
A successful callback commits unless it explicitly committed or rolled back;
a thrown error rolls back unless the transaction was already finalized.
Failed commits trigger rollback and rejection unless the callback explicitly rolls back.
If rollback also fails, the error cause is an AggregateError with both failures.
Type Parameters
Result
Result = void
Parameters
dbName
string
Name of the open database.
transactionCallback
(tx) => Promise<Result>
Async callback receiving the transaction handle.
isExclusive?
boolean = false
Begin an exclusive transaction when true.
queueKey?
DatabaseQueueKey = dbName
Managed connection queue identifier; defaults to the database name.
Returns
Promise<Result>
The callback's result after the transaction finishes.
Throws
NitroSQLiteError if BEGIN, the callback, COMMIT, or ROLLBACK fails.