Configuration

The CLI reads schemic.config.ts from your project root. Author it with defineConfig for full type-checking; schemic init --driver postgres scaffolds one for you.

Config is connections-only: a map of named connections, each built by a driver’s connection factory. There is no top-level driver string — the driver is the factory you call.

schemic.config.ts TypeScript

import { defineConfig } from "@schemic/core/config";
import { postgresConnection } from "@schemic/postgres/connection";

export default defineConfig({
  connections: {
    default: postgresConnection({
      schema: "./database/schema",
      // PGlite (embedded): `file:<dir>` is a persistent data dir; "" is in-memory.
      url: process.env.DATABASE_URL ?? "file:./.pgdata",
    }),
  },
});

Top-level

Option	Type	Description
`connections`	record	A map of named connections. The CLI uses `default` unless told otherwise; add more for multi-database setups.

Each entry comes from a driver factory — postgresConnection(...) from @schemic/postgres/connection. defineConfig is imported from @schemic/core/config.

`postgresConnection(...)`

Field	Type	Description
`schema`	string	Directory of schema modules, loaded recursively. Usually `./database/schema`.
`url`	string?	Where to connect — a PGlite data directory or in-memory (see below). Omitted means in-memory.
`migrations`	string?	Directory of `.sql` migrations and their `meta/` snapshot. Defaults relative to `schema`.
`key`	string?	An identifier for this connection, when resolving a keyed collection.

You can also pass a resolver function that yields a config (or a keyed collection of configs) instead of a static object.

The `url`: PGlite data directories

The driver runs on embedded PGlite, and url selects where its data lives:

`url`	Behaviour
`"file:./.pgdata"`	A persistent PGlite data directory on disk. The `file:` prefix is what makes it persist.
`""`, omitted, or a bare path	An in-memory PGlite database, fresh each run. A bare path like `"./.pgdata"` (no `file:`) silently runs in-memory — only a `file:`-prefixed url persists.
`"postgres://…"`	Rejected. `connect` fails loud — hosted Postgres over `postgres://` is not supported yet (a node-postgres client is planned). Use `file:<dir>` for persistence, or `""`/omit for in-memory.

Environment variables

Values are explicit — read environment variables yourself in the config (process.env.DATABASE_URL ?? "…"), as the scaffold does. There is no implicit magic. The companion .env.example documents the convention:

Shell

# A real Postgres server (reserved — uncomment once the node-postgres client lands):
# DATABASE_URL=postgres://user:pass@localhost:5432/app

Where to go next

CLI commands — the commands that read this config.
Generate & run migrations — the config in the workflow.
Quickstart — the scaffolded config in context.