Interface Transaction

Interactive transaction.

A transaction groups multiple SQL statements together, so that they are applied atomically: either all changes are applied, or none are. Other SQL statements on the database (including statements executed on the same Client object outside of this transaction) will not see any changes from the transaction until the transaction is committed by calling commit. You can also use rollback to abort the transaction and roll back the changes.

You must make sure that the 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();
}

Hierarchy

  • Transaction

Properties

closed

Methods

batch close commit execute executeMultiple rollback

Properties

closed

closed: boolean

Is the transaction closed?

This is set to true after a call to close, commit or rollback, or if we encounter an unrecoverable error.

Methods

batch

  • Execute a batch of SQL statements in this transaction.

    If any of the statements in the batch fails with an error, further statements are not executed and the returned promise is rejected with an error, but the transaction is not rolled back.

    Parameters

    Returns Promise<ResultSet[]>

close

  • Close the transaction.

    This method closes the transaction and releases any resources associated with the transaction. If the transaction is already closed (perhaps by a previous call to commit or rollback), then this method does nothing.

    If the transaction wasn't already committed by calling commit, the transaction is rolled back.

    Returns void

commit

  • Commit changes from this transaction to the database.

    This method closes the transaction and applies all changes done by the previous SQL statement on this transaction. Once the returned promise is resolved successfully, the database guarantees that the changes were applied.

    Returns Promise<void>

execute

  • Execute an SQL statement in this transaction.

    If the statement makes any changes to the database, these changes won't be visible to statements outside of this transaction until you call rollback.

    await transaction.execute({
        sql: "INSERT INTO books (name, author) VALUES (?, ?)",
        args: ["First Impressions", "Jane Austen"],
    });

    Parameters

    Returns Promise<ResultSet>

executeMultiple

  • Execute a sequence of SQL statements separated by semicolons.

    The statements are executed sequentially in the transaction. If a statement fails, further statements are not executed and this method throws an error, but the transaction won't be rolled back. All results from the statements are ignored.

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

    Parameters

    • sql: string

    Returns Promise<void>

rollback

  • Roll back any changes from this transaction.

    This method closes the transaction and undoes any changes done by the previous SQL statements on this transaction. You cannot call this method after calling commit, though.

    Returns Promise<void>

Settings

Member Visibility

Theme

Generated using TypeDoc