Reference

Codex and Recipes

Quarry Codex is the optional named-query and recipe registry. It stores raw SQL templates, binds parameters safely, and keeps repeated Quarry builders close to the SQL they represent.

Raw stored queries

cx := codex.New()

if err := cx.AddRawNamed("users.by_id", `
    SELECT id, email
    FROM users
    WHERE id = :id
`); err != nil {
    panic(err)
}

q := cx.MustRaw("users.by_id").With(qq).BindMap(map[string]any{
    "id": 10,
})

sql, args, err := q.ToSQL()

Behavior Named raw SQL still follows the active dialect. PostgreSQL gets $1, MySQL and SQLite get ?.

Recipes

type UserSearchParams struct {
    Search string
    Status *string
}

recipe := codex.NewRecipe(func(qq *quarry.Quarry, p UserSearchParams) quarry.SQLer {
    return qq.Select("id", "email").
        From("users").
        Where(
            quarry.OptionalILike("email", p.Search),
            quarry.OptionalEq("status", p.Status),
        )
})

q, err := recipe.Build(qq, UserSearchParams{
    Search: "%bob%",
})
if err != nil {
    panic(err)
}

Truthful contract Recipe builds return (quarry.SQLer, error). The API prefers errors over panic in normal use.

What Codex is doing here Codex is not executing SQL and it is not replacing Quarry builders. It stores reusable SQL shapes and recipe functions that still return Quarry queries.

Registry helpers

Validation

Query names are validated, duplicates are rejected, and the store stays deterministic.

Strict mode

Named queries can reject unused parameters when you want tighter review discipline.

Bindings

Bind by map, struct, or typed recipe parameter depending on the use case.

When to use Codex

You want a stable name for a query shape that gets reused in more than one place.
You want raw SQL to stay visible, but you still want named binding or a typed recipe wrapper.
You want a light registry, not an execution framework or repository layer.

When not to use Codex

You need query execution, transactions, or connection management.
You want relation loading, entity tracking, or schema-aware behavior.
You are trying to hide SQL instead of keep it obvious.