surreal-codegen

surreal-codegen is the maintained generator fork used by Hey Murph. It started from @sebastianwessel/surql-gen, then was adapted for SurrealDB v3 and a schemaful, generated-client-first workflow.

The package publishes as surreal-codegen. The GitHub repository is still patgpt/surreal-client until the repo rename lands.

Docs

• Changelog
• Publishing Guide
• Contributing
• User Docs

What It Does

• reads a single SurrealQL schema file or a schema directory
• spins up a temporary SurrealDB instance for schema-file introspection
• connects to a running SurrealDB instance for live introspection
• generates Zod schemas
• generates a typed TypeScript client and repository helpers

Install

Run directly:

bunx surreal-codegen

Install as a dev dependency:

bun add -D surreal-codegen

The package also keeps the upstream-compatible surql-gen bin alias:

bunx surql-gen

Usage

Generate from a running database:

bunx surreal-codegen \
  --surreal http://localhost:8000 \
  --username root \
  --password root \
  --ns test \
  --db test

Generate from a schema file:

bunx surreal-codegen -f ./schema.surql

Generate from a schema directory:

bunx surreal-codegen -f ./db/schema

Generate without the TypeScript client:

bunx surreal-codegen -f ./schema.surql --no-client

Configuration

You can configure the generator with CLI flags, a config file, or both. CLI values win.

The default JSON config filename is surreal-codegen.config.json for compatibility with the upstream tool.

Example:

{
  "schemaFile": "./schema",
  "surreal": "http://localhost:8000",
  "username": "root",
  "password": "root",
  "ns": "test",
  "db": "test",
  "outputFolder": "./client_generated",
  "generateClient": true,
  "surrealImage": "surrealdb/surrealdb:latest"
}

How It Works

Schema-file mode

When you pass -f with a file or directory, the generator:

1. starts a temporary SurrealDB container with Testcontainers
2. loads your schema into that database
3. introspects the resulting definitions
4. writes generated Zod schemas and optional client files

Docker is required for this path.

Live-database mode

When you omit -f, the generator connects to the database specified by --surreal, --ns, --db, and auth flags, then introspects that database directly.

Output Structure

• _generated/: regenerated output and record helpers
• schema/: schema wrappers and customization points
• client/: CRUD and repository helpers for generated tables

Development

Install dependencies:

bun install

Run the full validation pass:

bun run ci

Useful individual commands:

bun run lint
bun run lint:fix
bun run typecheck
bun run test
bun run build
bun run pack:dry-run

Release Notes

• npm and JSR publishing steps live in PUBLISHING.md
• the manual GitHub Actions release flow lives in .github/workflows/release-manual.yml
• package.json and jsr.json versions must stay in sync
• the current GitHub repository is patgpt/surreal-client even though the package name is surreal-codegen