HexDB

Search HexDB

Find a feature, an API example, a step, a FAQ answer or a term, then jump to it.

The API

Small Surface. Deep Features.

If you can send JSON over HTTP you already know how to use HexDB. Here's what that buys you.

Listen to the podcast - 4:50 min

Queries: REST, GraphQL, SQL and gRPC

The four ways to query HexDB and when to pick each one, why SQL is read-only, and where change feeds, streams and webhooks fit in.

0:00--:--

Plain HTTP. Every Write Is Atomic and Durable Before It Returns.

  • PUT replaces, PATCH is a JSON merge patch, null removes a field.
  • Bulk writes, update-by-filter and upserts are each a single atomic write.
  • Every write takes an Idempotency-Key: a retry returns the original response, even after a crash.
  • A write to a tessellation that doesn't exist creates it.
# Create: 201 with the document and a Location header. ?ttl=<seconds> sets an expiry.
curl -X POST http://localhost:7700/orders -H "Content-Type: application/json" \
  -d '{ "order_no": "ORD-1001", "status": "pending", "total": 445.5, "customer": { "name": "Ada", "country": "GB" } }'

# Read, replace, merge-patch (null removes a field), delete
curl http://localhost:7700/orders/01JTY87RVJ9B5863KMB2YD896B        # ETag = version
curl -X PUT   http://localhost:7700/orders/01JTY... -d '{ "order_no": "ORD-1001", "status": "paid", "total": 445.5 }'
curl -X PATCH http://localhost:7700/orders/01JTY... -d '{ "status": "shipped", "notes": null }'
curl -X DELETE http://localhost:7700/orders/01JTY...                 # 204

# Bulk: one atomic write, up to 10,000 documents
curl -X POST http://localhost:7700/orders/_bulk -d '[{ "order_no": "ORD-1002" }, { "order_no": "ORD-1003" }]'

# Patch everything a filter matches
curl -X POST http://localhost:7700/orders/_update \
  -d '{ "filter": { "status": "pending" }, "update": { "status": "paid" } }'
# => { "matched": 10, "modified": 10 }

# Upsert by key fields
curl -X POST http://localhost:7700/customers/_upsert \
  -d '{ "key": ["email"], "documents": [{ "email": "ada@example.com", "name": "Ada", "tier": "gold" }] }'

Drivers

Or Skip HTTP and Use a Client.

Node.js, Python and .NET drivers cover documents, queries, aggregations, transactions, idempotency keys, the change feed, streams, functions and GraphQL. They retry 429 and 503 where it's safe to. On .NET there is also an Entity Framework Core provider: LINQ filters, sorting and paging run on the server, and each SaveChanges is one atomic transaction. Reporting tools connect through the ODBC driver, and Java tools and code (DBeaver, IntelliJ, Spark) through the JDBC driver; both speak HexDB's read-only SQL.

npm install @dreaminhex/hexdb
import { HexDB } from "@dreaminhex/hexdb"

const db = new HexDB({ url: "http://127.0.0.1:7700", apiKey: process.env.HEXDB_API_KEY })
const orders = db.tessellation("orders")

await orders.insert({ customer: "ada", total: 12 })
const page = await orders.query({ filter: { total: { $gt: 10 } }, sort: "-total" })

Ecosystem

Plugs Into What You Already Run.

Plugins extend HexDB without changing it. Each is a folder with a manifest: a process in any language reading JSON lines on stdin, a webhook, or a built-in exporter. They run on the Overseer, so a lattice delivers each payload once, and they resume from a saved position after a restart.

Listen to the podcast - 5:28 min

Programmability: Drivers, Functions and Events

Stored functions in JavaScript, TypeScript and Python, saved transactions, cron jobs and triggers, streams, webhooks and plugins, and the drivers for npm, PyPI, NuGet, ODBC and JDBC.

0:00--:--
PluginTypeWhat it does
@streams/kafkastreamProduces changes to Kafka, keyed by document ID
@streams/kinesisstreamPuts changes on an Amazon Kinesis stream
@sinks/otlpmetricsMetrics to an OpenTelemetry endpoint (built in)
@sinks/log-filelogsRotating JSON-lines log files
@sinks/http-logslogsLog records to Splunk HEC, Logstash and friends
@sources/postgressourceCopies a PostgreSQL table and keeps it in sync
@sources/mssqlsourceThe same for SQL Server
@sources/s3sourceImports JSON and JSON-lines objects from S3
@sources/s3-filessourceImports files from S3 or an S3-compatible store, keeping folders
@sources/azure-filessourceImports files from Azure Blob Storage
@sources/gdrive-filessourceImports files from a Google Drive folder
@sources/dropbox-filessourceImports files from a Dropbox folder
@enrichers/ai-keywordsstreamAdds keywords to new documents with the lattice's AI provider
@examples/change-loggerstreamLogs each change; the minimal example
Plugin SDK and examples

Process plugins run in a clean environment with only the variables they're given. The server's own keys are never passed.

a plugin, with the dependency-free SDK
import { payloads, api, log } from "../../sdk/hexdb-plugin.mjs"

for await (const change of payloads()) {
  if (change.op === "put") log("order", change.id, change.document.total)
}

await api().post("/orders", { total: 12 })   // plugins with [access]
JavaScript / TypeScriptnpm install @dreaminhex/hexdb
Node.js 18+, Deno, Bun or a browser. No dependencies. npm (opens in a new tab)
Pythonpip install hexdb
Python 3.9+. Standard library only. PyPI (opens in a new tab)
.NET (C#, F#)dotnet add package HexDB.Client
Entity Framework Coredotnet add package HexDB.EntityFrameworkCore
EF Core 9 on .NET 8+. LINQ runs on the server; relationships with Include, owned types nested in the document, inheritance and explicit transactions; each SaveChanges is one atomic transaction. NuGet (opens in a new tab)
ODBCincluded with HexDB
64-bit, installed with HexDB on every platform; the Windows installer and the Debian package register it as "HexDB". Read-only SQL with joins and subqueries for BI tools, spreadsheets, pyodbc and R. Tested with pyodbc; desktop tools such as Excel and Power BI not yet. Install HexDB
JDBChexdb-jdbc-<version>.jar
Java 11+, one jar with no dependencies, on every GitHub release. Read-only SQL with joins and subqueries for DBeaver, IntelliJ, Spark, reporting tools and plain JDBC code: jdbc:hexdb://host:7700. Download (opens in a new tab)

Listen to the podcast - 1:38 min

Plugins in a Sandbox

Every process plugin runs in a sandbox: Landlock, seccomp and resource limits on Linux, an AppContainer on Windows. A plugin reads its own folder, writes its own data folder, and reaches the network or anything else only if its manifest says so.

0:00--:--