> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# embed_schema! macro

Bake .surql schema into the Rust binary with embed_schema!.

The `embed_schema!` macro reads your `database/schema/` directory at compile time and generates a Rust module containing the SQL for every `.surql` file it finds. Because the schema is compiled into the binary, there are no external files to deploy and the schema version is always tied to the application version.

Add SurrealKit to your dependencies. The `embed_schema!` macro is re-exported from the main crate, so a single dependency is enough:

```toml
[dependencies]
surrealkit = "1.0.0-beta.1"
```

## Basic usage

Call the macro at the crate root (typically `main.rs` or `lib.rs`):

```rust
surrealkit::embed_schema!();
```

This generates an `embedded_schema` module. Call `sync` on it after connecting to apply any outstanding schema changes:

```rust
#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let db = surrealkit::connect(
        &surrealkit::DbCfg::from_env(None, &Default::default())?
    ).await?;

    embedded_schema::sync(&db).await?;

    // application startup continues here
    Ok(())
}
```

`sync` behaves identically to `surrealkit sync` from the CLI: it applies new or changed definitions and prunes any that have been removed, using the `__entity` metadata table to track state.

## What the macro generates

Given a `database/schema/` directory with these files:

```text
database/schema/
├── users.surql
└── orders.surql
```

The macro generates roughly:

```rust
pub mod embedded_schema {
    pub static SCHEMA: &[surrealkit::EmbeddedSchemaFile] = &[
        surrealkit::EmbeddedSchemaFile {
            path: "database/schema/users.surql",
            sql: "DEFINE TABLE user SCHEMAFULL; ...",
        },
        surrealkit::EmbeddedSchemaFile {
            path: "database/schema/orders.surql",
            sql: "DEFINE TABLE order SCHEMAFULL; ...",
        },
    ];

    pub async fn sync(
        db: &surrealkit::Surreal<surrealkit::engine::any::Any>,
    ) -> surrealkit::anyhow::Result<()> {
        surrealkit::Sync::embedded(SCHEMA).run(db).await
    }
}
```

The generated `SCHEMA` static is public, so when you need to customise sync behaviour you can pass it to the [`Sync`](/docs/manage/schema-migration/library.md) builder directly instead of calling `embedded_schema::sync`:

```rust
use surrealkit::Sync;

Sync::embedded(embedded_schema::SCHEMA)
    .prune(false)
    .run(&db)
    .await?;
```

## Embedding several modules

_(since v1.0)_

A project split into [schema modules](/docs/manage/schema-migration/modules-and-targets.md) names each one and the directory it comes from:

```rust
surrealkit::embed_schema!(
    core    = "database/modules/core/schema",
    billing = "database/modules/billing/schema",
);
```

This generates a submodule per arm, alongside a top-level `sync` that applies all of them:

```rust
embedded_schema::sync(&db).await?;           // every module, in declaration order
embedded_schema::billing::sync(&db).await?;  // one module
```

Order the arms so that a module follows the ones it depends on. `embedded_schema::sync` exists in both the single- and named-module forms, so moving from one module to several needs no change at the call site. `embed_schema!()` and `embed_schema!("dir")` are unchanged.

## Embedding seed files

`embed_seed!` is the counterpart for [seed data](/docs/manage/schema-migration/seeding.md), reading `database/seed/**/*.surql` at compile time:

```rust
surrealkit::embed_seed!();

embedded_seed::seed(&db).await?;
```

Embedded seeds are tracked in `__seed` exactly as filesystem seeds are, so each file runs once even though the application calls this on every start.

## Compile-time rebuild behaviour

Cargo re-runs the macro whenever a `.surql` file in `database/schema/` changes, because the macro registers each file with `include_str!`. This means schema changes always produce a fresh build, and there is no risk of shipping stale SQL.

> [!WARNING]
> `include_str!` registers the files that exist when the macro runs, so the directory listing itself is not tracked. **Adding** a `.surql` file does not trigger a rebuild, and the new file is silently absent from the binary. Add a `build.rs` to cover that:
>
> ```rust
> fn main() {
>     println!("cargo:rerun-if-changed=database");
> }
> ```

## When to use the macro vs runtime loading

|-| `embed_schema!` | Runtime `Sync` |
|---|---|---|
| Schema location | Compiled into binary | Built from files at runtime |
| Deployment | No schema files needed | Schema directory must be present |
| Dev iteration | Rebuild required on change | Files can be swapped without rebuild |
| Best for | Production builds, Docker images | Development, mounted volumes |

For most production deployments `embed_schema!` is the right choice. For local development or environments that mount schema as a volume, building an `EmbeddedSchemaFile` slice at runtime and passing it to [`Sync::embedded`](/docs/manage/schema-migration/library.md) is more convenient.