using-udb

Using UDB

UDB is a proto-driven multi-database broker. Developers declare their data model as annotated Protocol Buffers; UDB generates the DB schema and serves a uniform gRPC DataBroker API (Select/Upsert/Delete) plus a native control plane (auth/authz/api-keys/storage/asset/notification/webrtc). Every request carries metadata (tenant, project, scopes, identity) enforced fail-closed server-side.

Full reference (read on demand): references/using-udb.md — per-language SDK install+connect snippets, the metadata header table, CRUD semantics (idempotency/retry/pagination/proto3-presence), auth + bootstrap, the native-services tour (storage upload flow, notifications, WebRTC, events/CDC), proto annotation authoring with tenant columns, the CLI, and the error-decode table.

Mental model (hold this)

1. Entities are protos. Table = annotated message; its fully-qualified name (e.g. shop.v1.Customer) is the message_type for every data RPC.
2. TWO gRPC targets. Data target (default :50051) serves ONLY health/reflection/DataBroker. ALL native services live on the control-plane target (default port+10) — every SDK has target AND authTarget. UNIMPLEMENTED ≈ you dialed the wrong one.
3. Every call carries metadata (tenant/project/scopes + a credential); tenant isolation is enforced server-side on reads AND writes, and a body tenant can never override the credential's tenant.
4. Mutations are not auto-retried (only read-only RPCs retry on DEADLINE_EXCEEDED) — recommend conflict_fields idempotency on Upsert.
5. Every mutation emits an event (udb.<svc>.<entity>.<verb>.v1); CDC subscription streams are tenant-scoped with since_event_id replay.

Before giving code, establish

• Language (TS / Python / Go / Java / C# / PHP) → that SDK's snippet from the reference.
• Both addresses — data target + control-plane/authTarget.
• Credential — bearer/API key in hand, or bootstrap needed?

Quick reference

SDK packages: TS @udb_plus/sdk · Python udb-client · Go github.com/fahara02/udb/sdk/go · Java dev.udb:udb-java-client · C# Udb.Client · PHP fahara02/udb-laravel.

CRUD (by message_type = proto FQN): Select {filter, limit ≤ ~500/page} · Upsert {record, conflict_fields, return_record} · Delete {filter} · typed cache/document/graph/timeseries RPCs per GetCapabilities.

Storage upload: RegisterUpload → presigned PUT → FinalizeUpload (is_public is optional — omit to preserve) → presigned GET. Authz: can(resource, action); server cache_ttl_seconds=0 = never cache.

Bootstrap a fresh broker:

UDB_PG_DSN=… UDB_PASSWORD_HASH_SECRET=… \
udb auth bootstrap user --username admin --email [email protected] \
    --password '<strong>' --tenant acme --project default

CLI: udb proto export --out proto · udb serve proto "" 0.0.0.0:50051 · udb sdk generate --lang <l> · udb sdk manifest · udb doctor · udb native list/docs · udb compat-matrix (authoritative annotations).

Error decode (first response to any failure)

UNIMPLEMENTED→wrong target (set authTarget) · PERMISSION_DENIED→scope or tenant mismatch · FAILED_PRECONDITION→service disabled / wrong state / missing config · RESOURCE_EXHAUSTED→rate limit or backpressure (back off) · INVALID_ARGUMENT→unknown message_type (use the FQN; udb sdk manifest) · ABORTED→version/CAS conflict (re-read, retry) · NOT_FOUND can mean "exists, but not your tenant" — by design.

Guardrails

• Always include metadata (tenant/project/scopes) AND a credential in examples; route native-service clients to authTarget. Use message_type FQNs, never table names.
• Tenant-scoped entity protos need a recognizable tenant column (tenant_id, _tenant_id, or is_tenant_column: true); custom proto packages need UDB_PROTO_NAMESPACE or annotations are silently ignored.
• Don't invent RPCs/fields/annotations — ground truth is udb sdk manifest, udb native list/docs, udb compat-matrix, and the reference file above.