udb 0.3.5

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 native-service table is generated from the embedded descriptor: docs/generated/native-services.md.

0.3.5 Release Focus

UDB 0.3.5 is the native-store release. It moves the P4 work out of ad-hoc service SQL and into descriptor-backed native entity paths, so control-plane features use the same typed model, tenant scope, event contracts, and migration guards as the rest of the broker.

• Native notification and analytics flows now run through the native entity store path instead of hand-built SQL call sites.
• Storage, asset, WebRTC, tenant, auth, IdP, and control services share the same native runtime/store binding and generated contract checks.
• SDKs were regenerated for Go, Python, TypeScript, Java, C#, and PHP, with cross-language conformance plus deep live coverage for the broker-backed SDK harnesses.
• CI release gates now cover version consistency, native contract drift, SDK service coverage, MinIO-backed live SDK startup, and native-service live integration assumptions.

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",
    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

Install the CLI from a release binary, through an SDK launcher, or from source:

cargo install --path .

Export UDB's shared protos into an application project:

udb proto export --fmt

Write app-owned protos that import UDB annotations:

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

Inspect the catalog and generated SQL:

udb catalog proto
udb sql proto
udb lint proto --human

Start a local broker:

udb serve proto "" 0.0.0.0:50051

Check runtime readiness:

udb doctor --human
udb compat-matrix

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: 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/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.