Database Adapters
Connect Federation to SQLite, Cloudflare D1, or PostgreSQL through the shared Database base class.
Local Federation accepts a Database instance derived from @downcity/federation; the adapter owns the driver, transactions, DDL, and connection lifecycle.
SQLite
pnpm add @downcity/federation @downcity/database-sqliteimport { Federation } from "@downcity/federation";
import { Database } from "@downcity/database-sqlite";
const database = new Database({ filename: "./federation.sqlite" });
const federation = new Federation({ database });Use filename: ":memory:" in tests. File databases enable WAL by default.
Cloudflare D1
import { Federation } from "@downcity/federation";
import { Database } from "@downcity/database-d1";
const database = new Database({ binding: env.DB });
const federation = new Federation({ database });The D1 adapter provides the same context.transaction() contract through snapshots, conflict retries, and atomic batch() commits. Reads inside a transaction observe its buffered writes.
PostgreSQL
import { Federation } from "@downcity/federation";
import { Database } from "@downcity/database-postgresql";
const database = new Database({ url: process.env.DATABASE_URL! });
const federation = new Federation({ database });The PostgreSQL adapter uses postgres-js and native Drizzle transactions.
Service boundary and lifecycle
Services use context.table() and context.transaction(). Selected official integrations can use the restricted context.database.query() / atomic() surface, but never receive the underlying driver client.
Federation owns the supplied database. First close dependent Cities and stop the host's queue consumer and maintenance scheduler, then call await federation.dispose(). Disposal rejects new business execution, cancels foreground requests, and waits for accepted HTTP business dispatch, queue.call() Actions including Hooks, and maintenance() before closing the database. Unmanaged detached work and externally held database handles remain the host's responsibility.
The SQLite Adapter waits for accepted transactions and queued operations before closing its native connection. Transactions retain their commit or rollback outcome. New operations, including calls through an existing ordinary Table API, are rejected once database closing begins. Concurrent database.dispose() calls wait for the same close result. Database ownership is exclusive: hosts must not share an Adapter between independently owned Federation instances.