Sync

Sync applies all .surql files in database/schema/ to the connected SurrealDB database in a single pass, bringing the database into alignment with your files. It tracks each file by content hash so that unchanged files are skipped on subsequent runs.

Basic usage

surrealkit sync --user root --pass secret

SurrealKit connects to the database, reads your schema files, applies any definitions that have changed, and removes definitions for files that have been deleted (pruning).

Watch mode

During active development, pass --watch to keep SurrealKit running and automatically re-sync on any file change:

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

SurrealKit debounces rapid consecutive saves, so editing multiple files in quick succession triggers a single sync rather than many overlapping ones.

How it works

When Sync runs:

1. All .surql files in database/schema/ are read and their content hashes computed.

2. Hashes are compared against the __entity metadata table stored in the database.

3. New or changed files have their SQL statements applied.

4. Files that existed in a previous sync but are no longer present are pruned: their definitions are removed from the database.

5. The __entity table is updated to reflect the new state.

Any definition that exists in the database but not in a file will be removed on the next sync. Pruning emits REMOVE … IF EXISTS, so a tracking entry that points at an object which is already gone no longer errors: drift between SurrealKit's metadata and the database self-heals on the next sync.

Tracked schema objects

Sync manages the full range of SurrealDB schema definitions, tracking each one in the __entity table so it can be updated and pruned. This includes TABLE, FIELD, INDEX, ANALYZER, PARAM, FUNCTION, ACCESS, and USER definitions, as well as BUCKET, SEQUENCE, CONFIG, MODEL, and MODULE.

Pruning on shared databases

Pruning is safe when you are the sole owner of the database. On a shared database (one already containing SurrealKit metadata from another developer or environment), automatic pruning could remove definitions that others have added.

SurrealKit detects this situation and refuses to prune unless you pass an explicit flag:

surrealkit sync --allow-shared-prune --user root --pass secret

Do not use this flag routinely on shared databases. Consider switching to Rollouts for any database that more than one person or service writes to.

Running non-DEFINE statements

By default, schema files may only contain DEFINE statements. To allow other statements such as INSERT, UPDATE, or CREATE in your schema files, pass --allow-all-statements:

surrealkit sync --allow-all-statements --user root --pass secret

This disables catalog entity tracking for the run: SurrealKit can no longer reason about individual objects, so only file-level content hashes are tracked. Pruning of individual definitions is unavailable while this flag is in effect. Prefer keeping data changes in seed files or rollout steps rather than schema files.

Metadata tables

SurrealKit creates two internal tables in the target database:

These tables are managed by SurrealKit and should not be modified directly.

Vite plugin

If you are using Vite, the vite-plugin-surrealkit package integrates Sync with the dev server:

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({
            syncArgs: [],
        }),
    ],
});

On vite dev, the plugin:

1. Runs surrealkit sync once at startup.

2. Watches database/schema/**/*.surql.

3. Re-runs sync on any file change, debouncing concurrent runs.

Reference

The schema root defaults to ./database. Override it with the global --folder flag or the SURREALDB_FOLDER environment variable.