qail 0.26.4

Schema-first database toolkit - migrations, diff, lint, and query generation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

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

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