udb 0.4.17

UDB is a public, schema-driven knowledge graph and data broker for applications that need one typed API in front of many data systems.

You describe your domain in normal .proto files, add UDB annotations for storage and security behavior, then run one broker in front of relational databases, object stores, caches, vector stores, document stores, graph stores, analytics systems, and native identity services. Application code calls UDB through gRPC or an SDK; UDB handles routing, metadata, authorization, migrations, CDC, and backend-specific execution.

What UDB Gives You

• One DataBroker API for relational records, objects, vectors, cache entries, documents, graphs, analytics, catalog operations, migrations, transactions, CDC, and admin health.
• A native control plane for authentication, authorization, API keys, identity providers, tenants, notifications, analytics, storage, assets, WebRTC, and versioned policy distribution.
• A descriptor-driven contract: protos define services, tables, field security, endpoint security, SDK surfaces, event contracts, and generated docs.
• Multi-tenant request context on every call: tenant, project, user, purpose, service identity, scopes, correlation id, and client catalog version.
• SDKs for Go, Python, TypeScript/Node, Java, C#, and PHP/Laravel.
• A single CLI named udb for proto export, formatting, SDK generation, native service setup, app integration, local dev, broker serving, and diagnostics.

Current Surface

The service surface below is generated from the embedded descriptor — do not edit the counts by hand. Run udb native docs (which also regenerates docs/generated/native-services.md) and commit the refreshed block; the readme_services_block_matches_embedded_descriptor staleness test fails if it drifts.

Per-service RPC counts (native control plane):

Why UDB

Any app that outgrows a single database ends up hand-writing the same plumbing: a client per datastore, a tenant filter on every query, retry and idempotency logic, an auth layer, a secrets store, a search index, a job runner. UDB is that plumbing — built once, behind one typed API — so your code stays about your product, not the seams between systems.

• Tenant isolation you can't forget to add. Every row is scoped by a canonical tenant UUID, enforced in the database — not by a WHERE tenant = … you might leave off one query. Pass your human tenant code ("acme") and the SDK resolves it to the UUID, so the classic first-week bug — a code/UUID mismatch that silently returns zero rows — simply can't happen.
• Writes that behave, so you delete code. Read-after-write consistency, idempotent Upsert/Delete (a retried mutation replays safely and reports was_duplicate), and typed errors on a stable wire contract are built in — correctness glue you'd otherwise re-write in every service.
• The rest of the backend, already built. Auth with SSO, secrets, search, cache, schedulers and durable workflows, webhooks, metering, embeddings, file storage — the control plane you'd normally assemble from a dozen vendors, all tenant-scoped and reached through the same SDK as your data.
• Swap the database without a rewrite. The same Select/Upsert/Delete fronts 18 backend kinds — relational, document, vector, object, cache, graph, wide-column, analytics, and search — so choosing or changing a store is a config decision, not a rewrite of your app.
• Identical behavior in every language. The Go, Python, TypeScript, Java, C#, and PHP SDKs are generated from one proto contract, so an Invoice behaves the same in all six.

None of this is aspirational: every backend and RPC is exercised by live conformance tests against a running broker in each language — the surface is proven, not just declared.

How It Feels

Your project owns the model:

syntax = "proto3";
package acme.billing.v1;

import "udb/core/common/v1/db.proto";

message Invoice {
  option (udb.core.common.v1.pg_table) = {
    schema: "billing"
    table: "invoices"
  };

  string invoice_id = 1 [(udb.core.common.v1.pg_column) = {
    primary_key: true
    sql_type: "text"
  }];

  string tenant_id = 2;
  string customer_id = 3;
  int64 total_cents = 4;
}

Application code calls the broker through an SDK:

from udb_client import Metadata, UdbClient, decode_records

meta = Metadata(
    tenant_id="acme",   # your human tenant code; the SDK login flow resolves it to
                        # the canonical UUID that RLS checks — see examples/python_enterprise
                        # (passing a raw code is the #1 "why are my reads empty?" bug).
    user_id="user-1",
    purpose="billing.api",
    scopes=("udb:read", "udb:write"),
    service_identity="billing-service",
    project_id="billing",
)

with UdbClient("127.0.0.1:50051", meta) as udb:
    rows = udb.select(message_type="acme.billing.v1.Invoice", limit=50)
    print(decode_records(rows))

Quick Start

The whole idea: you describe your data model in protobuf, and UDB turns it into a running, multi-tenant, RLS-protected API over your database — no ORM, no hand-written SQL, no schema migrations to babysit. Here's the path from an empty folder to querying your own tables.

1. Get the udb CLI — from a release binary, an SDK launcher, or source:

cargo install --path .

2. Pull in UDB's shared protobuf annotations so your own protos can use them:

udb proto export --fmt      # writes udb/core/common/v1/*.proto into your project

3. Describe your data model. Write normal protos and annotate the fields UDB should turn into tables/columns — that annotation file is the one you just exported:

import "udb/core/common/v1/db.proto";   // gives you pg_table / pg_column, RLS, tenancy

4. See exactly what UDB will build before you run anything — the catalog, the SQL it generates, and a human-readable lint of your model:

udb catalog proto            # the tables/columns UDB derived from your protos
udb sql proto                # the DDL it will run
udb lint proto --human       # plain-English warnings (missing tenant column, etc.)

5. Start the broker. It generates the schema and serves your model over gRPC:

udb serve proto "" 0.0.0.0:50051

6. Confirm it's healthy:

udb doctor --human           # readiness in plain English
udb compat-matrix            # which backends/features are live

7. Connect your application. Now point an SDK at the broker, authenticate, and do tenant-scoped CRUD. The shortest correct path — including the tenant-code → canonical-UUID handling that trips up most first integrations — is in examples/go_enterprise (Go), with equivalents in examples/python_enterprise and examples/ts_enterprise. Start there rather than wiring the raw gRPC clients yourself.

CLI

All public commands use the short binary name udb.

Backends

UDB knows these backend kinds:

postgres, mysql, sqlite, sqlserver, clickhouse, redis, memcached, qdrant, weaviate, pinecone, minio, s3, azureblob, gcs, mongodb, elasticsearch, neo4j, and cassandra.

The live capability matrix distinguishes compiled support from configured runtime availability:

udb compat-matrix

Native Control Plane

UDB ships a separate internal control-plane listener for native services. Bind it to an internal interface or place it behind a trusted gateway.

Details, including the read-your-writes consistency contract (write receipts, read fences, consistency modes) and idempotency was_duplicate replay: docs/native-services.md.

SDKs

Start here: sdk/README.md.

Examples

Documentation

• docs/README.md - documentation index
• docs/architecture.md - architecture, request flow, routing, pooling, events, and backend capability
• docs/api-rules.md - API route rules, OpenAPI operation IDs, and SDK alias policy
• docs/annotations.md - proto annotations
• docs/integration.md - application integration
• docs/native-services.md - native auth, authz, IdP, storage, assets, WebRTC, and SDK facades
• docs/operations.md - production readiness, config, runbooks, SLOs, and validation
• docs/security.md - request context, identity, authorization, sensitive data, and compliance profiles
• docs/testing.md - test commands and live checks
• VERSIONING.md - release and protocol versioning
• TESTING.md - top-level test guide

Development

Fast local checks:

cargo test --lib
buf lint
buf build
node scripts/check-versions.mjs

SDK conformance:

node sdk-conformance/run.mjs

The default Rust suite is designed to run without external services. Live backend, HA, and load checks are documented separately and require the matching infrastructure.

License

MIT. See LICENSE.