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 6, 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 6, 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.2.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.2-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.2-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.2-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.2-py3-none-macosx_11_0_arm64.whl (3.7 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

hoodiecollin_forgedb-0.3.2-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.2.tar.gz.

File metadata

  • Download URL: hoodiecollin_forgedb-0.3.2.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.2.tar.gz
Algorithm Hash digest
SHA256 aa7a630b2acef344fbe54d0c1718db8c17102d75264308294920a632bc041154
MD5 79a3407aaebe7632017f635f702995f7
BLAKE2b-256 3434231c27f55f7da11cdcf2b2458b58d0a99a33e95393279eb5a8b25d22ac5b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.3.2-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 18c04d5eb31a2f74eb764eb2d8a2ea265d866e2e84e655cb0abd0decf055f61d
MD5 954b2bba9e4fd1ccc6ffd2f3ecc69460
BLAKE2b-256 6047a041315a701acb637792c5b44296056c2265d23dd4464a73293a3720ae40

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.3.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 0787688a8aa4df2ba0038d9a03bcfeaf822e9983ab0c5a4dbfed101695648011
MD5 6f6d8572bae936ce29f38032bbbb359f
BLAKE2b-256 8a7a48d85a4bf8adbd19a986b08c6167f3305dbd87505a1e8f227c9e2ee43047

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.3.2-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 7bd33a1d67c7511b685d82ec3a8a3c6157c3d379f6cf31a6e1637f7708d0738e
MD5 9f58b56c49d807878b42a03adbeceab6
BLAKE2b-256 cadf8fb3400426b1ffda96481ac5afeb7600559b6ba69df0ec1d450ee46327c2

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.3.2-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 41b1ee6170bfae29d650c8472a289c7c3edd194e4e4807da67bcaab0f9557a29
MD5 b22b0bdb3171246961ea9a1d3852609f
BLAKE2b-256 c7c3dff8e58528d67fdb308ecbb80622fa94be2076f2e1ef219391c5822f7cb9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.3.2-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 49dbec02824e42cc468c5d2ff77c67fc968846468a47d5e2bc7085102e1fb5d9
MD5 f66b9aad10069c188861410c882f967c
BLAKE2b-256 91820341e5bab760f8120855ec8469cf64e50e249fdf5fa088243bec87772435

See more details on using hashes here.

Provenance

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

This release

0.3.2 This release

6 files

0.3.1

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