qail

Schema-first database toolkit — Pull, diff, migrate, validate.

[!CAUTION] Release Candidate: QAIL is now in the release-candidate phase. The API is near-stable and battle-tested in production. Breaking changes are expected to be rare and limited to critical correctness/security fixes before 1.0.

Installation

cargo install qail

Commands

Schema Operations

# Extract schema from database
qail pull postgres://user:pass@host/db -o schema.qail

# Compare two schemas
qail diff old.qail new.qail

# Check best practices
qail lint schema.qail

# Format QAIL files
qail fmt schema.qail

Migration Operations

# Create a new migration
qail migrate create add_users_table --author "dev"

# Preview migration SQL
qail migrate plan old.qail:new.qail

# Apply migrations
qail migrate up old.qail:new.qail postgres://...

# Rollback migrations
qail migrate down postgres://...

Query REPL

# Interactive query transpiler
qail repl

> get users fields id, name where active = true
SELECT id, name FROM users WHERE active = true

SQL String vs SQL Bytes

• qail repl shows SQL text for inspection/debugging.
• Runtime execution with qail-pg is AST-first and protocol-byte based.
• In other words: SQL text is a tooling view here, not the required authoring model for app code.

Legacy Syntax Notice

Old QAIL releases experimented with symbolic text syntax such as get::users•@id@email@role[active=true][lim=10] and macro snippets such as qail!("get::users:'id'email [ 'active == true ]").

Those examples are legacy and may still appear on old docs.rs pages in search results. They are not the current 0.27.x recommendation.

Current QAIL application code should use the native AST builder API, while the qail CLI remains a tooling surface for schema work, REPL inspection, and migration operations.

Schema Format

QAIL uses a concise, version-controlled schema format:

-- schema.qail
table users (
    id uuid primary key default gen_random_uuid(),
    email text not null unique,
    created_at timestamptz default now()
);

table orders (
    id uuid primary key,
    user_id uuid references users(id),
    total numeric(10,2)
);

Features

• Schema extraction — Pull live schemas from PostgreSQL
• Smart diffing — Detect additions, removals, modifications
• Impact analysis — Warn about breaking changes
• Foreign key validation — Ensure referential integrity
• Data-safe migrations — Preview SQL before applying
• Type-safe queries — Transpile QAIL to SQL

Ecosystem

License

Apache-2.0

🤝 Contributing & Support

We welcome issue reports on GitHub! Please provide detailed descriptions to help us reproduce and fix the problem. We aim to address critical issues within 1-5 business days.