README.md

Write SQL. Get type-safe code. In ten languages.

Scythe compiles annotated .sql files into database access code — row types, query functions and type mappings — that stays in sync with your schema. It reads your SQL statically, so generation needs no database connection and no network: it runs in a pre-commit hook.

10 languages · 10 databases · 56 backends · 58 lint and audit rules · nullability inferred through JOINs, CTEs and window functions

Docs · Install · What you get · Quick start · Commands · Compare

Why scythe

Every application that talks to a database needs glue: code that maps parameters in, maps result rows out, and keeps the types aligned. It is tedious, easy to get subtly wrong, and it changes every time the schema does.

Scythe deletes that layer. You keep writing SQL — the language your database already optimizes and your team already knows — and the mapping code is compiled from it. The generated code is readable, has no runtime dependency beyond your driver, and carries a provenance header so scythe check can tell you when it has drifted from the schema it came from.

Where an ORM still wins: if your users choose the database, an ORM abstracts dialect differences at runtime and scythe does not. Scythe targets one engine per configuration block, which is what buys you engine-specific features and a real query planner. If you control the database, that trade is worth making.

What you get

Installation

cargo install scythe-cli
cargo binstall scythe-cli              # prebuilt binary, no compile
brew install Goldziher/tap/scythe

No Rust toolchain required — both wrappers download the prebuilt binary for your platform and verify its checksum:

npm install --save-dev scythe-cli
pip install scythe-sql

See Installation for supported platforms, proxy configuration and cache control.

repos:
  - repo: https://github.com/Goldziher/scythe
    rev: v0.14.0
    hooks:
      - id: scythe-fmt        # format SQL
      - id: scythe-lint       # lint with auto-fix
      - id: scythe-audit      # SC-SEC*/SC-RLS*/SC-MIG*/SC-CHK*
      - id: scythe-inspect    # live-DB checks, needs $DATABASE_URL
      - id: scythe-generate   # regenerate on SQL changes
      - id: scythe-check      # validate without generating

Quick start

1. Annotate a query. status is an enum column; o.total and o.notes sit on the right side of a LEFT JOIN.

-- @name GetUserOrders
-- @returns :many
SELECT u.id, u.name, o.total, o.notes
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
WHERE u.status = \$1;

2. Point scythe.toml at it.

[scythe]
version = "1"

[[sql]]
name = "main"
engine = "postgresql"
schema = ["sql/schema.sql"]
queries = ["sql/queries.sql"]

[[sql.gen]]
backend = "python-psycopg3"
output = "src/generated"

3. Generate.

scythe generate

4. Use it. total and notes are | None because the join can fail to match; id and name are not. The enum became a real UserStatus, and the parameter is typed with it.

@dataclass(frozen=True, slots=True)
class GetUserOrdersRow:
    """Row type for GetUserOrders query."""

    id: int
    name: str
    total: decimal.Decimal | None
    notes: str | None


async def get_user_orders(conn: AsyncConnection, *, status: UserStatus) -> list[GetUserOrdersRow]:
    """Execute GetUserOrders query."""

#[derive(Debug, Clone, sqlx::FromRow)]
pub struct GetUserOrdersRow {
    pub id: i32,
    pub name: String,
    pub total: Option<rust_decimal::Decimal>,
    pub notes: Option<String>,
}

export interface GetUserOrdersRow {
	id: number;
	name: string;
	total: string | null;
	notes: string | null;
}

type GetUserOrdersRow struct {
	Id int32 `json:"id"`
	Name string `json:"name"`
	Total *decimal.Decimal `json:"total"`
	Notes *string `json:"notes"`
}

public record GetUserOrdersRow(
    int id,
    String name,
    @Nullable java.math.BigDecimal total,
    @Nullable String notes
) {}

data class GetUserOrdersRow(
    val id: Int,
    val name: String,
    val total: java.math.BigDecimal?,
    val notes: String?,
)

public record GetUserOrdersRow(
    int Id,
    string Name,
    decimal? Total,
    string? Notes
);

defmodule GetUserOrdersRow do
  @moduledoc "Row type for GetUserOrders queries."

  @type t :: %__MODULE__{
    id: integer(),
    name: String.t(),
    total: Decimal.t() | nil,
    notes: String.t() | nil
  }
  defstruct [:id, :name, :total, :notes]
end

GetUserOrdersRow = Data.define(:id, :name, :total, :notes)

readonly class GetUserOrdersRow {
    public function __construct(
        public int $id,
        public string $name,
        public ?string $total,
        public ?string $notes,
    ) {}
}

Commands

scythe generate                       # compile SQL to code
scythe check                          # is the committed code still in sync?
scythe lint sql/                      # 23 correctness and performance rules
scythe audit sql/ --format sarif      # 35 security and migration-safety rules
scythe fmt sql/                       # format via sqruff
scythe inspect $DATABASE_URL          # live-database health checks
scythe migrate sqlc.yaml              # convert an sqlc config

check and audit exit 2 on error-severity findings and 1 on operational failure, so CI can tell the two apart. Full flags and exit codes are in the CLI reference.

Language and database support

Ten languages — Rust, Python, TypeScript, Go, Java, Kotlin, C#, Elixir, Ruby and PHP, plus plain JavaScript via the four javascript-* backends — across PostgreSQL, MySQL, MariaDB, SQLite, DuckDB, CockroachDB, MSSQL, Oracle, Redshift and Snowflake. Coverage is not uniform: not every language has a driver for every engine.

Documentation

Full documentation at goldziher.github.io/scythe.

• Quickstart — zero to generated code, in every language
• Philosophy — why compile SQL instead of using an ORM
• Alternatives — scythe against sqlc, SQLDelight, jOOQ and ORMs
• Configuration — the full scythe.toml reference
• Annotations — @name, @returns, @optional, @nullable, @json
• Type inference — how nullability and types are derived
• Custom types — overrides for extension and domain types
• CLI reference — every command, flag and exit code

Contributing

See CONTRIBUTING.md for setup, architecture, and how to add backends, engines or lint rules.

License

MIT