galchemy

galchemy is a PostgreSQL-first SQL toolkit for Gleam:

• SQL DSL (select, insert, update, delete);
• SQL compiler (AST -> SQL + params);
• PostgreSQL execution helpers (pog);
• schema introspection, diff, DDL, and migration planning;
• explicit ORM/session building blocks.

The design goal is explicitness:

• you build immutable query values;
• you compile explicitly;
• you execute explicitly;
• no hidden query execution or Active Record-style magic.

Installation

gleam add galchemy

Quick Start

import galchemy
import galchemy/ast/query
import galchemy/dsl/expr
import galchemy/dsl/predicate
import galchemy/dsl/select
import galchemy/dsl/table
import gleam/io
import gleam/string

pub fn main() -> Nil {
  let users = table.as_(table.table("users"), "u")
  let id = table.int(users, "id")
  let name = table.text(users, "name")
  let active = table.bool(users, "active")

  let q =
    select.select([
      expr.item(expr.col(id)),
      expr.item(expr.col(name)),
    ])
    |> select.from(users)
    |> select.where_(predicate.eq(expr.col(active), expr.bool(True)))
    |> query.Select

  io.println(string.inspect(galchemy.compile(q)))
}

Core Workflow

1. Define table/column references with galchemy/dsl/table.
2. Build query AST values with galchemy/dsl/*.
3. Compile with galchemy.compile (or compile_with).
4. Optionally execute through galchemy/sql/postgres.

Example Catalog

All runnable examples live in src/galchemy/examples/*.
Root examples/* contains matching entry-point wrappers.

Scenario	Module
Simple select + decoder	galchemy/examples/simple_select
CRUD builders	galchemy/examples/crud
Joins	galchemy/examples/join_example
RETURNING	galchemy/examples/returning_example
Advanced SQL (CTE, derived source/join, subquery, window, UNION ALL)	galchemy/examples/advanced_select
Schema diff + migration plan + code generation	galchemy/examples/schema_tooling
PostgreSQL schema introspection	galchemy/examples/schema_introspection
Eager/lazy loading planners	galchemy/examples/loading
Entity + unit of work + runtime session	galchemy/examples/orm
Declarative models + model-first query + result mapping	galchemy/examples/orm_declarative

Run them with:

gleam run -m galchemy/examples/simple_select
gleam run -m galchemy/examples/crud
gleam run -m galchemy/examples/join_example
gleam run -m galchemy/examples/returning_example
gleam run -m galchemy/examples/advanced_select
gleam run -m galchemy/examples/schema_tooling
gleam run -m galchemy/examples/schema_introspection
gleam run -m galchemy/examples/loading
gleam run -m galchemy/examples/orm
gleam run -m galchemy/examples/orm_declarative

SQL DSL Highlights

CRUD

Use dedicated modules:

• galchemy/dsl/select
• galchemy/dsl/insert
• galchemy/dsl/update
• galchemy/dsl/delete

Each builder is immutable and returns a new query value.

Predicates and Expressions

galchemy/dsl/predicate supports:

• comparisons: eq, neq, gt, gte, lt, lte;
• boolean composition: and, or, not;
• in_list, in_subquery;
• is_null, is_not_null;
• like, ilike.

galchemy/dsl/expr supports:

• literals (text, int, bool, float, timestamp, date, time_of_day, null);
• scalar functions (call, lower, upper, coalesce);
• aggregates (count, count_all, sum, avg, min, max);
• arithmetic and concatenation;
• window expressions via over.

Advanced Select Features

Supported select composition:

• with_cte;
• from_derived, inner_join_derived, left_join_derived;
• group_by, having;
• union, union_all;
• distinct, order_by, limit, offset.

See galchemy/examples/advanced_select for a combined real-world example.

PostgreSQL Execution

galchemy/sql/postgres bridges compiled queries to pog.

import galchemy/ast/query
import galchemy/sql/postgres
import gleam/dynamic/decode
import pog

pub fn run(connection: pog.Connection, q: query.Query) {
  let decoder = decode.at([0], decode.int)
  postgres.execute_with(q, decoder, connection)
}

Schema Tooling

galchemy can help with the full schema pipeline:

1. introspect PostgreSQL to SchemaSnapshot;
2. infer relations;
3. diff snapshots;
4. compile DDL operations;
5. build and apply migration plans;
6. generate Gleam table modules from snapshots.

Main modules:

• galchemy/schema/introspection/postgres
• galchemy/schema/relation
• galchemy/schema/diff
• galchemy/schema/ddl/postgres
• galchemy/schema/migration/postgres
• galchemy/schema/generator/gleam

See:

• galchemy/examples/schema_tooling
• galchemy/examples/schema_introspection

ORM and Session Building Blocks

galchemy ORM is explicit and composable. It provides primitives, not hidden magic:

• declarative model definition: galchemy/orm/declarative;
• metadata/mapper/runtime registries;
• identity map and materializer;
• explicit entity state transitions;
• unit-of-work flush planning;
• session runtime with track, stage, flush, commit, rollback;
• loading planners (joined/select-in style).

Recommended starting path:

1. galchemy/examples/orm_declarative
2. galchemy/examples/orm
3. galchemy/examples/loading

Public API Map

• galchemy: top-level compile facade (compile, compile_with).
• galchemy/dsl/*: SQL builders.
• galchemy/sql/compiler: AST compiler.
• galchemy/sql/postgres: pog adapter.
• galchemy/schema/*: schema introspection/diff/migration/generation.
• galchemy/orm/*: declarative metadata, query/result mapping, materialization.
• galchemy/session/*: unit-of-work, runtime, transaction and loading helpers.

Current Scope

Intentionally in scope:

• PostgreSQL-first behavior;
• explicit AST and compile boundary;
• explicit runtime/session mechanics.

Intentionally out of scope:

• multi-dialect SQL abstraction;
• implicit ORM behaviors.

Development

gleam check
gleam test