Configuration

The CLI reads schemic.config.ts from your project root. Author it with defineConfig for full type-checking; schemic init 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 { surrealConnection } from "@schemic/surrealdb/connection";

export default defineConfig({
  connections: {
    default: surrealConnection({
      schema: "./database/schema",
      url: process.env.SURREAL_URL ?? "ws://127.0.0.1:8000/rpc",
      namespace: process.env.SURREAL_NAMESPACE ?? "app",
      database: process.env.SURREAL_DATABASE ?? "app",
      username: process.env.SURREAL_USER,
      password: process.env.SURREAL_PASS,
      authLevel: "root", // "root" | "namespace" | "database"
    }),
  },
});

Top-level

OptionTypeDescription
connectionsrecordA map of named connections. The CLI uses default unless told otherwise; add more for multi-tenant or multi-database setups.

Each entry comes from a driver factory — surrealConnection(...) from @schemic/surrealdb/connection (other drivers export their own, e.g. postgresConnection).

surrealConnection(...)

FieldTypeDescription
schemastringDirectory of schema modules, loaded recursively. Usually ./database/schema.
urlstringEndpoint, e.g. ws://127.0.0.1:8000/rpc.
namespacestringTarget namespace.
databasestringTarget database.
usernamestring?Auth username.
passwordstring?Auth password.
authLevel"root" | "namespace" | "database"Level to sign in at. Default root.
migrationsstring?Directory of .surql migrations and their meta/ snapshot. Defaults relative to schema.
checkobject?schemic check replay overrides — see below.

Environment variables

Values are explicit — read environment variables yourself in the config (process.env.SURREAL_URL ?? "…"), as the scaffold does. There is no implicit SURREAL_* magic; the names are a convention you choose. The companion .env.example documents them:

Shell 
SURREAL_URL=ws://127.0.0.1:8000/rpc
SURREAL_NAMESPACE=app
SURREAL_DATABASE=app
SURREAL_USER=root
SURREAL_PASS=root

CLI flags (--url, --namespace, …) override the resolved connection per command.

Check replay (check)

schemic check replays your migrations in a throwaway engine and confirms they reproduce your schema. Set it per connection with check.engine:

engineBehaviour
"auto" (default)Use the local surreal CLI for an ephemeral in-memory instance if present; otherwise fall back to a server.
"binary"Require the local surreal CLI; error if missing.
"remote"Always use a server, creating and dropping throwaway scratch databases.
{ backend, … }Run in-process via the optional @surrealdb/node package.

Alongside engine, check accepts binary (path to the surreal CLI, for the auto/binary engines) and db (a partial connection the remote engine uses for its throwaway scratch databases). The embedded object takes backend (memory — the default — surrealkv, surrealkv+versioned, or rocksdb), an optional path for the persistent backends, plus capabilities, strict, and query/transaction timeouts.

TypeScript 
default: surrealConnection({
  schema: "./database/schema",
  url: process.env.SURREAL_URL ?? "ws://127.0.0.1:8000/rpc",
  namespace: "app",
  database: "app",
  // Always replay against a scratch server, never production:
  check: { engine: "remote", db: { url: "ws://localhost:8000", namespace: "scratch" } },
}),

Where to go next