New databases

If you are starting a new project, SurrealKit can manage your schema from the very first definition. This guide walks through initialising a project, writing your first schema file, and pushing it to a local SurrealDB instance.

1. Initialise the project

In the root of your repository, run:

surrealkit init

This creates a database/ directory with the following layout:

database/
├── schema/
├── seed/
├── tests/
└── rollouts/

2. Write a schema file

Create a .surql file inside database/schema/. Each file can contain one or more DEFINE statements.

-- database/schema/users.surql
DEFINE TABLE user SCHEMAFULL;
DEFINE FIELD email ON user TYPE string ASSERT string::is_email($value);
DEFINE FIELD created_at ON user TYPE datetime DEFAULT time::now();
DEFINE INDEX unique_email ON user FIELDS email UNIQUE;

Schema files can be organised by table, by domain, or kept in a single file. SurrealKit applies everything in database/schema/ together.

3. Start a local SurrealDB instance

surreal start --user root --pass secret

4. Sync your schema

surrealkit --user root --pass secret sync

SurrealKit reads every file in database/schema/, applies the DEFINE statements to the database, and records a content hash for each file in an internal __entity metadata table. Future syncs only re-apply files that have changed.

5. Enable watch mode during development

Pass --watch to keep SurrealKit running and automatically re-sync whenever a schema file changes:

surrealkit --user root --pass secret sync --watch

Vite integration

If your project uses Vite, the vite-plugin-surrealkit package runs sync automatically when the dev server starts:

npm install --save-dev vite-plugin-surrealkit

// vite.config.ts
import { defineConfig } from 'vite';
import { surrealkitPlugin } from 'vite-plugin-surrealkit';

export default defineConfig({
    plugins: [
        surrealkitPlugin(),
    ],
});

The plugin watches database/schema/**/*.surql and re-syncs on any change, with debouncing to avoid overlapping runs.

Storing connection details

Rather than passing flags on every command, store your local connection details in a .env file at the project root:

SURREALDB_HOST=http://localhost:8000
SURREALDB_NAMESPACE=dev
SURREALDB_NAME=myapp
SURREALDB_USER=root
SURREALDB_PASSWORD=secret

With those set, surrealkit sync picks them up automatically.

Next steps

• •

  Sync: full reference for all sync options

• •

  Sync vs Rollouts: when to move from Sync to the Rollouts workflow