Interface DatabaseOptions

Database connection options.

interface DatabaseOptions {
    url?: string;
    file?: string;
    postgres?: PostgresAdapterOptions;
    mobile?: CapacitorAdapterOptions;
    indexedDb?: IndexedDbAdapterOptions;
    type?:
        | "sqlite"
        | "postgres"
        | "memory"
        | "browser"
        | "mobile";
    priority?: AdapterKind[];
    strict?: boolean;
    foreignKeys?: boolean;
    segment?: string;
    logger?: StorageLogger;
    hooks?: StorageHooks;
}

Properties

url? file? postgres? mobile? indexedDb? type? priority? strict? foreignKeys? segment? logger? hooks?

Properties

Optionalurl

url?: string

Database URL (e.g., postgresql://user:pass@host/db). A postgres:// or postgresql:// URL makes createDatabase() use PostgreSQL on Node, with no fallback to SQLite, unless priority or type says otherwise. A URL of another scheme (file:./dev.db, sqlite:...) names no PostgreSQL server: the local default opens, or, with strict, createDatabase() fails.

Optionalfile

file?: string

File path for SQLite database. Used for local/offline storage.

Optionalpostgres

postgres?: PostgresAdapterOptions

PostgreSQL-specific configuration, passed on to the Postgres adapter whole. When it names a server (a pool of the caller's, a postgres:// or postgresql:// connection string, or a host, database or user), PostgreSQL is used on Node, with no fallback to SQLite, unless priority or type says otherwise. { connectionString: process.env.DATABASE_URL } with DATABASE_URL unset, or set to a URL of another scheme, names none, and the local default is used. To open PostgreSQL from another form of connection string (a socket: URL, a socket path), pass type: 'postgres' or use connectDatabase().

Optionalmobile

mobile?: CapacitorAdapterOptions

Mobile (Capacitor) configuration. Automatically detected on mobile platforms.

OptionalindexedDb

indexedDb?: IndexedDbAdapterOptions

IndexedDB configuration for browser-native persistence, passed on to the IndexedDB adapter whole (durability, crossTab and the rest). Uses sql.js (WASM) for SQL execution + IndexedDB for storage.

Example

const db = await createDatabase({
  priority: ['indexeddb', 'sqljs'],
  indexedDb: {
    dbName: 'my-app-db',
    sqlJsConfig: {
      locateFile: (file) => `/wasm/${file}`
    }
  }
});

Optionaltype

type?:
    | "sqlite"
    | "postgres"
    | "memory"
    | "browser"
    | "mobile"

Force a specific database type. Leave empty to auto-detect.

Optionalpriority

priority?: AdapterKind[]

Custom priority order for adapter selection. Advanced: Only use if you need fine-grained control.

Optionalstrict

strict?: boolean

Strict resolution, for servers: no local database stands in for a Postgres the options configure. Default: false.

  • A url or postgres option that names no server (no pool, no postgres:// or postgresql:// connection string, and no host, database or user) fails on Node instead of opening the local default, unless file is given.
  • A postgres candidate that fails ends resolution with an error, whatever priority lists after it.

DATABASE_URL in the environment does not count here, strict or not. See StorageResolutionOptions.strict for the resolver's side.

OptionalforeignKeys

foreignKeys?: boolean

SQLite: true turns foreign-key enforcement on and false turns it off when the adapter opens. On sql.js and IndexedDB it holds when sql.js reopens its connection (a save, an export, an import), as a PRAGMA foreign_keys statement run later does. Left out, each engine keeps its default: better-sqlite3 and the Capacitor plugin enforce foreign keys, sql.js and IndexedDB do not. PostgreSQL always enforces them and ignores this. On the resolver, pass openOptions: { foreignKeys: true }.

Optionalsegment

segment?: string

Keeps this database's tables apart from other users of the same database: a schema of its own on PostgreSQL, a file with the segment in its name on SQLite, a database name with the segment appended on IndexedDB and Capacitor. See StorageResolutionOptions.segment.

Example

// AgentOS's tables beside the app's, in one PostgreSQL database
const agentos = await createDatabase({ url: process.env.DATABASE_URL, segment: 'agentos' });

Optionallogger

logger?: StorageLogger

The logger for this call's resolver lines (pino's fits). Default: the one setStorageLogger() set, else the console.

Optionalhooks

hooks?: StorageHooks

Lifecycle hooks around every call of the adapter returned (see withHooks): each query, write, transaction and error, with the power to change a statement or a result, or to stop a call by returning undefined.

Settings

Member Visibility

On This Page

Properties