# qail

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

[![Crates.io](https://img.shields.io/crates/v/qail.svg)](https://crates.io/crates/qail)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

> [!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

```bash
cargo install qail
```

## Commands

### Schema Operations

```bash
# 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

```bash
# 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

```bash
# 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:

```sql
-- 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

| Crate | Purpose |
|-------|---------|
| **qail** | CLI tool for schema and migration operations |
| [qail-core](https://crates.io/crates/qail-core) | AST builder, parser, expression helpers |
| [qail-pg](https://crates.io/crates/qail-pg) | PostgreSQL driver (AST → wire protocol) |

## 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.
