Shimpz
Conforming reference · Service Spec v1

PostgreSQL Service

One Space service owns the PostgreSQL administrator credential, provisions exact database roles, and gives each Capsule access only to its registered database set.

Security boundary

The control credential stops at the Service

  • Only the PostgreSQL Service holds the administrator DSN.
  • The provisioner uses a dedicated Bearer token for Capsule creation and finalization.
  • Each Capsule receives a random principal; the Service stores its hash and exact database set.
  • Database and role names are derived on the server from validated Capsule and workload identifiers.
  • The current compatibility runtime issues only a database URL scoped to the registered workload.
  • No generic SQL, global list, arbitrary create, or arbitrary drop operation is exposed.
Discovery

Internal discovery, protected mutations

HTTP · shimpz.postgresql/v1
GET /healthz
GET /v1/driver
POST /v1/capsules/provision
POST /v1/capsules/finalize
POST /v1/capsules/apps/create
POST /v1/capsules/apps/drop
POST /v1/capsules/drop

/v1/driver and the /apps/ route segments are retained wire identifiers from before the public Service and Assistant rename. The two GET routes reveal only liveness and validated manifest metadata. Every POST route requires the correct Bearer authority for its exact operation. These endpoints are internal to private Space networks and must not be routed to the Internet.

shimpz.postgresql/v1

Request and response contract

Control requests are JSON objects with Content-Type: application/json. A successful mutation returns HTTP 200 and a trace_id; errors return a generic error without reflecting SQL, subprocess output, credentials, or an upstream body.

The capsule.app.* operation names and app_id field below are legacy wire compatibility identifiers. New public documentation calls that workload an Assistant; these identifiers can change only through a versioned interface migration.

  • capsule.provision uses provisioner authority with capsule_id and principal_token; it returns database_url and created.
  • capsule.finalize uses provisioner authority with capsule_id; it returns finalized.
  • capsule.app.create uses that Capsule's principal with capsule_id and app_id; it returns database_url and created.
  • capsule.app.drop uses that Capsule's principal with capsule_id and app_id; it returns the exact dropped database and may report already_absent for a proved retry.
  • capsule.drop uses that Capsule's principal with capsule_id; it returns the exact dropped database list and retires the principal for retry-safe finalization.
Conformance proof

What conforms now

  • The manifest is parsed with a closed allowlist before the listener or token state starts.
  • Malformed, incomplete, unknown, Capsule-scoped, and required-BYOK declarations fail closed.
  • Discovery metadata matches the in-image manifest exactly.
  • Unauthenticated mutations remain forbidden, including the Docker healthcheck's live auth probe.
  • Provision, retry, workload teardown, Capsule retirement, and legacy-route denial retain their isolation tests.

Read the PostgreSQL Service source.