Documentation Edit this page

CockroachDb

A hosted SQL-database proxy: ask url://cockroachdb/ for a database and receive a handle speaking the ecosystem's sql.Database contract — parameterized SQL, typed getters, transactions, batch inserts — so a service or agent gets a real SQL database on demand instead of provisioning a cluster and distributing JDBC credentials. It is the SQL Database storage mechanism made concrete as a service, the tabular counterpart to Blobstore, and the credential-containment boundary for the operator's CockroachDB cluster credentials.

Architecture

Consumer (CLI / agent / service)
   │  url:// protocol via UrlResolver (sandboxed client library)
   ▼
CockroachDbServiceServer (url://cockroachdb/)
   │  delegates to
   ▼
CockroachDbEmbedded (domain logic: accounts, tenancy, provisioning)
   │  JDBC (Postgres wire, verify-full TLS via cockroachdb.PsqlSocketFactory)
   ▼
Operator's shared CockroachDB Cloud cluster
   (per-account databases + the cockroachdb_proxy_metadata registry)

Tiered tenancy: CockroachDbAccountManager (root, url://cockroachdb/) → CockroachDbAccount (one tenant) → CockroachDbDatabase, which is the sql.Database contract. Accounts are either shared-cluster tenants (a logical tenant on the operator's cluster, isolated by a dedicated SQL user and opaque physical database names) or bring-your-own CockroachDB Cloud accounts (databases provisioned in the caller's own organization via the Cloud control-plane API).

Dependents

• Any url:// service or agent needing an on-demand SQL database (the tabular counterpart to storing bytes in Blobstore or paths in SimpleFileSystem).

Deployment

# Deploy the url:// service (ContainerNursery lazy-start)
container-nursery-cli deploy \
  --jar cockroachdb-service-server.jar \
  --route "url://cockroachdb/" \
  --env COCKROACHDB_HOST=<operator-cluster-host> \
  --env COCKROACHDB_ADMIN_USER=<admin-user> \
  --env COCKROACHDB_ADMIN_PASSWORD=<admin-password>

URL_BIND_DOMAIN/PORT are supplied by ContainerNursery for lazy-start; absent URL_BIND_DOMAIN, the server runs in standalone P2P mode. See the ServiceServer README for the full environment-variable table.

Health Checks

• Production Health: community.kotlin.healthchecks.cockroachdb:cockroachdb-health-check registered with productionhealth.wasmserver.com — connects over url://, creates a probe account and database, runs a SQL round trip through the vended handle, and cleans up.

Notes

• Transaction serialization: server-held transactions on the same database serialize (sql.Database.execute is synchronized per database); transactions on different databases run concurrently. An abandoned transaction is rolled back by a 120s idle reaper.
• v1 security posture: tenant SQL-user passwords and bring-your-own Cloud API tokens are stored in the metadata database as-is; W3Wallet-gated capabilities, quota, and encryption-at-rest are the planned hardening milestone (see the CockroachDb workstream).
• getConnection() is not served over the proxy (inherently in-process); use the parameterized-SQL surface.