Vespertide

Declarative database schema management. Define your schemas in JSON, and Vespertide automatically generates migration plans and SQL from model diffs.

Features

• Declarative Schema: Define your desired database state in JSON files
• Automatic Diffing: Vespertide compares your models against applied migrations to compute changes
• Migration Planning: Generates typed migration actions (not raw SQL) for safety and portability
• Multi-Database Support: PostgreSQL, MySQL, SQLite
• Enum Types: Native string enums and integer enums (no migration needed for new values)
• Zero-Runtime Migrations: Compile-time macro generates database-specific SQL
• JSON Schema Validation: Ships with JSON Schemas for IDE autocompletion and validation
• ORM Export: Export schemas to SeaORM, SQLAlchemy, SQLModel
• Language Server: First-class editor support via the bundled vespertide-lsp — see LSP Features below

What's new in 0.2.0

API stability pass with a byte-identical JSON wire format — existing models and migration files load unchanged.

• Newtype identifiers: TableName, ColumnName, IndexName in vespertide-core (crates/vespertide-core/src/schema/names.rs). #[serde(transparent)] keeps JSON identical; Deref<Target = str> means most call sites need no edit.
• #[non_exhaustive] configs: VespertideConfig, SeaOrmConfig, and MigrationOptions must be built with ..Default::default() (or MigrationOptions::new()), so future fields don't break semver.
• Decomposed QueryError: new InvalidColumnType, SchemaError, BackendError, and UnsupportedAction variants. QueryError::Other(String) is #[deprecated] but still compiles.
• Cloneable MigrationError: backed by Arc<dyn Error>, so retry loops can re-emit errors without re-running the planner.
• Faster LSP: every editor hot path (diagnostics, symbols, drift) is now RingCache-backed in vespertide-lsp. No API change; -99% latency on the synthetic tools/lsp-profile/ workload.
• Quality policy: every #[allow(...)] migrated to #[expect(LINT, reason = "...")]; workspace lints reject reason-less allows going forward.

LSP Features

The vespertide-lsp binary ships with VSCode and Zed extensions (apps/vscode-extension/, apps/zed-extension/). It implements 13 LSP capabilities tuned for Vespertide schema files:

Installation

cargo install vespertide-cli

Quick Start

# Initialize a new project
vespertide init

# Create a model template
vespertide new user

# Edit models/user.json, then check changes
vespertide diff

# Preview the SQL
vespertide sql

# Generate a migration file
vespertide revision -m "create user table"

CLI Commands

Model Definition

Models are JSON files in the models/ directory. Always include $schema for IDE validation:

{
  "$schema": "https://raw.githubusercontent.com/dev-five-git/vespertide/refs/heads/main/schemas/model.schema.json",
  "name": "user",
  "columns": [
    { "name": "id", "type": "integer", "nullable": false, "primary_key": true },
    { "name": "email", "type": "text", "nullable": false, "unique": true, "index": true },
    { "name": "name", "type": { "kind": "varchar", "length": 100 }, "nullable": false },
    { 
      "name": "status", 
      "type": { "kind": "enum", "name": "user_status", "values": ["active", "inactive", "banned"] },
      "nullable": false,
      "default": "'active'"
    },
    { "name": "created_at", "type": "timestamptz", "nullable": false, "default": "NOW()" }
  ]
}

Column Types

Simple Types:

Complex Types:

{ "kind": "varchar", "length": 255 }
{ "kind": "char", "length": 2 }
{ "kind": "numeric", "precision": 10, "scale": 2 }
{ "kind": "enum", "name": "status", "values": ["active", "inactive"] }
{ "kind": "custom", "custom_type": "TSVECTOR" }

Enum Types (Recommended)

Use enums instead of text columns for status fields and categories:

String Enum (PostgreSQL native enum):

{
  "name": "status",
  "type": { "kind": "enum", "name": "order_status", "values": ["pending", "shipped", "delivered"] },
  "nullable": false,
  "default": "'pending'"
}

Integer Enum (stored as INTEGER, no DB migration needed for new values):

{
  "name": "priority",
  "type": {
    "kind": "enum",
    "name": "priority_level",
    "values": [
      { "name": "low", "value": 0 },
      { "name": "medium", "value": 10 },
      { "name": "high", "value": 20 }
    ]
  },
  "nullable": false,
  "default": 10
}

Inline Constraints (Preferred)

Define constraints directly on columns instead of using table-level constraints:

{
  "name": "author_id",
  "type": "integer",
  "nullable": false,
  "foreign_key": {
    "ref_table": "user",
    "ref_columns": ["id"],
    "on_delete": "cascade"
  },
  "index": true
}

Reference Actions (snake_case): "cascade", "restrict", "set_null", "set_default", "no_action"

Composite Primary Key (inline):

{ "name": "user_id", "type": "integer", "nullable": false, "primary_key": true },
{ "name": "role_id", "type": "integer", "nullable": false, "primary_key": true }

Table-level constraints are only needed for CHECK expressions:

"constraints": [
  { "type": "check", "name": "check_positive", "expr": "amount > 0" }
]

See SKILL.md for complete documentation.

Migration Files

Important: Migration files are auto-generated. Never create or edit them manually.

# Always use the CLI to create migrations
vespertide revision -m "add status column"

The only exception is adding fill_with values when prompted (for NOT NULL columns without defaults).

Supported Databases

ORM Export

vespertide export --orm seaorm      # Rust - SeaORM entities
vespertide export --orm sqlalchemy  # Python - SQLAlchemy models
vespertide export --orm sqlmodel    # Python - SQLModel (FastAPI)

Runtime Migrations (Macro)

Use the vespertide_migration! macro to run migrations at application startup:

[dependencies]
vespertide = "0.2"
sea-orm = { version = "2.0.0-rc", features = ["sqlx-postgres", "runtime-tokio-native-tls", "macros"] }

use sea_orm::Database;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let db = Database::connect("postgres://user:pass@localhost/mydb").await?;
    vespertide::vespertide_migration!(db).await?;
    Ok(())
}

The macro generates database-specific SQL at compile time for zero-runtime overhead.

Architecture

vespertide/
├── vespertide-core      # Data structures (TableDef, ColumnDef, MigrationAction)
├── vespertide-planner   # Schema diffing and migration planning
├── vespertide-query     # SQL generation (PostgreSQL, MySQL, SQLite)
├── vespertide-cli       # Command-line interface
├── vespertide-exporter  # ORM code generation
├── vespertide-macro     # Compile-time migration macro
└── vespertide-config    # Configuration management

How It Works

1. Define Models: Write table definitions in JSON files with $schema for validation
2. Replay Migrations: Applied migrations are replayed to reconstruct the baseline schema
3. Diff Schemas: Current models are compared against the baseline
4. Generate Plan: Changes are converted into typed MigrationAction enums
5. Emit SQL: Migration actions are translated to database-specific SQL

Error Handling

vespertide-query returns a typed, #[non_exhaustive] QueryError so callers can react to each failure category without string-matching:

use vespertide_query::QueryError;

fn report(err: QueryError) {
    match err {
        QueryError::SchemaError(msg) => {
            eprintln!("schema is inconsistent: {msg}");
        }
        QueryError::InvalidColumnType { backend, message } => {
            eprintln!("cannot map column type for {backend:?}: {message}");
        }
        // Other variants (UnsupportedConstraint, BackendError, UnsupportedAction,
        // deprecated Other) handled elsewhere; `#[non_exhaustive]` requires a
        // wildcard arm.
        _ => {}
    }
}

Configuration

vespertide.json:

{
  "modelsDir": "models",
  "migrationsDir": "migrations",
  "tableNamingCase": "snake",
  "columnNamingCase": "snake",
  "modelFormat": "json"
}

Migration timeouts (optional)

Protect runtime migrations (the vespertide_migration! macro) from hanging on a lock or a runaway statement. Both are optional, in milliseconds, and omitted by default (no timeout applied):

{
  "lockTimeoutMs": 5000,
  "statementTimeoutMs": 30000
}

When set, the macro emits a backend-appropriate timeout at the start of the migration session:

Development

cargo build                              # Build
cargo test                               # Test
cargo clippy --all-targets --all-features # Lint
cargo fmt                                # Format
cargo run -p vespertide-schema-gen -- --out schemas  # Regenerate JSON Schemas

Quality & Maintenance

Workspace lints are enforced in CI; the migration from #[allow] to #[expect] (and the rationale) is tracked in docs/clippy-allow-audit.md.

License

Apache-2.0