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 Aug 1, 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 Aug 1, 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.1.tar.gz (3.3 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.1-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.1-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.1-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.1-py3-none-macosx_11_0_arm64.whl (3.7 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

hoodiecollin_forgedb-0.3.1-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.1.tar.gz.

File metadata

  • Download URL: hoodiecollin_forgedb-0.3.1.tar.gz
  • Upload date:
  • Size: 3.3 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.1.tar.gz
Algorithm Hash digest
SHA256 d224bf2b6907c0469b8e4b6137f741de672c87098ffe1648226780acd636c99d
MD5 6c3f79d334bd330ee8e2cb396d3efd5d
BLAKE2b-256 8e657d4a57bb0776cd812b10160117e2af964a9399a1a0ec1a7dadeb5ce6a220

See more details on using hashes here.

Provenance

The following attestation bundles were made for hoodiecollin_forgedb-0.3.1.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.1-py3-none-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.3.1-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 bda590c1cab754352e83807f8302af7cc013a82e94df217e6a5378d1b2c86d79
MD5 ed3b7733c3940b3467e60ce3287e0b70
BLAKE2b-256 d45081011243d3a0a006fdda357903d7d3889886126a6b46c0c7a60c1e056714

See more details on using hashes here.

Provenance

The following attestation bundles were made for hoodiecollin_forgedb-0.3.1-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.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.3.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 f0a3654eca7a952c8de1b76d1eb6a34aaf25703a2778d7a6956a10cd07ae94bb
MD5 96e7303ad9dbd248ece0a93ad2706d7e
BLAKE2b-256 ac33b893bb1b9d9ecc541dd13e3a890fbd254b86124d6487586656575a091d27

See more details on using hashes here.

Provenance

The following attestation bundles were made for hoodiecollin_forgedb-0.3.1-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.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.3.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 ddc0deaad03dd836a9b74753136126ada98f6a753dd681ccbcd5b3c77e60923e
MD5 e53b4a435e0d0685d098b87fad0ee16a
BLAKE2b-256 2f2a3ad379a0ec51671b8e3d3dbf4de3f459cb3a397a3c608ccfa5dee1ef013c

See more details on using hashes here.

Provenance

The following attestation bundles were made for hoodiecollin_forgedb-0.3.1-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.1-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.3.1-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 dc849c600116b76dc2b7f63e7a90fd68815e271ebf882907a16357068a7174dd
MD5 7b20d046cc0291ffd40a149695aea0b6
BLAKE2b-256 03a5148b4d6246b87a6d45e5754e710c46da007f46f012d01e916dcbdd9600c0

See more details on using hashes here.

Provenance

The following attestation bundles were made for hoodiecollin_forgedb-0.3.1-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.1-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.3.1-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 9e95fc34d0e9dd2d1f3edcee37f3cc8c877997ca91bdc18116b2b1880dbd7c7a
MD5 238c17af95b7bfbbd77f47b4d92cca31
BLAKE2b-256 0e8f2f81f27f45b19933e624ae8c0b03d6813269725f7a7913e3a2a9dde09ae2

See more details on using hashes here.

Provenance

The following attestation bundles were made for hoodiecollin_forgedb-0.3.1-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

This release

0.3.1 This release

6 files

0.3.0

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