ForgeDB

An application-database generator. Write one schema; get a tailored database.

forgedb.dev · Getting Started · Docs · Benchmarks

What it is

ForgeDB compiles a declarative .forge schema — at compile time — into a tailored Rust database, a REST API (with an OpenAPI 3.1 spec), and typed clients for TypeScript, Python, Rust, and Go. It is a code generator, not an ORM or query engine: your schema is a compile-time input to generation, never a runtime input to a generic engine. The generated code is specialized per schema over columnar storage, so there is no generic-runtime layer to pay for — nothing reflects your schema at runtime.

Everything in this repository is open source under MIT OR Apache-2.0. See docs/OPEN_CORE.md for the open-core boundary.

Status: early development (0.2.x, pre-1.0), not yet production-ready. What v1 actually guarantees — and what it defers — is stated plainly in docs/WHAT_V1_IS.md. Trust that over any headline here.

One schema in, a stack out

User {
  id: +uuid                                              // auto-generated primary key
  email: ^&string @pattern("^[^@]+@[^@]+\\.[a-z]{2,}$")  // unique, indexed, format-checked
  username: ^&string                                     // unique, indexed
  created_at: ^timestamp                                 // indexed (ordered → range queries)
  posts: [Post]                                          // one-to-many

  @index(created_at, username)                           // composite index
}

Post {
  id: +uuid
  title: ^string @length(5, 200)                         // indexed; length-validated
  author: *User                                          // required foreign key
  view_count: ^u64                                       // indexed (ordered → range queries)
  created_at: ^timestamp
  tags: [Tag]                                            // many-to-many

  @index(author, created_at)                             // composite index
}

Tag {
  id: +uuid
  name: ^&string
  posts: [Post]                                          // many-to-many (bidirectional)
}

forgedb generate turns that into typed, schema-tailored methods — index probes, not scans, and no runtime engine to interpret the schema (these are the real generated signatures; probes return plain values, not a Result):

let ada     = db.user.get_by_email("ada@example.com");    // Option<User> — O(1) unique lookup
let popular = db.post.find_by_view_count_range(            // Vec<Post> — ordered range / top-N
                  Some(1_000), None, /* descending */ true, /* limit */ Some(10));
let recent  = db.post.find_by_author_and_created_at(author_id, ts);  // Vec<Post> — composite index
db.link_post_tag(post_id, tag_id);                        // many-to-many link

— plus a REST endpoint per model with filter/sort/pagination, the OpenAPI spec, and matching typed clients for TypeScript, Python, Rust, and Go (same methods, same shapes, no hand-written HTTP and no drift between them).

How it works

schema.forge
    │  parser (lexer → AST) → validation
    ▼
codegen
    ├─→ Rust database code      (columnar storage, typed query API, durable writes)
    ├─→ REST API (axum)         (CRUD, relation traversal, query params)
    ├─→ OpenAPI 3.1 spec
    ├─→ typed REST clients      (TypeScript, Python, Rust, Go — one per language)
    ├─→ in-process bindings     (PyO3, NAPI-RS — embed the DB instead of calling it, opt-in)
    ├─→ browser read-replica    (WASM, opt-in — the same generated engine, in a Worker)
    └─→ migration transformer   (offline, per-version data rewrite)

The storage is a columnar hybrid: fixed-size types (u64, f64, uuid, …) live in packed columns for tight, cache-friendly access; variable-length data (strings, json) rides an append-only column with an offset index. Because the generated code is monomorphized to your exact schema, there is no dynamic dispatch over a generic row type. Performance is measured, not asserted, and benchmarked fairly — with durability semantics matched across engines. At the fsync-barrier tier ForgeDB ties SQLite and redb; relaxed, it's the fastest of the group, with the smallest on-disk footprint of the embedded four. The methodology and current numbers live in docs/BENCHMARKS.md.

What's real today

Implemented and working:

  • Schema parser (lexer → AST) + validation; the forgedb CLI
  • Columnar storage engine, WAL, in-process compaction
  • Crash-safe durable writes; MVCC transactions + multi-process write coordination
  • Codegen: Rust database, REST API (+ OpenAPI 3.1), typed REST clients for TypeScript / Python / Rust / Go
  • Secondary + composite indexes, relation traversal, snapshot reads, live queries, backup/restore
  • Multi-tenancy (verify-only JWT), schema migrations, browser read-replica (WASM)
  • LSP server + VS Code extension; in-process native bindings (PyO3 for Python, NAPI-RS for Node / Bun)

Not built (and not near-term): generated UI components. The schema can reference UI components as contract markers, but ForgeDB does not generate component code today.

For the full, honest scope see docs/WHAT_V1_IS.md and docs/V1_ROADMAP.md.

Why generate instead of run an engine

  • One source of truth. The schema defines storage layout, the Rust database, the TS types, and the API — they cannot drift, because they are all generated from it.
  • Compile-time, not runtime. Errors surface at build time; the compiler optimizes for your schema rather than a generic one.
  • No runtime engine to interpret your schema. Generated code links only schema-agnostic substrate crates (storage, WAL, types); there is no ORM reflecting over a schema at runtime.
  • Columnar from the start. Not a row store with columns bolted on.

Good fit: type-safe full-stack apps with stable schemas, local-first apps (browser read-replica), embedded use where the schema is known at compile time, services that want strong contracts. Poor fit: schemas that change shape at runtime, or ad-hoc analytics over unknown schemas.

Getting started

Install the CLI (macOS / Linux — Windows via WSL2), then scaffold a project:

curl -fsSL https://get.forgedb.dev/install.sh | sh   # prebuilt binary, no Rust toolchain

forgedb init my-app
cd my-app
# edit schema.forge, then:
forgedb dev                    # generate, build, and run the dev server

The same binary is on every major channel — Homebrew, npm, pip/uv, Docker, Nix, and cargo install forgedb. See docs/INSTALL.md for every path.

Or generate from a schema in a cloned checkout:

git clone https://github.com/hoodiecollin/forgedb && cd forgedb
cargo build --workspace
cargo run -- generate all --output ./generated   # discovers ./schema.forge

See docs/GETTING_STARTED.md for the full loop with verified output, docs/INSTALL.md for every install path, and examples/ for worked schemas across many domains.

Documentation

The full docs — with an ecosystem toggle for TypeScript / Python / Rust / Go — are hosted at forgedb.dev/docs. The Markdown sources below are the same content.

Start here

Operating

Internals & contributing

Contributing

Contributions are welcome — bug fixes, tests, docs, examples, and performance work especially. Start with the Contributing Guide. Design proposals are filed as rfc-labeled issues, not committed docs.

License

Dual-licensed under MIT or Apache 2.0 at your option.

Project links

Data verified by PyPI on Jul 31, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.5.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for hoodiecollin from gravatar.com hoodiecollin

Credits

Author: Collin Kokotas

GitHub Statistics

Data verified by PyPI on Jul 31, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache Software License, MIT License (MIT OR Apache-2.0)

Requires

Python >=3.8

Tags

database codegen orm cli generator

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hoodiecollin_forgedb-0.3.0.tar.gz (3.2 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

hoodiecollin_forgedb-0.3.0-py3-none-musllinux_1_2_x86_64.whl (4.1 MB view details)

Uploaded Python 3musllinux: musl 1.2+ x86-64

hoodiecollin_forgedb-0.3.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (4.0 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

hoodiecollin_forgedb-0.3.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.7 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

hoodiecollin_forgedb-0.3.0-py3-none-macosx_11_0_arm64.whl (3.7 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

hoodiecollin_forgedb-0.3.0-py3-none-macosx_10_12_x86_64.whl (3.9 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file hoodiecollin_forgedb-0.3.0.tar.gz.

File metadata

  • Download URL: hoodiecollin_forgedb-0.3.0.tar.gz
  • Upload date:
  • Size: 3.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hoodiecollin_forgedb-0.3.0.tar.gz
Algorithm Hash digest
SHA256 ddda906a79284b275452cf7c4df608cda6d3092ba6c1bb18e4b31ad0656b3fba
MD5 8b731f466e2b1188e2b8f2331506215b
BLAKE2b-256 163783be44f669aa2ee0b93d7a75c23191b7f94a282f29e2e2393d0f11fe02cb

See more details on using hashes here.

Provenance

The following attestation bundles were made for hoodiecollin_forgedb-0.3.0.tar.gz:

Publisher: pypi.yml on hoodiecollin/forgedb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hoodiecollin_forgedb-0.3.0-py3-none-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.3.0-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 a3a3cd01257fbcf0eeb0955ade2796a4334cb12af30a7654f132f806ab8694e5
MD5 4103239dc25d000fbdab46298d0ff5c7
BLAKE2b-256 9640e3a960ed35969f8ea8015192f2c408a85247d29120daaec31ddd4112f015

See more details on using hashes here.

Provenance

The following attestation bundles were made for hoodiecollin_forgedb-0.3.0-py3-none-musllinux_1_2_x86_64.whl:

Publisher: pypi.yml on hoodiecollin/forgedb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hoodiecollin_forgedb-0.3.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.3.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 c7145142d90b10e62c8240bd9552821adc31cffd34e4fe53292c46e02c47f9d5
MD5 7df3109ff7501dd10b519fab34bcc972
BLAKE2b-256 ccea9d3a799bdda39b95f70e8ced0ae8002fc39375b9ddaeaf7c86fe22f04161

See more details on using hashes here.

Provenance

The following attestation bundles were made for hoodiecollin_forgedb-0.3.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: pypi.yml on hoodiecollin/forgedb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hoodiecollin_forgedb-0.3.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.3.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 6667439c159d75aee0941c2a2431a684ff07ee2571ac8a43ab09c9c1c29507c1
MD5 6c9e8fb0543316d9b2e5b812c1aa7d7e
BLAKE2b-256 c91d4d5004abf7e58fc9c3ea4337c130abc9aee2f8944ef9b03c0a809a523779

See more details on using hashes here.

Provenance

The following attestation bundles were made for hoodiecollin_forgedb-0.3.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: pypi.yml on hoodiecollin/forgedb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hoodiecollin_forgedb-0.3.0-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.3.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f2e85dc62cc72be5772201e7fa9ec5850130cbd12c73ec2abb73f27f5d42c620
MD5 c672a77479b504ce4d4bff1c23535a4c
BLAKE2b-256 800d4c89ed4277a0086d1b915ae23adb8cfec523cb42ab4236b0f0aaa21483a4

See more details on using hashes here.

Provenance

The following attestation bundles were made for hoodiecollin_forgedb-0.3.0-py3-none-macosx_11_0_arm64.whl:

Publisher: pypi.yml on hoodiecollin/forgedb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hoodiecollin_forgedb-0.3.0-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.3.0-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 f5e1e3751421c1df3391f275ea2d1481bb64e3d19e00ac9b4ffa4d315ae19485
MD5 b682558df69a161baeb4a563d973498f
BLAKE2b-256 b8f4213dc24fac91ac973fc59f9986febc352a7d246a3911b3384ae856d31e97

See more details on using hashes here.

Provenance

The following attestation bundles were made for hoodiecollin_forgedb-0.3.0-py3-none-macosx_10_12_x86_64.whl:

Publisher: pypi.yml on hoodiecollin/forgedb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.5.0

6 files

0.4.1

6 files

0.4.0

6 files

0.3.2

6 files

0.3.1

6 files

This release

0.3.0 This release

6 files

0.2.0

6 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page