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 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 12, 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 12, 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.4.0.tar.gz (3.6 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.4.0-py3-none-musllinux_1_2_x86_64.whl (4.3 MB view details)

Uploaded Python 3musllinux: musl 1.2+ x86-64

hoodiecollin_forgedb-0.4.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (4.2 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

hoodiecollin_forgedb-0.4.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.9 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

hoodiecollin_forgedb-0.4.0-py3-none-macosx_11_0_arm64.whl (3.9 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

hoodiecollin_forgedb-0.4.0-py3-none-macosx_10_12_x86_64.whl (4.1 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: hoodiecollin_forgedb-0.4.0.tar.gz
  • Upload date:
  • Size: 3.6 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.4.0.tar.gz
Algorithm Hash digest
SHA256 cb7ba2adbfdafa910548bf201f798bbdda6088ea3d2f8c81cd12ee778e452038
MD5 6b1967d869bf27312123a9180b3feccb
BLAKE2b-256 133afcb0ed18e940c1b6bddf1038e8731ba879b4552010f6836b04c0f6089509

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.4.0-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 7864ed93fd592978f16cf7d69939cfd6592b7b291d1eeea69d2e5a341aa2e5eb
MD5 997edd8da7ca92771dbb3ae55ce78a45
BLAKE2b-256 8273b7488e00bbebdbcf0bb16875798dd5552c9ab31b4f0028bb64cf53f7832f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.4.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 27118a6df7e60a33e06d9a4e82105ff7643f5ea9d47d341c8107391a535e5f84
MD5 f2d5bd1b7ffa47cf8416903b99e12c63
BLAKE2b-256 4ea8612b5aae6aba57e2e31cbe23ef31e0713c88710eb40b453082c04de852c9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.4.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 44ead97e3dc4048700ba73aea4cd5ca675280f315f22e178cc8f62ce5a5f0340
MD5 95be8d97fde7440d46c2f0a089a755e8
BLAKE2b-256 0ca81e70660f59bc32cb13e0dd8743f00231f07b2c5f77510fd8de4913fe0170

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.4.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1965c14db0400c298edc26f50acb1f8dbb7f8cd727399de28b5eed6c286c698b
MD5 5df3fdd3e15bf75eafcf8056fa80497b
BLAKE2b-256 e60dffa2954f9a090b376f7497c7d3c99ceafa3629661ccdde47a593eebc34dc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for hoodiecollin_forgedb-0.4.0-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 bc76c48565ef55663d454c4ada4f81021c009712ce5649070008763b2b9bcdc0
MD5 9921471f10ca9f502328cf6600b02095
BLAKE2b-256 0707fb33c4d3d9dd7c0063b042463292c36b7c1e53deb486313c5763497bc6c9

See more details on using hashes here.

Provenance

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

This release

0.4.0 This release

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