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

  • Deployment — containers, env config, ops routes, multi-tenancy, JWT
  • Migrations — how schema changes affect data at rest
  • Upgrading — what each release requires you to do, newest first
  • Versioning & Stability — the compatibility policy across surfaces
  • Benchmarks — measured performance + methodology

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 design gate issues, not committed docs.

License

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

Project links

Data verified by PyPI on Aug 26, 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:
Latest release

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 26, 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.5.0.tar.gz (4.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.5.0-py3-none-musllinux_1_2_x86_64.whl (4.7 MB view details)

Uploaded Python 3musllinux: musl 1.2+ x86-64

hoodiecollin_forgedb-0.5.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (4.6 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

hoodiecollin_forgedb-0.5.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (4.3 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

hoodiecollin_forgedb-0.5.0-py3-none-macosx_11_0_arm64.whl (4.2 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

hoodiecollin_forgedb-0.5.0-py3-none-macosx_10_12_x86_64.whl (4.5 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: hoodiecollin_forgedb-0.5.0.tar.gz
  • Upload date:
  • Size: 4.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.5.0.tar.gz
Algorithm Hash digest
SHA256 6ed8d78d86ab89d84c1e486c6ec8bb469b368dcc7a91514ae1c449b4b756c703
MD5 82400c0999d277c92d5bad8c15a5a4ac
BLAKE2b-256 170071a12c7cf5734452bd66d1fcf82fd8949997d0ae9c1a3f010560b960526d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.5.0-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 bb08bfa4784023fa03e7b009e719f3cf6a6e3e07707100da1b72bb211ea2d397
MD5 f7402fb70a573934fb267c754e14da88
BLAKE2b-256 eabfbd9c189ea396c5f795bcf5a07f1302cafb78c7b2ab211dd41dae02a13a54

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.5.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 12760dcbc9a8714c399e5c2130ad25b7797854fac5a29dc6717173914a6b268b
MD5 08d94341115c9030804953e2fef25319
BLAKE2b-256 386f90e80d5c9f4f8f548957f304928dfb61dcd3f349834cb7766e528f076626

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.5.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 aee50aef9ee9ee5616c46b07052bb1a52a9adaf98ac2fe46cb9cd263d686c2b2
MD5 9a038029e3d920aeb70a2b996314a30f
BLAKE2b-256 873b0417511c31901f55a92a5e38614c349729ed79ac25cd622dd20571e151cd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.5.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1608e01c0074093924a79095133f5c0a98134034d8bcee35e1c8e7ec5676b95b
MD5 e15813845f3409a2da1bb6c8a26539fb
BLAKE2b-256 5f837f6b7842ce71e627cfb395e481cdc79ba0cb3ec1844bf263b68f331f62cc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.5.0-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 92748694ccf25553813f87f1ac4296dcf7f42e1ba38e7e80c1ddd24b018a2d79
MD5 3ce9939c836836b736bcde17d6982417
BLAKE2b-256 1bd92666ce85ac66e1a146b29ae87fed40ca37f6ee5bbb45ce72c613089078c3

See more details on using hashes here.

Provenance

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

This release

0.5.0 This release

6 files

0.4.1

6 files

0.4.0

6 files

0.3.2

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