Class DAL

The DAL instance. Create one with createDAL, then connect() before use. A single instance is meant to be shared across your whole app.

Index

Constructors

Accessors

Methods

connect schema close swapEngine

Constructors

constructor

new DAL(): DAL

Returns DAL

Accessors

pendingWrites

get pendingWrites(): number
Number of writes currently buffered in the collector (0 when disabled).

Returns number
- Defined in index.ts:811

Methods

connect

connect(config: DALConfig): Promise<void>
Initialise the driver & collector from config.
Parameters
- config: DALConfig
  Engine mode + collector settings.
Returns Promise<void>

Throws
ConfigurationError if the config is missing required fields, or if the engine's optional peer dependency (better-sqlite3 for local, pg for cloud) isn't installed.

Remarks
Calling this on an already connected DAL replaces the engine instead of leaking it => the previous collector is flushed & stopped and the previous driver closed (same work as DAL.close), with a console.warn so it doesn't happen unnoticed. Without that the old pg pool, flush timer & signal listeners stayed alive forever, and anything still buffered on the old collector was never written by anybody.

fragile, the order matters => the new engine is fully built (peer dep imported, driver constructed & its own config validated) before the old one is torn down, so a connect() that throws — bad config, a missing better-sqlite3/pg, a bad busyTimeout — leaves the connection you already had fully intact. Only once the replacement exists do we flush & close the old one and swap it in.
- Defined in index.ts:620

schema

schema(name: string): SchemaProxy
Start a fluent chain on the given schema.

Maps to ./data/databases/<name>.db in local mode, or the Postgres logical schema <name> in cloud mode.
Parameters
- name: string
  Schema name. Must match ^[a-zA-Z0-9_-]+$.
Returns SchemaProxy

Throws
NotConnectedError if called before connect().
- Defined in index.ts:710

close

close(): Promise<void>
Flush any pending writes & close all connections. Call on graceful shutdown.

Returns Promise<void>
- Defined in index.ts:716

swapEngine

swapEngine(options: DalSwapOptions): Promise<EngineSwapResult>
Swap this DAL onto the other engine from code => same migration as npm run db:engine-swap, no terminal involved.

Pending writes are flushed & the current handles closed first (deleting a .db file out from under an open connection is asking for trouble), then the data moves, then the DAL reconnects on the target engine reusing the same collector settings.

Closing first is also what lets an upward swap clean up the local files => a directory a DAL in this process still has open counts as un quiesced and is never deleted from, because a write sitting in its collector buffer is invisible to a migration reading the file.

Anything you don't pass is inherited from connect() => dataDir in local mode, connectionString in cloud mode, falling back to DATABASE_URL. Missing schemas, tables & directories on the target side are created.
Parameters
- options: DalSwapOptions
  Direction plus any overrides. See DalSwapOptions.
Returns Promise<EngineSwapResult>
Throws
NotConnectedError if called before connect().

Throws
ConfigurationError if no Postgres connection string can be resolved.
Example
```
// local SQLite => production Postgres, then keep querying the same db object
const result = await db.swapEngine({ direction: 'up', onConflict: 'overwrite' });
console.log(`moved ${result.totalRows} rows`);
```
- Defined in index.ts:754