Database Drivers

ObjectStack supports multiple database backends through a unified driver interface. Drivers can be selected in two ways:

1. Env var only — auto-inferred from the URL scheme (the simplest path):

   export OS_DATABASE_URL=mongodb://localhost:27017/myapp   # → MongoDB
   export OS_DATABASE_URL=postgres://user:pass@host/db      # → PostgreSQL
   export OS_DATABASE_URL=mysql://user:pass@host/db         # → MySQL
   export OS_DATABASE_URL=libsql://mydb.turso.io            # → Turso / libSQL
   export OS_DATABASE_URL=file:./data/app.db                # → SQLite
   pnpm dev

   The CLI inspects the connection-string scheme and picks the right driver automatically. You only need to set OS_DATABASE_DRIVER when you want to override the inference (e.g. force sqlite for an ambiguous path).

2. Programmatic in objectstack.config.ts:

   import { defineStack } from '@objectstack/spec';
   import { SqlDriver } from '@objectstack/driver-sql';
   
   export default defineStack({
     manifest: { /* ... */ },
     driver: new SqlDriver({
       client: 'pg',
       connection: process.env.DATABASE_URL,
     }),
   });

URL → Driver Inference Table

Supported Drivers

All SQL flavours (PostgreSQL / MySQL / SQLite) are served by a single @objectstack/driver-sql package — there is no separate driver-postgres, driver-mysql, or driver-sqlite package. Pick the Knex client name (pg / mysql2 / better-sqlite3) when you instantiate SqlDriver.

PostgreSQL (via @objectstack/driver-sql)

pnpm add @objectstack/driver-sql pg

SqlDriver's constructor accepts a Knex Knex.Config object verbatim.

import { SqlDriver } from '@objectstack/driver-sql';

new SqlDriver({
  client: 'pg',
  connection: {
    host: 'db.example.com',
    port: 5432,
    user: 'admin',
    password: process.env.DB_PASSWORD,
    database: 'myapp',
    ssl: true,
  },
  pool: { min: 2, max: 10 },
});

Or via env var alone (driver inferred from postgres:// scheme):

export OS_DATABASE_URL=postgres://admin:secret@db.example.com:5432/myapp

MongoDB

Configuration properties for the MongoDB driver.

Example (config):

import { MongoDBDriver } from '@objectstack/driver-mongodb';

datasources: {
  default: {
    driver: 'mongodb',
    url: 'mongodb+srv://admin:secret@cluster.mongodb.net/myapp',
    readPreference: 'nearest',
    maxPoolSize: 50,
  },
}

Example (env-var, recommended for objectstack dev / objectstack serve):

export OS_DATABASE_URL=mongodb://localhost:27017/myapp
pnpm dev

The CLI infers the MongoDB driver from the mongodb:// (or mongodb+srv://) URL scheme automatically — no OS_DATABASE_DRIVER needed. Set OS_DATABASE_DRIVER=mongodb only if you want to be explicit.

SQLite (via @objectstack/driver-sql)

SQLite is ideal for local-first development and embedded applications. It uses the same SqlDriver class with client: 'better-sqlite3'.

pnpm add @objectstack/driver-sql better-sqlite3

import { SqlDriver } from '@objectstack/driver-sql';

new SqlDriver({
  client: 'better-sqlite3',
  connection: { filename: './data/app.db' },
  useNullAsDefault: true,
});

Env-var path (driver inferred from file: / :memory: / .db paths):

export OS_DATABASE_URL=file:./data/app.db
# or
export OS_DATABASE_URL=:memory:

Memory Driver

The in-memory driver stores data in a JavaScript Map. Data is lost when the process exits. This is the default driver auto-registered by objectstack dev when no OS_DATABASE_DRIVER is set and no driver is provided programmatically.

import { InMemoryDriver } from '@objectstack/driver-memory';

new InMemoryDriver();

apps/objectos and Single-Project Local Mode

When running apps/objectos (or any boot stack with runtime: { cloudUrl: 'local' }), two databases are involved:

Both honor the same URL-scheme inference described above. If OS_CONTROL_DATABASE_URL is unset, the control DB defaults to a local SQLite file (<dataDir>/control.db); for backward compatibility OS_DATABASE_URL is also accepted as a fallback for the control DB when no explicit OS_CONTROL_DATABASE_URL is provided and no project DB URL has consumed it.

# Run apps/objectos with MongoDB as the project DB (control DB stays sqlite):
OS_DATABASE_URL=mongodb://localhost:27017/objectos pnpm dev

# Pin both DBs explicitly:
OS_DATABASE_URL=mongodb://localhost:27017/objectos \
OS_CONTROL_DATABASE_URL=postgres://user:pass@host/control \
pnpm dev

Multi-Datasource

ObjectStack supports multiple data sources. Objects can target specific datasources:

import { SqlDriver } from '@objectstack/driver-sql';
import { MongoDBDriver } from '@objectstack/driver-mongodb';

export default defineStack({
  datasources: {
    primary:   new SqlDriver({ client: 'pg', connection: process.env.PG_URL }),
    analytics: new SqlDriver({ client: 'pg', connection: process.env.ANALYTICS_URL }),
    cache:     new MongoDBDriver({ url: process.env.MONGO_URL! }),
  },
});

Then in your object definition:

export const AuditLog = ObjectSchema.create({
  name: 'audit_log',
  datasource: 'analytics', // Routes to the analytics database
  fields: { /* ... */ },
});