crates.io
Rust
Embed the engine directly with native transactions, Cypher, SQL, and bounded retrieval. Select Cargo features to fit your host; the synchronous API works without Tokio.
Get the Rust crate →Embedded graph database · SQL + Search · Rust
The context layer,
inside your process.
HawDB brings graph, SQL, full-text, and vector search into one embedded Rust database. Connect entities, documents, and events, query with Cypher and PostgreSQL SQL, and return bounded context from a shared snapshot.
Now on HawDB 0.25.0 — durable agent branches, exact decimals, and a native MoonBit SDK.
MATCH (h:Hawk)-[:HUNTS]->(p:Prey)
WHERE h.wingspan_cm > 100
RETURN h.name AS hawk, p.name AS prey
ORDER BY h.wingspan_cm DESCWhat's in the box
One canonical store, everything else a projection of it. Build-time features are an upper bound: what you compile out cannot quietly reappear at runtime.
One engine, four shapes
Graph structure, relational rows, lexical search, and vector search live on one canonical snapshot and commit boundary — no sync job between a graph store, a SQL store, and an index.
Cypher and PostgreSQL SQL
Parameterized Cypher for connected facts, PostgreSQL-dialect SQL for tables and strict-append event logs — on the same handle, inside the same transaction model.
One Cascades-style optimizer
Both languages plan through a shared memo. Graph predicates run as soon as their variables are bound, reducing downstream reads. Cached plans reuse compatible parameters, and EXPLAIN shows the chosen plan.
Durable by default
The WAL syncs on every commit by default. Host-enabled automatic checkpoints respond to storage pressure, while recovery replays the committed prefix and drops a torn tail. One writer lease, one process.
Search as rebuildable projections
BM25 full-text search and filtered DiskANN vector retrieval are derived from canonical state. RaBitQ remains available. Pinned generations and canonical snapshot checks keep retrieval tied to the facts it comes from.
Budgets the host can act on
Reads have row, payload, and execution-memory limits under local QoS admission. Typed errors identify the exhausted resource, while retained result views keep their memory reservations until released.
Query, search, and summarize
Isolate an agent's work, keep exact numeric values, maintain live SQL summaries, and retrieve connected context — inside the same engine.
Synchronous materialized views
Keep filtered projections and grouped COUNT, SUM, MIN, and MAX results current in the base table's transaction. Rollback discards both; successful commits publish both. Add indexes to the view's output columns.
Read the view guide →Filtered DiskANN retrieval
DiskANN combines filtered navigation and update overlays with snapshot catch-up. Binary vector sidecars avoid loading document bodies for vector hits, and final ranking respects the projection's distance metric.
Explore the vector backend →Durable branches for agents
Give each agent a writable copy-on-write branch sharing the parent's sealed data. Branch-local graph, SQL, and schema changes stay isolated and survive restart. Hosts choose which results to write back; branches do not merge.
Read the branching contract →Exact decimal arithmetic
Use native DECIMAL and NUMERIC columns for exact values with up to 38 digits. Arithmetic, aggregates, indexes, and durable recovery preserve numeric precision. Python Decimal and SQLAlchemy Numeric keep values exact across the host boundary.
Explore the SQL numeric contract →Tables without primary keys
Store duplicate rows in native keyless tables. Hidden row handles stay internal, while SQL supports implicit INSERT columns, typed string defaults, and common PostgreSQL type aliases. SQLAlchemy Core can use these tables; ORM mappings still need a primary key.
Explore relational SQL support →Expressive Cypher transformations
Normalize text with trim and regexp_replace, extend lists with list_append, and UNWIND computed lists. Supported constant SET assignments across independent matched nodes execute atomically, with resource refusal and rollback preserving the whole mutation.
Read the Cypher query contracts →Live SQL summaries
Write the fact.
Read the updated summary.
A materialized view tracks changes as part of the source transaction. Insert, update, upsert, and delete all maintain the result before commit returns. There is no refresh job to schedule.
Definitions use one resident row table, supported filters, and projections or COUNT/SUM/MIN/MAX aggregates. MIN/MAX require a qualifying source index. Maintenance shares the transaction's work budget; exceeding it rejects the whole transaction.
Query a live summary in the playground →CREATE MATERIALIZED VIEW sightings_by_hawk AS
SELECT hawk, COUNT(*) AS sightings
FROM sightings
GROUP BY hawk;
INSERT INTO sightings (id, hawk, spotted_at)
VALUES (3, 'Aurelia', '2026-10-29');
SELECT hawk, sightings
FROM sightings_by_hawk
ORDER BY hawk;
-- Aurelia | 2
-- Talon | 1Exact values, end to end
Keep every digit.
Keep the scale.
Native DECIMAL and NUMERIC carry exact values through expressions, aggregates, indexes, and recovery. Use Python's decimal.Decimal or SQLAlchemy Numeric to keep that precision in your application too.
Precision is bounded to 38 digits. Column assignments round to the declared scale with ties away from zero and reject overflow. Mixing Decimal and DOUBLE PRECISION arithmetic or comparisons requires an explicit CAST. The playground displays Decimal results as exact text.
Try exact arithmetic in the playground →SELECT
CAST(9007199254740993.01 AS NUMERIC(38, 2))
+ CAST(0.01 AS NUMERIC(38, 2)) AS amount;
-- 9007199254740993.02Context, in one pipeline
retrieve_knowledgeruns one fixed pipeline against a pinned graph snapshot. Stale search hits are dropped and counted, missing score features are reported rather than read as zero, and a request that exceeds its memory or payload budget fails whole — partial context is never returned.
01
search_candidate
Lexical or vector hits from the published search projection.
02
metadata_filter
Relevance predicates on projection metadata.
03
authorized_graph_expand
Neighborhood expansion that rechecks scope on canonical nodes.
04
rerank
Max, a weighted sum, or a host-supplied ScoringSpec with decay.
05
top_k
Truncate before any output entity is built.
06
canonical_hydration
Identity, properties, and graph context from the pinned snapshot.
Try it without installing anything
The playground compiles HawDB's public facade towasm32-unknown-unknownand runs it in a dedicated Web Worker, in memory, on your device. Type Cypher or SQL against a seeded dataset and share any query as a link. Try graph traversal, relational queries, and the seeded materialized view, exact decimal arithmetic, and keyless tables. It's an experimental runtime — one statement at a time. Persistent storage, full-text search, and vector indexes require a native host.
Embed it
HawDB is a Rust library, published oncrates.io. The default build includes full-text search, vector search, graph analytics, background maintenance, and the Tokio adapter. Trim it down for constrained hosts.
# Cargo.toml
[dependencies]
hawdb = "0.25.0"
# minimal: canonical storage, WAL recovery, transactions, Cypher
hawdb = { version = "0.25.0", default-features = false }
# pick specific capabilities back
hawdb = { version = "0.25.0", default-features = false, features = [
"full-text-search",
"vector-search",
] }Snapshot isolation is the default. Opt-in serializable validation is available for supported SQL and Cypher statements. HawDB is a single-process engine: one database directory, one writer lease, no standalone server.
Language bindings & integrations
Your language. One embedded engine.
Start with Rust, install Python and SQLAlchemy from PyPI, or embed the native library through Go, MoonBit, or the C ABI. Every host runs HawDB inside its own process, without a separate database server.
PyPI · CPython 3.11+
Python
Install hawdb for graph and SQL queries, transactions, PEP 249 cursors, and exact decimal.Decimal values. Native wheels cover Linux and macOS on x86-64 and Arm64, plus Windows x86-64. Pydantic is optional.
Get hawdb on PyPI →PyPI · SQLAlchemy 2.x
SQLAlchemy
Use Core and ORM statements, explicit transactions, and schema reflection through HawDB's DB-API driver. Numeric columns preserve Decimal values and reflected precision and scale. Core also supports tables without primary keys.
Get the SQLAlchemy dialect →Source binding · cgo-free
Go
Load the HawDB native shared library through purego with CGO_ENABLED=0. Run Cypher or SQL and receive owned rows through JSON. Build the native library separately and close database handles explicitly.
Read the Go binding guide →Source build · shared or static library
C ABI
Embed from C, C++, or another FFI host using hawdb-ffi and its generated header. Open a database and execute Cypher or SQL with JSON parameters and results; release output buffers through the matching free function.
Explore the C ABI →Source SDK · native FFI
MoonBit
Run Cypher and SQL against the embedded Rust engine from MoonBit. The native SDK includes typed values, exact Decimal, read and write transactions, durable reopen, and read-only access. Build from source; no separate SDK publisher is provided.
Explore the MoonBit SDK →Experimental · in-memory
WebAssembly
Run graph and SQL queries in a browser Web Worker through the wasm-bindgen bridge used by this playground. The runtime is single-threaded and in-memory; persistent storage, full-text search, and vector indexes require a native host.
Read the WASM guide →Upgrading an existing database? HawDB 0.25 changes relational storage formats. Older development databases must be recreated; there is no automatic migration. Preserve the data you need before recreating them. See the storage compatibility notes.
Python: graph queries and SQL cursors
python -m pip install hawdb==0.25.0import hawdb
with hawdb.open() as db:
db.execute(
"CREATE (:Hawk {name: $name})", {"name": "Aurelia"}
)
result = db.execute("MATCH (h:Hawk) RETURN h.name")
print(result.fetchall())
with hawdb.connect() as connection:
cursor = connection.cursor()
cursor.execute("SELECT version()")
print(cursor.fetchone())SQLAlchemy: Core and ORM integration
python -m pip install sqlalchemy-hawdb==0.25.0from sqlalchemy import create_engine, text
engine = create_engine("hawdb:///:memory:")
with engine.begin() as connection:
connection.execute(text(
"CREATE TABLE sightings "
"(id BIGINT PRIMARY KEY, hawk TEXT)"
))
connection.execute(
text("INSERT INTO sightings (id, hawk) "
"VALUES (:id, :hawk)"),
{"id": 1, "hawk": "Aurelia"},
)
rows = connection.execute(text("SELECT * FROM sightings"))
print(rows.all())
engine.dispose()For durable storage, use an absolute directory URL such ashawdb:////var/lib/my-app/knowledge; its parent must exist. File databases use NullPool, and in-memory databases stay local to each thread. Use connections serially on the thread that opened them. Auto-generated IDs, savepoints, schema alteration, and concurrent connections to one path are outside the dialect's scope.
Built to be checked
Executable TLA+ models cover storage publication, MVCC, and retrieval. Differential fuzzing, crash-recovery checks, and resource qualification exercise the engine alongside those models. Shiro adds a continuous local SQL and Cypher fuzzing tool for contributors.
Explore the fuzzing tools →