udb 0.4.14

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):

What's Battle-Tested

UDB isn't a prototype. Every backend it advertises is exercised by live conformance tests against a real server, and the hard parts of putting one API in front of many databases are already handled for you:

• Multi-tenant isolation that actually holds. Row-level security is enforced in the database, scoped by a canonical tenant UUID — not a string you can typo. The SDKs resolve your human-readable tenant code ("acme") to that UUID for you, which removes the single most common first-integration bug: a code/UUID mismatch that silently returns zero rows.
• Correctness you don't re-implement. Read-after-write, idempotent retries (keyed Upsert/Delete replay safely), typed errors on a stable wire contract, and tenant/project binding are broker-owned. Your application code stays short without the rules going quiet.
• A real control plane, not stubs. Native identity (authentication, authorization, API keys, IdP with SAML/SCIM), plus Vault, Lock, Scheduler, Webhook, Search, Cache, LiveQuery, Config, Metering, Backup, Embedding, Workflow, Storage, Assets, and WebRTC — all served through the same tenant-scoped runtime.
• Broad backend coverage, one typed API. Relational (Postgres, MySQL, SQLite, SQL Server), document (MongoDB), vector (Qdrant, Weaviate, Pinecone), object (S3, MinIO, GCS, Azure Blob), cache (Redis, Memcached), graph (Neo4j), wide-column (Cassandra), analytics (ClickHouse), and search (Elasticsearch).
• Six SDKs from one contract. Go, Python, TypeScript, Java, C#, and PHP are generated from the same protos and checked for cross-language parity, so an Invoice behaves the same in every language — and the full RPC surface is measured live in each.

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.