Skip to content

ADR-0004 — Database initialization by a standalone Job and one JNDI resource per data source

Date: 2026-09-01 · Status: accepted

Context

The TimescaleDB database is an existing, shared service operated by another team. GeoServer must have an isolated configuration schema there (JDBC plugins) and read data schemas owned by other services (message decoding, ingestion), potentially on other URLs and with other accounts. Credentials must come from Secrets, and the GeoServer pods must never hold an administrator account.

Decision

  1. Initialization by a standalone, replayable Kubernetes Job (psql, idempotent SQL script), executed before GeoServer (Helm hook pre-install,pre-upgrade / ArgoCD PreSync), sole holder of the admin Secret provided by the operator. Preconditions (PostGIS) are checked before any creation: no partial state.
  2. One JNDI resource per (URL, account) pair: jdbc/geoserver (configuration schema, read/write) and one resource per data schema (jdbc/meteo, …) with a read-only role created by grant-reader.sql. GeoServer stores reference a JNDI name, never a URL.
  3. search_path set on the role; PostGIS detected, installed only if absent and if the account is superuser, otherwise explicit failure.

Rejected alternatives

Alternative Why rejected
initContainer in the GeoServer Deployment Admin Secret present in every replica; N concurrent executions
Migration tool (Flyway, Liquibase) Oversized for one role and one schema; to reconsider for the data schemas
A single account for configuration and data No read-only access possible; coupling with the producer services
Systematic PostGIS installation in public Pollutes a shared database; a decision that belongs to the operator
search_path in the JDBC URL Duplicated in every datasource; if forgotten = tables created in public

Consequences

  • Data schemas are created and owned by their services; we provide the script and the reader-role convention.
  • Rotating a password = update the Secret + rerun the Job + restart GeoServer.
  • Sub-project 2 declares the JNDI resources in Tomcat from the same Secrets (keys GEOSERVER_DB_*, READER_*).