surrealdb-migrations

The project follows a philosophy that divides a SurrealDB migration project into three distinct categories to manage the evolution of the database:

1. Schemas (/schemas folder): Represents the Query model. Each file represents no more than one SurrealDB table. This folder provides a view of the current data model.
2. Events (/events folder): Represents the Command model. Each file represents no more than one SurrealDB event and its underlying table. This folder shows the different ways to update the data model.
3. Migrations (/migrations folder): Represents changes in the SurrealDB data itself (e.g., renaming columns, dropping tables, or adding default values). These files are applied to transition the database between schema states.

The database branching feature requires the existence of three specific namespaces in your SurrealDB instance. It is strongly recommended to avoid using these namespaces for other purposes to prevent conflicts:

• features
• branches
• branches/origin

By default, migrations are forward-only. To undo changes, you must provide a "down" migration.

Backward Migration Formats

Backward migrations can be stored in one of two ways:

1. In a /migrations/down folder with the same name as the forward migration.
2. In the /migrations folder with a .down.surql extension (e.g., 20230317_153201_AddAdminUser.down.surql).

Reverting via CLI

To revert migrations back to a specific point:

surrealdb-migrations apply --down <TIMESTAMP_NAME>

Example:

surrealdb-migrations apply --down 20231605_205201_AddProduct

To undo all migrations:

surrealdb-migrations apply --down 0

To prepare your application for production, run the build command. You can then use the preview command to test the production build locally.

# Create a production version of your app
npm run build

# Preview the production build
npm run preview

Use npm create svelte@latest to scaffold a new Svelte project. You can either initialize the project in the current directory or specify a directory name.

# create a new project in the current directory
npm create svelte@latest

# create a new project in my-app
npm create svelte@latest my-app

To start a new Rust and WebAssembly project using this template, use cargo generate. This will clone the template and allow you to specify a project name.

cargo generate --git https://github.com/rustwasm/wasm-pack-template.git --name my-project
cd my-project

After creating the project and installing dependencies (using npm install, pnpm install, or yarn), start the development server. You can use the --open flag to automatically open the application in a new browser tab.

npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open

To commit and merge changes from a branch back to the original branch, use the surrealdb-migrations branch merge command.

Merge Modes:

Example: surrealdb-migrations branch merge <BRANCH_NAME> --mode <MODE> --address <ADDRESS>

surrealdb-migrations branch merge bright-fold-1617 --mode all --address http://localhost:8000

Once scaffolded, you can generate new files using the CLI:

Create a Schema

Creates a table with predefined fields. By default, it uses SCHEMALESS unless configured otherwise.

surrealdb-migrations create schema <NAME> --fields <FIELD1>,<FIELD2>...

Create an Event

Creates an event and its underlying table.

surrealdb-migrations create event <NAME> --fields <FIELD1>,<FIELD2>...

Create a Migration

Creates a new migration file prefixed with the current date and time (e.g., 20230317_153201_Name.surql).

surrealdb-migrations create <NAME>

To include a corresponding "down" migration file immediately, use the --down flag:

surrealdb-migrations create <NAME> --down

surrealdb-migrations create schema post --fields title,content,author,created_at,status

To start a new migration project, use the scaffold command with a template. The empty template creates the basic directory structure: /schemas, /events, and /migrations (including a script_migration.surql file).

Available templates:

• empty: A clean schema with a script_migration table to track applied migrations.
• blog: A blog domain model (users, posts, comments).
• ecommerce: An ecommerce domain model (customers, products).

Use the following command:

surrealdb-migrations scaffold template <TEMPLATE>

surrealdb-migrations scaffold template empty

You can apply migrations using the CLI or programmatically within a Rust application.

Using the CLI

surrealdb-migrations apply

Using the Rust API

Use MigrationRunner to apply migrations to a connected surrealdb::engine::any::Connection.

use surrealdb_migrations::MigrationRunner;
use surrealdb::engine::any::connect;
use surrealdb::opt::auth::Root;

#[tokio::main]
async fn main() -> Result<()> {
    let db = connect("ws://localhost:8000").await?;

    db.signin(Root {
        username: "root",
        password: "root",
    }).await?;

    db.use_ns("namespace").use_db("database").await?;

    // Apply all migrations
    MigrationRunner::new(&db)
        .up()
        .await
        .expect("Failed to apply migrations");

    Ok(())
}