Fediversity

Feature Specification: Component postgresql

Created: 2026-10-07

Status: Implemented

Input: Reconstructed from the code of core/components/hosting-provider/postgresql/ and the setups at 093e68b6f.

User Scenarios & Testing (mandatory)

User Story 1 - Run the shared database node (Priority: P1)

The apps need PostgreSQL databases. The postgresql component marks the node that provides postgresql, and carries no server configuration itself. The setups give that node the server, and the databases and roles of the consumers (see postgresql, 005).

Why this priority: each app with a postgresql request needs this node.

Independent Test: a unit test of the setups holds that what the node creates agrees with what the consumers expect. A contract test and a render-gate test cover the provider.

Acceptance Scenarios:

  1. Given the node in the central group (the one group whose roster provides the varsBackend), When the setups evaluate, Then it also gets the requests of the operator groups, the full roster, and access from the networks of the app nodes.
  2. Given a deployment that serves PKI, When the leaf of the database name renders, Then only the server can read its key, and the server and the UI restart.

User Story 2 - Read the databases in a web UI (Priority: P2)

An administrator reads the tables in a read-only web UI on its own name under the apex, behind a one-factor Authelia forward-auth check. The UI can switch between app databases.

Why this priority: a convenience. The databases work without it.

Independent Test: unit tests hold the UI in the served names under the apex.

Acceptance Scenarios:

  1. Given a running UI, When an administrator runs a write statement, Then the UI refuses it.

Edge Cases

  • The UI connects as the superuser over loopback without TLS, so it needs the loopback trust rule of the postgresql resource.
  • The UI starts after the server without requiring it. A slow leaf can exhaust its start limit, and the restart on the new leaf recovers it.
  • Without the admin UI policy, the node has no UI.
  • The node does not back up the full cluster. Each consumer backs up its own database. A database without such a backup has no offsite copy.

Requirements (mandatory)

Functional Requirements

  • FR-001: The component MUST declare that it provides postgresql, and MUST request a SPIFFE identity so that the node can get an OpenBao token.
  • FR-002: The component MUST request a one-factor forward-auth vhost for the UI, and the UI MUST exist only with that vhost.
  • FR-003: The UI MUST run without a fixed user, listen only on loopback, refuse writes, and restart after a failure.
  • FR-004: The setups, not the component, MUST give the server, the databases and the roles to the provider of postgresql. On the central group they MUST add the operator requests, the full roster and the app networks.
  • FR-005: On a node that serves PKI, only the server MUST read the leaf key, and a new leaf MUST restart the server and the UI.

Key Entities

  • PostgreSQL roster: the databases and roles that the node creates for its consumers.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: The unit tests of the roster, the render gate, the served names and the apex, and the contract test of the provider, pass.
  • SC-002: On a live node, the UI name sends a browser without a session to the Authelia portal.

Assumptions

  • Authelia runs in the deployment (see authelia).
  • The entry point gives the apex to the module.

Known Deviations

None.