Class: Attachment

Defined in: packages/core/src/api/attachment.ts:29

An open database attachment. Obtain via connect() or createDatabase().

Properties

Property	Modifier	Type	Defined in
options	readonly	ResolvedOptions	packages/core/src/api/attachment.ts:45

Accessors

dbHandle

Get Signature

get dbHandle(): number;

Defined in: packages/core/src/api/attachment.ts:66

Server-side database handle on the current connection.

Returns

number

---

generation

Get Signature

get generation(): number;

Defined in: packages/core/src/api/attachment.ts:80

Reconnect epoch: 0 until the first reconnect(), +1 per reconnect. Transactions, prepared statements and lazy blobs remember the generation they were created in and throw once it moves past them.

Returns

number

---

handshake

Get Signature

get handshake(): HandshakeResult;

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

Handshake of the current wire connection.

Returns

HandshakeResult

---

isAlive

Get Signature

get isAlive(): boolean;

Defined in: packages/core/src/api/attachment.ts:427

True while the connection is usable (socket open, not detached).

Returns

boolean

---

protocolVersion

Get Signature

get protocolVersion(): number;

Defined in: packages/core/src/api/attachment.ts:202

Negotiated protocol version (13 = FB3 … 16 = FB4/5).

Returns

number

---

roundTrips

Get Signature

get roundTrips(): number;

Defined in: packages/core/src/api/attachment.ts:110

Packet flushes performed on this connection so far (≈ round trips). Cumulative across reconnect(). Useful for performance assertions and diagnostics.

Returns

number

---

wire

Get Signature

get wire(): WireConnection;

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

Wire connection currently in use (swapped by reconnect()).

Returns

WireConnection

---

wireCompressed

Get Signature

get wireCompressed(): boolean;

Defined in: packages/core/src/api/attachment.ts:215

Returns

boolean

---

wireCryptPlugin

Get Signature

get wireCryptPlugin(): string | null;

Defined in: packages/core/src/api/attachment.ts:211

Negotiated wire-crypt plugin (Arc4/ChaCha/ChaCha64), or null.

Returns

string | null

---

wireEncrypted

Get Signature

get wireEncrypted(): boolean;

Defined in: packages/core/src/api/attachment.ts:206

Returns

boolean

Methods

[asyncDispose]()

asyncDispose: Promise<void>;

Defined in: packages/core/src/api/attachment.ts:458

await using db = await connect(…) → disconnects at scope exit.

Returns

Promise<void>

---

clearStatementCache()

clearStatementCache(): Promise<void>;

Defined in: packages/core/src/api/attachment.ts:446

Drop every cached prepared statement and release the server handles NOW (the deferred op_free_statements ride one op_ping round trip). Prepared statements pin table metadata, so run this before DDL like recreate table — otherwise it fails with "object ... is in use".

Returns

Promise<void>

---

disconnect()

disconnect(): Promise<void>;

Defined in: packages/core/src/api/attachment.ts:462

Returns

Promise<void>

---

dropDatabase()

dropDatabase(): Promise<void>;

Defined in: packages/core/src/api/attachment.ts:478

Drops the attached database file on the server, then closes.

Returns

Promise<void>

---

events()

events(names): Promise<EventListener>;

Defined in: packages/core/src/api/attachment.ts:393

Subscribe to Firebird POST_EVENT notifications. Returns a started EventListener (an EventEmitter): .on(name, count => …) per event, .on('post', (name, count) => …) for any, .on('error', …). Call .close() when done. Uses a separate async channel, so it does not block queries on this connection.

const ev = await db.events(['order_placed']);
ev.on('order_placed', (count) => refresh());

Parameters

Parameter	Type
names	string[]

Returns

Promise<EventListener>

---

execute()

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

Defined in: packages/core/src/api/attachment.ts:320

Run a single statement in its own transaction; returns affected 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/attachment.ts:341

Run one DML statement against MANY parameter rows in bulk via the wire batch API (Firebird 4+): all rows travel to the server in one round trip per ~8 MiB cycle, instead of one per row. Runs in its own transaction — committed on success (with continueOnError, the successful rows).

Rows are positional arrays or @name objects; the connection must not be used for other statements while an async rows source is consumed.

const r = await db.executeBatch(
  'insert into orders (id, total) values (?, ?)',
  [[1, '9.99'], [2, '15.00'], [3, '7.50']],
);
r.rowsAffected; // 3

Parameters

Parameter	Type
sql	string
rows	BatchRows
options?	BatchOptions

Returns

Promise<BatchResult>

---

executeScript()

executeScript(script, options?): Promise<ScriptExecutionResult>;

Defined in: packages/core/src/api/attachment.ts:377

Parse and execute a multi-statement Firebird script (handles SET TERM, PSQL bodies, comments, strings). See ExecuteScriptOptions for transaction scoping and error handling.

Parameters

Parameter	Type
script	string
options?	ExecuteScriptOptions

Returns

Promise<ScriptExecutionResult>

---

ping()

ping(): Promise<void>;

Defined in: packages/core/src/api/attachment.ts:432

Cheap liveness check via op_ping (one round trip).

Returns

Promise<void>

---

prepare()

prepare(sql): Promise<PreparedStatement>;

Defined in: packages/core/src/api/attachment.ts:272

Prepare a statement for repeated execution (pinned outside the LRU cache). Close it when done.

Parameters

Parameter	Type
sql	string

Returns

Promise<PreparedStatement>

---

query()

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

Defined in: packages/core/src/api/attachment.ts:255

Run a single statement in its own transaction and return the rows. Type rows via the generic: db.query<{ ID: number }>('select id from t'). (Compile-time shaping only — no runtime validation.)

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/attachment.ts:264

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/attachment.ts:405

Type Parameters

Type Parameter	Default type
T	Row

Parameters

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

Returns

AsyncGenerator<T>

---

reconnect()

reconnect(): Promise<void>;

Defined in: packages/core/src/api/attachment.ts:178

Tear down the wire connection and re-attach to the same database with the same options — on the SAME Attachment object, so every holder of the reference (a pool, a script executor) keeps working. Everything created before the reconnect is dead: Transactions, PreparedStatements, lazy Blob handles and event listeners throw a clear "attachment was reconnected" error when used (event listeners get an 'error' event). The statement cache and inline-blob cache start fresh; roundTrips keeps counting cumulatively.

If establishing the new connection fails, the attachment is left closed (isAlive is false) but not detached — reconnect() can be retried.

Returns

Promise<void>

---

run()

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

Defined in: packages/core/src/api/attachment.ts:294

Run a single statement in its own transaction; returns rows + 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>>

---

startTransaction()

startTransaction(options?): Promise<Transaction>;

Defined in: packages/core/src/api/attachment.ts:223

Start an explicit transaction. Options merge field-by-field over the connection's defaultTransaction (see FirebirdConnectionOptions).

Parameters

Parameter	Type
options?	TransactionOptions

Returns

Promise<Transaction>

---

transaction()

transaction<T>(fn, options?): Promise<T>;

Defined in: packages/core/src/api/attachment.ts:232

Run fn inside a transaction: commits on success, rolls back on error.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
fn	(tx) => Promise<T>
options?	TransactionOptions

Returns

Promise<T>

---

open()

static open(raw, mode?): Promise<Attachment>;

Defined in: packages/core/src/api/attachment.ts:121

Parameters

Parameter	Type	Default value
raw	ConnectInput	undefined
mode	"create" | "attach"	'attach'

Returns

Promise<Attachment>