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 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.

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