Interface Client

Execute a batch of SQL statements in a transaction.

The batch is executed in its own logical database connection and the statements are wrapped in a transaction. This ensures that the batch is applied atomically: either all or no changes are applied.

The mode parameter selects the transaction mode for the batch; please see TransactionMode for details. The default transaction mode is "deferred".

If any of the statements in the batch fails with an error, the batch is aborted, the transaction is rolled back and the returned promise is rejected.

This method provides non-interactive transactions. If you need interactive transactions, please use the transaction method.

const rss = await client.batch([
    // batch statement without arguments
    "DELETE FROM books WHERE name LIKE '%Crusoe'",

    // batch statement with positional arguments
    {
        sql: "INSERT INTO books (name, author, published_at) VALUES (?, ?, ?)",
        args: ["First Impressions", "Jane Austen", 1813],
    },

    // batch statement with named arguments
    {
        sql: "UPDATE books SET name = $new WHERE name = $old",
        args: {old: "First Impressions", new: "Pride and Prejudice"},
    },
], "write");

Close the client and release resources.

This method closes the client (aborting any operations that are currently in progress) and releases any resources associated with the client (such as a WebSocket connection).

Execute a single SQL statement.

Every statement executed with this method is executed in its own logical database connection. If you want to execute a group of statements in a transaction, use the batch or the transaction methods.

// execute a statement without arguments
const rs = await client.execute("SELECT * FROM books");

// execute a statement with positional arguments
const rs = await client.execute({
    sql: "SELECT * FROM books WHERE author = ?",
    args: ["Jane Austen"],
});

// execute a statement with named arguments
const rs = await client.execute({
    sql: "SELECT * FROM books WHERE published_at > $year",
    args: {year: 1719},
});

Execute a sequence of SQL statements separated by semicolons.

The statements are executed sequentially on a new logical database connection. If a statement fails, further statements are not executed and this method throws an error. All results from the statements are ignored.

We do not wrap the statements in a transaction, but the SQL can contain explicit transaction-control statements such as BEGIN and COMMIT.

This method is intended to be used with existing SQL scripts, such as migrations or small database dumps. If you want to execute a sequence of statements programmatically, please use batch instead.

await client.executeMultiple(`
    CREATE TABLE books (id INTEGER PRIMARY KEY, title TEXT NOT NULL, author_id INTEGER NOT NULL);
    CREATE TABLE authors (id INTEGER PRIMARY KEY, name TEXT NOT NULL);
`);

Execute a batch of SQL statements in a transaction with PRAGMA foreign_keys=off; before and PRAGMA foreign_keys=on; after.

The batch is executed in its own logical database connection and the statements are wrapped in a transaction. This ensures that the batch is applied atomically: either all or no changes are applied.

The transaction mode is "deferred".

If any of the statements in the batch fails with an error, the batch is aborted, the transaction is rolled back and the returned promise is rejected.

const rss = await client.migrate([
    // statement without arguments
    "CREATE TABLE test (a INT)",

    // statement with positional arguments
    {
        sql: "INSERT INTO books (name, author, published_at) VALUES (?, ?, ?)",
        args: ["First Impressions", "Jane Austen", 1813],
    },

    // statement with named arguments
    {
        sql: "UPDATE books SET name = $new WHERE name = $old",
        args: {old: "First Impressions", new: "Pride and Prejudice"},
    },
]);

Start an interactive transaction.

Interactive transactions allow you to interleave execution of SQL statements with your application logic. They can be used if the batch method is too restrictive, but please note that interactive transactions have higher latency.

The mode parameter selects the transaction mode for the interactive transaction; please see TransactionMode for details. The default transaction mode is "deferred".

You must make sure that the returned Transaction object is closed, by calling close, commit or rollback. The best practice is to call close in a finally block, as follows:

const transaction = client.transaction("write");
try {
    // do some operations with the transaction here
    await transaction.execute({
        sql: "INSERT INTO books (name, author) VALUES (?, ?)",
        args: ["First Impressions", "Jane Austen"],
    });
    await transaction.execute({
        sql: "UPDATE books SET name = ? WHERE name = ?",
        args: ["Pride and Prejudice", "First Impressions"],
    });

    // if all went well, commit the transaction
    await transaction.commit();
} finally {
    // make sure to close the transaction, even if an exception was thrown
    transaction.close();
}

Start an interactive transaction in "write" mode.

Please see transaction for details.

Deprecated

Please specify the mode explicitly. The default "write" will be removed in the next major release.