Skip to main content

Acquiring Connections

SqbClient.acquire() checks a connection out of the pool and hands you back a SqbConnection — a wrapper around a single live adapter connection that you use to run queries, manage transactions and read/change the schema.

acquire() is overloaded with two call forms.

Callback form (auto-release)​

const result = await client.acquire(async connection => {
  return connection.execute('select * from customers where id = $1', {
    params: [1],
  });
});
async acquire(fn: TransactionFunction, options?: ConnectionOptions): Promise<any>;

Pass a function and acquire() will:

  1. Check a connection out of the pool.
  2. Run your callback with that connection.
  3. Call connection.release() in a finally block, whatever your callback returns or throws.
  4. Resolve with whatever your callback returned (or reject with whatever it threw).

This is the recommended form for one-off units of work — you can't accidentally forget to release the connection.

No-callback form (manual release)​

const connection = await client.acquire();
try {
  await connection.execute('select 1');
} finally {
  connection.release();
}
async acquire(options?: ConnectionOptions): Promise<SqbConnection>;

Without a callback, acquire() resolves directly with the SqbConnection. You are responsible for releasing it — typically in a finally block, as above. This form is useful when a connection needs to stay open across multiple, non-contiguous calls (for example, when a cursor must outlive the function that opened it — see Cursors & Streaming).

ConnectionOptions currently has one field:

FieldTypeDescription
autoCommitbooleanDefault autoCommit behavior applied to every query executed on this connection (can still be overridden per-call — see Executing Queries).

Reference counting: retain() / release() / refCount​

A SqbConnection starts life with an internal reference count of 1. Instead of a hard open/close, SqbConnection uses reference counting to decide when the underlying adapter connection actually goes back to the pool:

  • connection.retain() increments refCount by one and emits a retain event.
  • connection.release() decrements refCount by one, emits a release event, and — once refCount reaches 0 — calls connection.close() to return the physical connection to the pool. It returns true if the connection was actually closed by that call, false otherwise.
  • connection.refCount reads the current count.

You rarely need to call retain() yourself in application code — SqbConnection calls it internally around every execute() call (so a query can't return the connection to the pool mid-flight), and SqbClient.execute() calls it once more when a query returns a Cursor, so the connection stays open until the cursor is closed. Call it yourself only if you need to keep a connection alive across an acquire() callback boundary or similar.

connection.close() releases the underlying adapter connection back to the pool immediately, regardless of refCount, and emits a close event.

sessionId and inTransaction​

  • connection.sessionId — an adapter-assigned identifier for the underlying session, useful for logging/debugging.
  • connection.inTransaction — true if a transaction is currently open on this connection (see Transactions).

Testing a connection​

await connection.test();

Delegates to the adapter connection's own test() method — useful for health checks. SqbClient also exposes client.test(), which acquires a connection, calls test() on it, and releases it.

Next steps​