Quickstart

Create a project

create schemic is interactive: it asks for a project directory and a database driver, installs everything, and scaffolds your project. Run it in an empty directory for a new project, or inside an existing one — it merges the @schemic dependencies and a db script into your package.json without touching the rest of your setup. For the SurrealDB driver it scaffolds:

• schemic.config.ts — where your database connection lives
• database/schema/tables/user.ts — a sample user table
• database/seed/index.ts — the seed script
• database/migrations/meta/_snapshot.json — migration state
• .env.example — connection environment template

Start a local SurrealDB

In a second terminal, start an in-memory database with root credentials that match the scaffolded config:

surreal start --user root --pass root memory

Leave it running. The scaffolded schemic.config.ts connects to ws://127.0.0.1:8000/rpc with namespace app and database app, which is exactly what this command serves.

The config reads its credentials from the environment, so copy the generated template to .env (it already has the matching root / root values):

cp .env.example .env

Read the generated schema

Open database/schema/tables/user.ts. This is the single source of truth; the DDL below is derived from it.

import { s, defineTable, surql } from "@schemic/surrealdb";

export const User = defineTable("user", {
  name: s.string().$assert(surql`string::len($value) > 0`),
  email: s.email().$unique(),
  createdAt: s.datetime().$default(surql`time::now()`).$readonly(),
}).schemafull();

It generates this DDL:

DEFINE TABLE user TYPE NORMAL SCHEMAFULL;
DEFINE FIELD name ON TABLE user TYPE string ASSERT string::len($value) > 0;
DEFINE FIELD email ON TABLE user TYPE string ASSERT string::is_email($value);
DEFINE INDEX user_email_idx ON TABLE user FIELDS email UNIQUE;
DEFINE FIELD createdAt ON TABLE user TYPE datetime DEFAULT time::now() READONLY;

A few things to notice, each of which you will use constantly:

• s.email() emits an ASSERT string::is_email($value) constraint, and .$unique() adds a UNIQUE INDEX — both enforced by SurrealDB on write.
• .$assert(surql…) on name adds a custom constraint (here, a non-empty check).
• s.datetime() is a codec field: a Date in your TypeScript code, a datetime on the wire.
• .$default(...) sets a database-side DEFAULT — here time::now(), written with the surql tag — and .$readonly() marks the field READONLY.

Generate your first migration

schemic gen diffs your schema against the recorded snapshot and writes a reviewable migration for the difference:

npx schemic gen initial

The migration is a single SurrealQL file with an up and down branch — idempotent DEFINE … OVERWRITE to apply, REMOVE to roll back. Open it before applying anything:

-- 20260613090000_initial
-- Generated by @schemic/core. Review before applying.

IF $direction = "up" {
    DEFINE TABLE OVERWRITE user TYPE NORMAL SCHEMAFULL;
    DEFINE FIELD OVERWRITE name ON TABLE user TYPE string ASSERT string::len($value) > 0;
    DEFINE FIELD OVERWRITE email ON TABLE user TYPE string ASSERT string::is_email($value);
    DEFINE FIELD OVERWRITE createdAt ON TABLE user TYPE datetime DEFAULT time::now() READONLY;
    DEFINE INDEX OVERWRITE user_email_idx ON TABLE user FIELDS email UNIQUE;
} ELSE {
    REMOVE TABLE IF EXISTS user;
};

You commit these files to version control.

Apply the migration

Confirm the state:

Your database now has the user table.

Evolve the schema

A schema change is an edit to your TypeScript. Add a post table next to user. Create database/schema/tables/post.ts:

import { s, defineTable, surql } from "@schemic/surrealdb";
import { User } from "./user";

export const Post = defineTable("post", {
  title: s.string().$assert(surql`string::len($value) > 0`),
  body: s.string(),
  author: User.record(),
  publishedAt: s.datetime().optional(),
  createdAt: s.datetime().$default(surql`time::now()`).$readonly(),
}).schemafull();

User.record() is a typed record link — a record<user> field on the wire — built from the imported User definition, so the table name lives only in user.ts. Generate and apply a migration for the change:

npx schemic gen add_posts
npx schemic migrate

gen writes a second migration containing only the new post table — it diffs against the snapshot, so it never re-defines user.

Read and write rows as typed values

Your schema also gives you codecs and types for app code. encode turns app values into a wire payload for a write; decode turns a database row back into app values.

import { Surreal } from "surrealdb";
import { User } from "./database/schema/tables/user";
import type { App } from "@schemic/surrealdb";

const db = new Surreal();
await db.connect("ws://127.0.0.1:8000/rpc", {
  namespace: "app",
  database: "app",
  authentication: { username: "root", password: "root" },
});

// encode() builds the wire payload — createdAt has a DB default, so you omit it.
// db.query returns one result set per statement, each an array of wire rows.
const [[created]] = await db.query<[unknown[]]>("CREATE user CONTENT $data", {
  data: User.encode({ name: "Ada Lovelace", email: "ada@example.com" }),
});

// decode() validates the returned row and converts wire values to app values.
const ada: App<typeof User> = User.decode(created);

console.log(ada.createdAt instanceof Date); // true — a Date, not a wire datetime

User.encode(...) is typed to the create shape (fields with a default are optional), and App<typeof User> is the decoded app type. The createdAt you read back is a JavaScript Date, decoded from the datetime SurrealDB stored.