embed_schema! macro

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:

[dependencies]
surrealkit = "0.7"

Basic usage

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

surrealkit::embed_schema!();

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

#[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:

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

The macro generates roughly:

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 builder directly instead of calling embedded_schema::sync:

use surrealkit::Sync;

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

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.

When to use the macro vs runtime loading

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 is more convenient.