cquill

A compile-time safe data access library for Gleam.

“Ecto, but scaled down and typed, for Gleam” — Schema-like types, composable queries, and adapter-based persistence without locking into any particular database.

Design Philosophy

• Compile-time safety over runtime convenience — Invalid queries should fail at compile time
• Explicit over implicit — No magic; transformations are visible and traceable
• Gleam-idiomatic — Leverage Result types, pipelines, and the module system naturally
• Adapter-first — Define persistence boundaries early; real DBs are just one adapter
• Small, composable modules — Each module has one responsibility

Architecture

cquill follows a layered architecture with clear boundaries:

┌─────────────────────────────────────────┐
│           Your Application              │
├─────────────────────────────────────────┤
│  Schema    │  Changeset  │    Query     │  ← Pure, no I/O
│  (types)   │ (validation)│   (builder)  │
├─────────────────────────────────────────┤
│                  Repo                   │  ← Public API
├─────────────────────────────────────────┤
│  Memory    │  Postgres   │   (Future)   │  ← Adapters
│  Adapter   │  Adapter    │   Adapters   │
└─────────────────────────────────────────┘

Installation

gleam add cquill

Quick Start

import cquill/schema
import cquill/query
import cquill/repo
import cquill/adapter/postgres

pub fn main() {
  // Define your schema
  let user_schema = schema.new("users")
    |> schema.field("id", schema.int())
    |> schema.field("email", schema.string())
    |> schema.field("name", schema.optional(schema.string()))

  // Build a query
  let active_users = query.from(user_schema)
    |> query.where(query.eq("active", True))
    |> query.order_by("created_at", query.Desc)
    |> query.limit(10)

  // Execute via repo
  use pool <- result.try(postgres.connect(config))
  repo.all(pool, active_users)
}

Key Features

• Schemas as data — Define structure without coupling to persistence
• Composable queries — Build complex queries from simple, reusable parts
• Changesets — Validate and transform data before persistence
• Adapter abstraction — Same API works with Postgres, in-memory, or custom backends
• Testable by design — Use in-memory adapter for fast, isolated tests

Database Migrations

cquill focuses on runtime data access, not schema evolution. We recommend using dedicated migration tools:

Quick Start with dbmate

# Create a migration
dbmate new add_users_table

# Apply migrations
dbmate up

# Regenerate cquill types
gleam run -m cquill_cli generate

See docs/MIGRATIONS.md for the complete migration guide, including:

• CI/CD integration examples
• Schema drift detection
• Makefile templates
• Best practices

Status

This library is currently in early development. See the GitHub Issues for the development roadmap.

Roadmap

• Phase 0: Foundation & Research
• Phase 1: Core Query Execution
• Phase 2: Code Generation (MVP)
• Phase 3: Type-Safe Query Builder
• Phase 4: Transactions & Advanced Features
• Phase 5: Developer Experience

Development

gleam test           # Run all tests
gleam format         # Format code
gleam docs build     # Build documentation

Further documentation can be found at https://hexdocs.pm/cquill.

License

Apache-2.0