Proto contract reference
Lookup tables for working in
soundverse-proto. For the “how”, see
Add a field or RPC and
How the DB codegen plugin works.
DB annotations
Section titled “DB annotations”Defined in proto/soundverse_proto/db/v1/db_options.proto. RPC options annotate the method;
field options annotate a message field.
| Annotation | Applies to | Ext # | What it does |
|---|---|---|---|
target_db |
RPC | 50001 | Which connection pool to run against (e.g. "prod") |
sql_query |
RPC | 50002 | The literal SQL the generated handler runs |
cache_ttl_seconds |
RPC | 50003 | Cache-aside TTL for the result |
require_internal_auth |
RPC | 50005 | Require the internal bearer (INTERNAL_RPC_SECRET) |
cache_key |
RPC | 50006 | Cache key template (e.g. tools:active:{environment}) |
invalidates_keys |
RPC | 50007 | Cache keys to bust on a mutation |
db_column |
field | 50004 | Maps a message field to a DB column |
db_enum_text |
field | 50008 | Field maps to a Postgres ENUM (send lowercase label, cast in SQL) |
buf templates & generated outputs
Section titled “buf templates & generated outputs”Codegen runs these in order (mirrors ci.yml):
| Template | Emits |
|---|---|
buf.gen.yaml |
Go, Python (+ mypy stubs), Swift, Kotlin message/service code |
buf.gen.connect.yaml |
Connect Go handlers + Connect-ES (bufbuild/es) TypeScript for the web |
buf.gen.soundverse-db.yaml |
Runs the local ./bin/protoc-gen-soundverse-db → SQL-backed Go handlers |
cmd/gen-db-registry (go run .) |
Aggregates registry/db_registry.go (mounts every handler) |
Build the custom plugin (cmd/protoc-gen-soundverse-db) into ./bin before the
soundverse-db template. Generated code (gen/) is gitignored — the SDKs are published in CI.
DB error → Connect code
Section titled “DB error → Connect code”The generated handlers map Postgres/pgx errors to Connect status codes:
| Postgres / pgx | Connect code |
|---|---|
pgx.ErrNoRows |
NotFound |
23505 unique violation |
AlreadyExists |
23502 not-null / 23503 FK / 23514 check |
InvalidArgument / FailedPrecondition |
40001 serialization / 40P01 deadlock |
Aborted |
08* connection errors |
Unavailable |
| context canceled / deadline exceeded | Canceled / DeadlineExceeded |
| anything else | Internal |
Package layout (selected)
Section titled “Package layout (selected)”proto/soundverse_proto/<domain>/v1/ — one domain per directory, each with its .proto and
sibling schema.sql:
identity · billing/* · generation (task, tool) · storage · chat · consumer ·
studio / collabstudio · growth · compat · db · common.
Related
Section titled “Related”- Add a field or RPC to a data service — using these annotations
- Run proto codegen locally — the ordered commands
- How the DB codegen plugin works — the internals
- Data schema catalog — the tables these RPCs hit