Features

Built for Serious Data Layers

An AI-first database framework with built-in skills, powerful privacy modeling, and guardrails that prevent destructive operations.

Declarative Data Modeling

Define your entire data model in a simple, readable format. Specify field types, defaults, required constraints, and indexing — then let MoleculeDB generate everything from API endpoints to storage logic.

atom(
    "FileAtom",
    [field("name", required=True),
     field("path", required=True),
     field("size", required=True),
     field("owner", required=True,
           indexable=index_query_type.EQUALITY),
     field("description"),
     field("status", default="active")],
    [],
    {},
)

Connected Data

Model real-world relationships between your data types. Edges support direction, cardinality, and automatic lifecycle management — so deleting a parent can cascade, restrict, or orphan related records.

atom(
    "MediaAtom",
    [field("label", required=True),
     field("owner", required=True,
           indexable=index_query_type.EQUALITY)],
    [edge("MediaFileEdge", "FileAtom",
          edge_direction.BOTH)],
    {},
)

Instant GraphQL API

Define your schema once and every molecule serves an auto-generated GraphQL endpoint alongside gRPC — queries, mutations, and nested traversal across edges, with the same access-control checkers enforced on both transports. Fetch the SDL from a running server or generate it offline; the two are byte-identical.

# One query, serialized across an edge
{
  note(key: "n1") {
    title
    owner
    noteTagEdge {   # nested via the edge
      label         # target's checkers run
    }
  }
}

# Clients get the schema either way:
$ curl host:8080/graphql/schema
$ atom_build graphql --file schema.star

Privacy & Access Control

Build powerful privacy models with chainable access policies: ownership and role checks, graph-aware rules that consult edges (has_edge / get_edge), separate read and write chains per schema, and tunable write authorization (strict pre-image checks, key-derived, or create-guard). Policies run on every read, write, delete, and edge operation — deny-by-default, with reasons accumulated across the chain.

def check(schema, data, key, ctx):
    ctx_name = ctx.get("name", "")
    if ctx_name == "":
        return deny("no context provided")
    if ctx_name == data.get("owner", ""):
        return allow("owner matched")
    # Graph-aware: consult edges in policy
    if has_edge("AdminEdge", ctx_name, key):
        return allow("admin of this record")
    return deny("not owner or admin")

Data Integrity & Versioning

Every write is automatically versioned, preventing lost updates and enabling full change history. Concurrent writers never silently overwrite each other — conflicts are detected and surfaced immediately. Multi-key changes commit atomically, and deletes can run synchronously or as safe, out-of-band background jobs.

# Create (version must be 1)
$ atom_cli set --schema FileAtom \
    --key photo-001 --version 1 \
    --json '{"name":"beach.jpg"}'

# Update (version must be current + 1)
$ atom_cli set --schema FileAtom \
    --key photo-001 --version 2 \
    --json '{"name":"sunset.jpg"}'

# Conflict! (stale version)
$ atom_cli set ... --version 1
  Error: VERSION_CONFLICT

Multi-Generational Schema Storage

Schemas evolve; your data outlives every version of them. MoleculeDB keeps an append-only registry of every schema revision ever registered — name, version, hash, and the full definition — so records written years ago remain interpretable exactly as written, names can be retired and reused safely, and any stored object resolves back to the precise schema generation that produced it.

# Every registration is appended, never overwritten
$ atom_cli schema-revisions --schema FileAtom
v1  3f9a02…  registered_at_unix_ms=1748736000000
v2  62c1e3…  registered_at_unix_ms=1751414400000

# Fetch any generation's full definition
$ atom_cli schema-revisions --schema FileAtom --version 1

# Every stored record carries its schema hash —
# old data always resolves to the definition
# that wrote it, even after evolution or reuse

AI-First Database Development

MoleculeDB is designed from the ground up for AI agents. Pre-written skills guide LLMs through schema creation, access policy setup, and context configuration — turning complex database tasks into simple, guided workflows. The declarative architecture means AI agents work with high-level definitions instead of raw SQL or imperative code, dramatically reducing the risk of destructive operations like accidental deletes or schema corruption.

# AI agent creates a new schema
/create-atom
> Name: UserProfile
> Fields: name (required), email (required),
>         role (default="viewer")

# AI agent adds access control
/create-checker
> Policy: owner-match
> Rule: only the user can read their profile

# AI agent configures auth context
/create-context
> Fields: user_id, role

Secure Identity & Authentication

Every request carries cryptographically signed identity context. Access policies can inspect caller identity, roles, and custom claims — ensuring data access is always authenticated and tamper-proof.

# Config: atom_config.json
{
  "backend": "FileSystem",
  "context_proto": "./context.proto",
  "port": 50051
}

# Pass context with CLI
$ atom_cli get --schema FileAtom \
    --key photo-001 --json \
    --ctx name=alice \
    --ctx role=admin

Developer-Friendly CLI

Manage your data directly from the command line. Full CRUD, querying, edge operations, and JSON output make development and debugging fast.

# CRUD operations
$ atom_cli set --schema MyData \
    --key item-001 --version 1 \
    --json '{"title":"Hello"}'

$ atom_cli get --schema MyData \
    --key item-001 --json

$ atom_cli delete --schema MyData \
    --key item-001

# Query by indexed field
$ atom_cli query --schema MyData \
    --field owner --value alice --json

# Edge operations
$ atom_cli set --field MediaFileEdge \
    media-001 file-001
$ atom_cli get --field MediaFileEdge \
    media-001

Production Observability

One config line turns on Prometheus metrics across every layer: request rates and latency percentiles, storage operations per backend, access-policy verdicts, and background job health. Ready-made Grafana dashboards ship with every release — import and point them at your Prometheus.

# atom_config.json
{ "metrics": { "listen_addr": "0.0.0.0:9464" } }

# Prometheus scrape target
- job_name: moleculedb
  static_configs:
    - targets: ["molecule-host:9464"]

# Dashboards: grafana_dashboards.zip
#   MoleculeDB — Overview
#   MoleculeDB — Storage Backend
#   MoleculeDB — Deletion & Reaper

Storage Backends

Same API, Three Backends

MoleculeDB ships with Filesystem, DynamoDB, and Spanner backends. Pick the one that fits your scale and operational model — the gRPC API, schemas, and checkers stay identical.

Every backend implements the same versioned key-value contract with optimistic concurrency control. Filesystem is ideal for local development and tests. DynamoDB gives you a fully managed, AWS-native option. Spanner adds globally-distributed, externally-consistent storage with the option to run managed in Google Cloud or self-hosted.

Feature	Filesystem	DynamoDB	Spanner
Setup	Drop a directory	AWS account + table	Spanner instance + database
Scale	Single host	Horizontal, AWS-managed	Horizontal, globally distributed
Consistency	Strong (single host)	Tunable per-request	Strong, externally consistent
Concurrency control	File locking	Conditional writes	Read-write transactions
Best for	Local dev, tests, single-tenant	Cloud-native, AWS-hosted apps	Multi-region, SQL-queryable, complex schemas
Operational model	Filesystem	Managed (capacity units)	Managed or self-hosted (incl. Spanner Omni)

Filesystem

The default for local development and tests. Writes to a directory on disk, uses file locking for optimistic concurrency, and ships with the binary — nothing to provision.

atom_config.json

{
  "backend": "FileSystem",
  "storage_path": "./molecule_data",
  "port": 50051,
  "schema_files": ["./MyAtom.star"]
}

DynamoDB

Single-table design on Amazon DynamoDB. Conditional writes back the version counter, and tables can be auto-created on first start.

atom_config.json

{
  "backend": "DynamoDb",
  "dynamodb": {
    "region": "us-east-1",
    "table_name": "atom_storage",
    "auto_create_table": true
  },
  "port": 50051,
  "schema_files": ["./MyAtom.star"]
}

Spanner

Globally-distributed, externally-consistent SQL storage. Optimistic concurrency uses Spanner read-write transactions instead of conditional DML.

atom_config.json

{
  "backend": "Spanner",
  "spanner": {
    "project": "my-project",
    "instance": "my-instance",
    "database": "atomdb",
    "endpoint_url": "http://localhost:9010"
  },
  "port": 50051,
  "schema_files": ["./MyAtom.star"]
}

Set endpoint_url to point at the open-source Spanner emulator or a self-hosted Spanner Omni deployment; omit it to use managed Cloud Spanner with Application Default Credentials.

Interested in MoleculeDB?

We're building the next generation of schema-driven data infrastructure. Register to stay updated.