# JavaScript API reference This document describes the JavaScript API for Turso. The API is implemented in two different packages: - [@tursodatabase/database](https://www.npmjs.com/package/@tursodatabase/database) (`bindings/javascript`) - Native bindings for the Turso database. - [@tursodatabase/serverless](https://www.npmjs.com/package/@tursodatabase/serverless) (`serverless/javascript`) - Serverless driver for Turso Cloud databases. The API is compatible with the libSQL promise API, which is an asynchronous variant of the `better-sqlite3` API. ## Functions #### connect(path, [options]) ⇒ Database Opens a new database connection. | Param | Type | Description | | ------- | ------------------- | ------------------------- | | path | string | Path to the database file | The `path` parameter points to the SQLite database file to open. If the file pointed to by `path` does not exists, it will be created. To open an in-memory database, please pass `:memory:` as the `path` parameter. Supported `options` fields include: - `timeout`: busy timeout in milliseconds - `defaultQueryTimeout`: default maximum query execution time in milliseconds before interruption Per-query timeout override is available via `queryOptions`, for example: - `db.exec("SELECT 1", { queryTimeout: 100 })` - `stmt.get(undefined, { queryTimeout: 100 })` The function returns a `Database` object. ## class Database The `Database` class represents a connection that can prepare and execute SQL statements. ### Methods #### prepare(sql) ⇒ Statement Prepares a SQL statement for execution. | Param | Type | Description | | ------ | ------------------- | ------------------------------------ | | sql | string | The SQL statement string to prepare. | The function returns a `Statement` object. #### batch(statements, [mode]) ⇒ object Executes an array of SQL statements over the connection. Each statement is either a SQL string or an object of the form `{ sql, args }`, where `args` is an array of positional bind parameters or an object of named bind parameters. | Param | Type | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | statements | Array<string \| { sql: string, args?: any[] \| Record<string, any> }> | The SQL statements to execute as a batch. | | mode | "deferred" \| "immediate" \| "exclusive" \| "concurrent" | Optional. When set, the batch is wrapped in `BEGIN ` / `COMMIT` (with `ROLLBACK` on failure). Ignored when already inside a `transaction(...)` callback. | Without a `mode`, `batch()` is not transactional: each statement runs in its own autocommit step, so a failure mid-batch leaves earlier successful statements committed. With a `mode`, the batch becomes atomic — on the serverless driver the entire batch (including `BEGIN`, the user statements, `COMMIT`, and a conditional `ROLLBACK`) ships as a single Hrana request, so an atomic batch is still one round-trip. When `mode` is set, `batch()` owns the surrounding `BEGIN`/`COMMIT`/`ROLLBACK`. Do not include transaction-control SQL (`BEGIN`, `COMMIT`, `ROLLBACK`, `SAVEPOINT`, `RELEASE`) in `statements`; the input is not validated, and a user-supplied `COMMIT` will close the wrapper transaction mid-batch and leave earlier statements committed. For flexible all-or-nothing work that mixes `batch()` with other calls, wrap them in `transactionAsync(...)` (or one of its `deferred`/`immediate`/`exclusive`/`concurrent` variants): ```js const txn = db.transactionAsync(async (tx) => { await tx.batch([ { sql: "INSERT INTO users(name) VALUES (?)", args: ["Alice"] }, { sql: "INSERT INTO users(name) VALUES (?)", args: ["Bob"] }, ]); await tx.exec("UPDATE counters SET n = n + 1"); }); await txn.immediate(); ``` The function returns an object with two properties: `rowsAffected` (the total number of rows affected by all statements) and `lastInsertRowid` (the `rowid` of the last successful insert, or `undefined` if the batch performed no inserts). #### transaction(function) ⇒ function **Deprecated — use [`transactionAsync(function)`](#transactionasyncfunction--function) instead.** Returns a function that runs the given callback between `BEGIN` and `COMMIT` (`ROLLBACK` on error), passing through the call's own arguments. The wrapper does not own the connection: concurrent statements and transactions can interleave their own statements into the transaction's window and be committed or rolled back with it, which is why this API is deprecated. #### transactionAsync(function) ⇒ function Returns a function that runs the given callback inside a transaction: `BEGIN` before the callback, `COMMIT` on success, `ROLLBACK` on error. The wrapper owns the connection for the whole transaction — concurrent statements and transactions queue until it finishes, so nothing can interleave with the transaction's window. The callback receives a `Transaction` handle as its first argument, followed by the arguments the wrapped function was called with. All SQL inside the callback must go through the handle (`tx.exec`, `tx.prepare`, `tx.run`, `tx.get`, `tx.all`, `tx.iterate`, `tx.batch`); calls on the `Database` itself wait for the transaction to finish, so awaiting them inside the callback deadlocks it. The handle becomes unusable once the transaction completes. Callbacks that do not declare the handle parameter are rejected. The returned function exposes `deferred`, `immediate`, `exclusive`, and `concurrent` properties that begin the transaction with the corresponding locking mode. ```js const insertMany = db.transactionAsync(async (tx, users) => { const insert = await tx.prepare("INSERT INTO users(name, email) VALUES (?, ?)"); for (const user of users) { await insert.run(user.name, user.email); } }); await insertMany([ { name: "Alice", email: "alice@example.org" }, { name: "Bob", email: "bob@example.org" }, ]); // or with an explicit locking mode: await insertMany.immediate([{ name: "Carol", email: "carol@example.org" }]); ``` #### pragma(string, [options]) ⇒ results This function is currently not supported. #### backup(destination, [options]) ⇒ promise This function is currently not supported. #### serialize([options]) ⇒ Buffer This function is currently not supported. #### function(name, [options], function) ⇒ this This function is currently not supported. #### aggregate(name, options) ⇒ this This function is currently not supported. #### table(name, definition) ⇒ this This function is currently not supported. #### authorizer(rules) ⇒ this This function is currently not supported. #### loadExtension(path, [entryPoint]) ⇒ this This function is currently not supported. #### exec(sql) ⇒ this Executes a SQL statement. | Param | Type | Description | | ------ | ------------------- | ------------------------------------ | | sql | string | The SQL statement string to execute. | #### interrupt() ⇒ this This function is currently not supported. #### close() ⇒ this Closes the database connection. ## class Statement ### Methods #### run([...bindParameters]) ⇒ object Executes the SQL statement and returns an info object. | Param | Type | Description | | -------------- | ----------------------------- | ------------------------------------------------ | | bindParameters | array of objects | The bind parameters for executing the statement. | The returned info object contains two properties: `changes` that describes the number of modified rows and `info.lastInsertRowid` that represents the `rowid` of the last inserted row. #### get([...bindParameters]) ⇒ row Executes the SQL statement and returns the first row. | Param | Type | Description | | -------------- | ----------------------------- | ------------------------------------------------ | | bindParameters | array of objects | The bind parameters for executing the statement. | ### all([...bindParameters]) ⇒ array of rows Executes the SQL statement and returns an array of the resulting rows. | Param | Type | Description | | -------------- | ----------------------------- | ------------------------------------------------ | | bindParameters | array of objects | The bind parameters for executing the statement. | ### iterate([...bindParameters]) ⇒ iterator Executes the SQL statement and returns an iterator to the resulting rows. | Param | Type | Description | | -------------- | ----------------------------- | ------------------------------------------------ | | bindParameters | array of objects | The bind parameters for executing the statement. | #### pluck([toggleState]) ⇒ this This function is currently not supported. #### expand([toggleState]) ⇒ this This function is currently not supported. #### raw([rawMode]) ⇒ this This function is currently not supported. #### timed([toggle]) ⇒ this This function is currently not supported. #### columns() ⇒ array of objects This function is currently not supported. #### bind([...bindParameters]) ⇒ this This function is currently not supported.