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.
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.
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.
| Plugin | Type | What it does |
|---|---|---|
| @streams/kafka | stream | Produces changes to Kafka, keyed by document ID |
| @streams/kinesis | stream | Puts changes on an Amazon Kinesis stream |
| @sinks/otlp | metrics | Metrics to an OpenTelemetry endpoint (built in) |
| @sinks/log-file | logs | Rotating JSON-lines log files |
| @sinks/http-logs | logs | Log records to Splunk HEC, Logstash and friends |
| @sources/postgres | source | Copies a PostgreSQL table and keeps it in sync |
| @sources/mssql | source | The same for SQL Server |
| @sources/s3 | source | Imports JSON and JSON-lines objects from S3 |
| @sources/s3-files | source | Imports files from S3 or an S3-compatible store, keeping folders |
| @sources/azure-files | source | Imports files from Azure Blob Storage |
| @sources/gdrive-files | source | Imports files from a Google Drive folder |
| @sources/dropbox-files | source | Imports files from a Dropbox folder |
| @enrichers/ai-keywords | stream | Adds keywords to new documents with the lattice's AI provider |
| @examples/change-logger | stream | Logs each change; the minimal example |
Process plugins run in a clean environment with only the variables they're given. The server's own keys are never passed.
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]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.
