# Sync

Sync pushes your .surql schema files to SurrealDB immediately, keeping the database in desired state. Use it for local development and ephemeral environments.

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

```bash
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:

```bash
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:

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

Do not use this flag routinely on shared databases. Consider switching to [Rollouts](/docs/manage/schema-migration/rollouts.md) 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`:

```bash
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](/docs/manage/schema-migration/getting-started/new-databases.md) or [rollout steps](/docs/manage/schema-migration/rollouts.md) rather than schema files.

## Metadata tables

SurrealKit creates two internal tables in the target database:

| Table | Purpose |
|---|---|
| `__entity` | Stores the content hash and file key for every schema definition SurrealKit manages. Used to detect changes and drive pruning. |
| `__rollout` | Stores rollout state. Created when you first use Rollouts; may be present even if you use Sync only. |

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:

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

```ts
// 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

| Flag | Default | Description |
|---|---|---|
| `--watch` | off | Re-sync automatically when schema files change |
| `--allow-shared-prune` | off | Permit pruning on a database that already has SurrealKit metadata |
| `--allow-all-statements` | off | Permit non-`DEFINE` statements (e.g. `INSERT`, `UPDATE`, `CREATE`) in schema files; disables catalog entity tracking |
| `--dry-run` | off | Print what would be applied without modifying the database |
| `--fail-fast` | off | Stop on the first error rather than continuing |

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