🪝 QAIL — The Horizontal Query Language

Stop writing strings. Hook your data.

The Manifesto

SQL is vertical, verbose, and clunky inside modern codebases.

QAIL is horizontal, dense, and composable. It treats database queries like a pipeline, using symbols to hook data and pull it into your application.

-- The Old Way (SQL)
SELECT id, email, role FROM users WHERE active = true LIMIT 1;

# The QAIL Way
get::users•@id@email@role[active=true][lim=1]

One line. Zero ceremony. Maximum velocity.

📖 Quick Reference

🚀 Installation

CLI (Recommended)

cargo install qail

As a Library

# Cargo.toml
[dependencies]
qail = "0.1"

💡 Usage

CLI — The qail Command

# Fetch all users
qail 'get::users•@*'

# Get specific columns with filter
qail 'get::orders•@id@total@status[user_id=$1][lim=10]' --bind 42

# Update a record
qail 'set::users•[verified=true][id=$1]' --bind 7

# Delete with condition
qail 'del::sessions•[expired_at<now]'

# Transpile only (don't execute)
qail 'get::users•@*[active=true]' --dry-run

As a Library

use qail::prelude::*;

#[tokio::main]
async fn main() -> Result<(), QailError> {
    let db = QailDB::connect("postgres://localhost/mydb").await?;

    // Parse and execute
    let users: Vec<User> = db
        .query("get::users•@id@email@role[active=true][lim=10]")
        .fetch_all()
        .await?;

    // Or use the builder for type-safe composition
    let query = qail::get("users")
        .hook(&["id", "email", "role"])
        .cage("active", true)
        .limit(10);

    let users: Vec<User> = db.run(query).fetch_all().await?;

    Ok(())
}

📚 Syntax Deep Dive

A. Simple Fetch (get::)

-- SQL
SELECT id, email, role FROM users WHERE active = true LIMIT 1;

# QAIL
get::users•@id@email@role[active=true][lim=1]

B. Mutation (set::)

-- SQL
UPDATE user_verifications SET consumed_at = now() WHERE id = $1;

# QAIL
set::user_verifications•[consumed_at=now][id=$1]

Note: In set:: mode, the first [] is the payload (SET), the second [] is the filter (WHERE).

C. Deletion (del::)

-- SQL
DELETE FROM sessions WHERE expired_at < now();

# QAIL
del::sessions•[expired_at<now]

D. Complex Search with Fuzzy Match

-- SQL
SELECT * FROM ai_knowledge_base 
WHERE active = true 
AND (topic ILIKE $1 OR question ILIKE $1 OR EXISTS (SELECT 1 FROM unnest(keywords) k WHERE k ILIKE $1))
ORDER BY created_at DESC
LIMIT 5;

# QAIL
get::ai_knowledge_base•@*[active=true][topic~$1|question~$1|keywords[*]~$1][^!created_at][lim=5]

# Or multi-line for readability:
get::ai_knowledge_base•@*
  [active=true]
  [topic~$1 | question~$1 | keywords[*]~$1]
  [^!created_at]
  [lim=5]

E. Joins (Coming Soon)

# Inner join
get::orders•@*>>users.id=orders.user_id•@users.email[status=paid]

# Left join
get::products•@*>|categories.id=products.cat_id•@categories.name

⚙️ Configuration

Create a .qailrc or qail.toml in your project root:

[connection]
driver = "postgres"           # postgres | mysql | sqlite
url = "postgres://localhost/mydb"

[output]
format = "table"              # table | json | csv
color = true

[safety]
confirm_mutations = true      # Prompt before UPDATE/DELETE
dry_run_default = false

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                      QAIL Pipeline                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   "get::users•@*[active=true]"                              │
│              │                                              │
│              ▼                                              │
│   ┌─────────────────────┐                                   │
│   │   Parser (nom)      │  → Tokenize symbols               │
│   └─────────┬───────────┘                                   │
│             │                                               │
│             ▼                                               │
│   ┌─────────────────────┐                                   │
│   │   AST (QailCmd)     │  → Structured representation      │
│   └─────────┬───────────┘                                   │
│             │                                               │
│             ▼                                               │
│   ┌─────────────────────┐                                   │
│   │ Transpiler (SQL)    │  → Generate valid SQL             │
│   └─────────┬───────────┘                                   │
│             │                                               │
│             ▼                                               │
│   ┌─────────────────────┐                                   │
│   │ Engine (sqlx)       │  → Execute against DB             │
│   └─────────────────────┘                                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Core Structs

pub struct QailCmd {
    pub action: Action,         // GET, SET, DEL, ADD
    pub table: String,
    pub columns: Vec<Column>,
    pub cages: Vec<Cage>,       // Filters, limits, sorts
    pub bindings: Vec<Value>,
}

pub enum Action {
    Get,    // SELECT
    Set,    // UPDATE
    Del,    // DELETE
    Add,    // INSERT
}

pub struct Cage {
    pub kind: CageKind,         // Filter, Limit, Sort, Payload
    pub conditions: Vec<Condition>,
}

pub struct Condition {
    pub column: String,
    pub op: Operator,           // Eq, Ne, Gt, Lt, Fuzzy, In
    pub value: Value,
}

🗺️ Roadmap

Phase 1: Parser ✅

• Lexer for QAIL symbols
• nom parser combinators
• AST generation

Phase 2: Transpiler 🚧

• PostgreSQL codegen
• MySQL codegen
• SQLite codegen
• Query optimization hints

Phase 3: Engine 🔜

• Async execution (sqlx)
• Connection pooling
• Transaction support
• Prepared statement caching

Phase 4: Ecosystem 📋

• VS Code extension (syntax highlighting)
• Language server (LSP)
• REPL mode
• Schema introspection

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

# Clone the repo
git clone https://github.com/your-username/qail.git
cd qail

# Run tests
cargo test

# Run with example
cargo run -- "get::users•@*[lim=5]" --dry-run

📄 License

MIT © 2025 QAIL Contributors