Class: Transaction

Defined in: packages/core/src/api/transaction.ts:31

Constructors

Constructor

new Transaction(
   att, 
   handle, 
   options): Transaction;

Defined in: packages/core/src/api/transaction.ts:42

Parameters

Parameter	Type
att	Attachment
handle	number
options	TransactionOptions

Returns

Transaction

Accessors

autoUpgraded

Get Signature

get autoUpgraded(): boolean;

Defined in: packages/core/src/api/transaction.ts:61

True once autoUpgradeReadOnly has promoted this transaction to read-write.

Returns

boolean

---

handle

Get Signature

get handle(): number;

Defined in: packages/core/src/api/transaction.ts:52

Server-side transaction handle (changes across restart).

Returns

number

---

isFinished

Get Signature

get isFinished(): boolean;

Defined in: packages/core/src/api/transaction.ts:56

Returns

boolean

Methods

[asyncDispose]()

asyncDispose: Promise<void>;

Defined in: packages/core/src/api/transaction.ts:161

await using tx = await db.startTransaction() → rolls back at scope exit unless the transaction was committed (or rolled back) explicitly.

Returns

Promise<void>

---

commit()

commit(): Promise<void>;

Defined in: packages/core/src/api/transaction.ts:204

Returns

Promise<void>

---

commitRetaining()

commitRetaining(): Promise<void>;

Defined in: packages/core/src/api/transaction.ts:234

Commit but keep the transaction context open for further work.

Returns

Promise<void>

---

execute()

execute(
   sql, 
   params?, 
options?): Promise<number>;

Defined in: packages/core/src/api/transaction.ts:126

Run a statement, returning only the affected-record count.

Parameters

Parameter	Type	Default value
sql	string	undefined
params	QueryParams	[]
options?	QueryOptions	undefined

Returns

Promise<number>

---

executeBatch()

executeBatch(
   sql, 
   rows, 
options?): Promise<BatchResult>;

Defined in: packages/core/src/api/transaction.ts:135

Bulk-run one DML statement against many parameter rows inside THIS transaction via the wire batch API (Firebird 4+). Nothing commits here — the caller owns the transaction. See Attachment.executeBatch.

Parameters

Parameter	Type
sql	string
rows	BatchRows
options?	BatchOptions

Returns

Promise<BatchResult>

---

query()

query<T>(
   sql, 
   params?, 
options?): Promise<T[]>;

Defined in: packages/core/src/api/transaction.ts:87

Run a statement and return its rows (query<T> types them).

Type Parameters

Type Parameter	Default type
T	Row

Parameters

Parameter	Type	Default value
sql	string	undefined
params	QueryParams	[]
options?	QueryOptions	undefined

Returns

Promise<T[]>

---

queryOne()

queryOne<T>(
   sql, 
   params?, 
options?): Promise<T | undefined>;

Defined in: packages/core/src/api/transaction.ts:96

Run a statement and return the FIRST row, or undefined when the result is empty. The whole result set is still fetched — put FIRST 1 (or a unique predicate) in the SQL when the query could match many rows.

Type Parameters

Type Parameter	Default type
T	Row

Parameters

Parameter	Type	Default value
sql	string	undefined
params	QueryParams	[]
options?	QueryOptions	undefined

Returns

Promise<T | undefined>

---

queryStream()

queryStream<T>(
   sql, 
   params?, 
options?): AsyncGenerator<T>;

Defined in: packages/core/src/api/transaction.ts:145

Stream rows lazily within THIS transaction (no commit/rollback here — the caller owns the transaction). Backpressure at batch granularity. Lazy blob handles from this stream stay valid until the transaction ends.

Type Parameters

Type Parameter	Default type
T	Row

Parameters

Parameter	Type	Default value
sql	string	undefined
params	QueryParams	[]
options?	QueryOptions	undefined

Returns

AsyncGenerator<T>

---

restart()

restart(options?): Promise<void>;

Defined in: packages/core/src/api/transaction.ts:257

Finish the current transaction and immediately start a fresh one on the same connection, reusing the same isolation strategy — or a new one if transaction options are supplied. Reuses this Transaction object (its handle changes). Any lazy blob handles from before the restart become invalid (reading them throws FirebirdBlobError).

await tx.restart();                         // commit, reopen, same strategy
await tx.restart({ action: 'rollback' });   // rollback, reopen, same strategy
await tx.restart({ readOnly: false });      // commit, reopen with a new strategy

Parameters

Parameter	Type
options	RestartOptions

Returns

Promise<void>

---

rollback()

rollback(): Promise<void>;

Defined in: packages/core/src/api/transaction.ts:221

Returns

Promise<void>

---

rollbackRetaining()

rollbackRetaining(): Promise<void>;

Defined in: packages/core/src/api/transaction.ts:239

Returns

Promise<void>

---

run()

run<T>(
   sql, 
   params?, 
options?): Promise<QueryResult<T>>;

Defined in: packages/core/src/api/transaction.ts:101

Run a statement and return rows + affected-record count.

Type Parameters

Type Parameter	Default type
T	Row

Parameters

Parameter	Type	Default value
sql	string	undefined
params	QueryParams	[]
options?	QueryOptions	undefined

Returns

Promise<QueryResult<T>>

---

transaction()

transaction<T>(fn): Promise<T>;

Defined in: packages/core/src/api/transaction.ts:182

Run fn inside a SAVEPOINT (a nested transaction): released on success, rolled back to on error — the outer transaction survives either way. Nests arbitrarily (savepoint names are depth-based). fn receives THIS transaction: statements always run on the one server transaction.

await db.transaction(async (tx) => {
  await tx.execute('insert into audit values (?)', [1]);
  await tx.transaction(async () => {              // savepoint scope
    await tx.execute('insert into risky values (?)', [2]);
    throw new Error('undo just the inner part');
  }).catch(() => {});
  // audit row survives; risky row was rolled back
});

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
fn	(tx) => Promise<T>

Returns

Promise<T>