Managed PostgreSQL and Cloud SQL
Available in: Pro, Enterprise
Xberg needs a PostgreSQL database that you provision. This page lists what a managed PostgreSQL service must provide, then bootstraps an empty database on Google Cloud SQL for PostgreSQL 18.
The bootstrap script ships in the chart archive for both products. It runs from your machine and needs no superuser. AWS RDS and other managed services use the same steps with their own endpoint and administrator credential.
Requirements
Section titled “Requirements”| Requirement | Detail |
|---|---|
| Version | PostgreSQL 15 to 18. The non-superuser bootstrap supports 16 to 18. PostgreSQL 15 needs a true superuser. |
| Extensions | uuid-ossp, pgcrypto, btree_gin and vector (pgvector 0.8.0 or newer). The administrator must be able to create them. |
| Optional extension | vectorscale for DiskANN indexes. Cloud SQL does not offer it, so the product uses the pgvector HNSW path. On Enterprise set vectorstore.defaultIndexMethod: hnsw. |
| Administrator | A login with LOGIN, CREATEROLE, CREATEDB and database CREATE, without SUPERUSER, BYPASSRLS or REPLICATION. Provider role names such as cloudsqlsuperuser or rds_superuser are not required. |
| Roles | The bootstrap creates fixed roles and eight login roles. Roles are cluster-global. |
| Dedicated instance | Use one PostgreSQL instance for each independently administered Xberg deployment. Separate databases or custom login names do not isolate the fixed roles. |
Never give the administrator credential, the schema-owner credential or the physical-migration credential to a runtime pod. The chart never stores or mounts the administrator credential.
This procedure is for an empty database on a dedicated instance. The script accepts only an empty database or one it produced earlier. It refuses a database that already has Xberg roles or tables in public, before it changes anything.
It does not convert an existing Cloud SQL database. For an existing installation, contact support.
Bootstrap an empty database
Section titled “Bootstrap an empty database”-
Prepare the instance. Create an empty database and set a password for the built-in
postgreslogin. Keep its Cloud SQL defaults:LOGIN INHERIT CREATEROLE CREATEDB NOSUPERUSER NOBYPASSRLS NOREPLICATION, with direct membership incloudsqlsuperuser. Do not create Xberg roles yourself. -
Allow your machine to connect, through an authorized network path or the Cloud SQL Auth Proxy. The example uses the proxy on
127.0.0.1. Its local leg is plaintext, and the proxy encrypts the connection to Cloud SQL. -
Locate the chart files. Point
CHART_DIRat the extracted chart of the release you will install, eitherproorxberg-enterprise:Terminal window export CHART_DIR=/path/to/protest -f "$CHART_DIR/charts/_distribution/files/pro-db-bootstrap.sh" || exit 1test -f "$CHART_DIR/charts/_distribution/files/managed-postgres-fresh-bootstrap.sql" || exit 1 -
Set the connection and passwords. Choose eight distinct login passwords, each different from the administrator password. The
*_URLENCODEDvariables hold URL-safe encodings of the passwords. The plain variables hold the raw values.Terminal window export PGHOST=127.0.0.1export PGPORT=5432export PGSSLMODE=disableexport POSTGRES_DB=xbergexport POSTGRES_USER=postgresexport POSTGRES_PASSWORD=REPLACE_WITH_CLOUD_SQL_ADMINISTRATOR_PASSWORDexport PGPASSWORD="$POSTGRES_PASSWORD"export POSTGRES_APPLICATION_PASSWORD=REPLACE_WITH_APPLICATION_PASSWORDexport POSTGRES_MAINTENANCE_PASSWORD=REPLACE_WITH_MAINTENANCE_PASSWORDexport POSTGRES_SCHEMA_OWNER_PASSWORD=REPLACE_WITH_SCHEMA_OWNER_PASSWORDexport POSTGRES_MIGRATION_PASSWORD=REPLACE_WITH_SCHEMA_MIGRATOR_PASSWORDexport POSTGRES_ROLE_ADMIN_PASSWORD=REPLACE_WITH_ROLE_ADMIN_PASSWORDexport POSTGRES_INDEX_WORKER_PASSWORD=REPLACE_WITH_VECTOR_INDEX_WORKER_PASSWORDexport POSTGRES_VECTOR_BROKER_PASSWORD=REPLACE_WITH_VECTOR_BROKER_PASSWORDexport POSTGRES_PHYSICAL_MIGRATION_PASSWORD=REPLACE_WITH_PHYSICAL_MIGRATION_PASSWORDexport POSTGRES_PASSWORD_URLENCODED=REPLACE_WITH_PERCENT_ENCODED_ADMINISTRATOR_PASSWORDexport POSTGRES_MIGRATION_PASSWORD_URLENCODED=REPLACE_WITH_PERCENT_ENCODED_SCHEMA_MIGRATOR_PASSWORDexport DATABASE_URL="postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD_URLENCODED}@${PGHOST}:${PGPORT}/${POSTGRES_DB}"export MIGRATION_DATABASE_URL="postgresql://xberg_schema_migrator:${POSTGRES_MIGRATION_PASSWORD_URLENCODED}@${PGHOST}:${PGPORT}/${POSTGRES_DB}" -
Set the bootstrap options and run the script.
Terminal window export MIGRATION_PLAN_DATABASE=xberg_schema_planexport PLANNING_DATABASE_BOOTSTRAP=trueexport PLANNING_EXTENSIONS_FILE="$CHART_DIR/charts/_distribution/files/extensions-prepare.sql"export PRO_DB_BOOTSTRAP_MODE=standardexport PRO_DB_BOOTSTRAP_PHASE=allexport PRO_DB_INITIALIZE_SCHEMA=trueexport PRO_DB_DEFER_CLAIMS_ENABLE=trueexport SCHEMA_DIRECTORY="$CHART_DIR/charts/_distribution/files"sh "$CHART_DIR/charts/_distribution/files/pro-db-bootstrap.sh"The script creates the eight login roles, installs the schema and extensions, prepares the planning database (used to preview schema changes) and verifies the result.
-
If the script is interrupted, run it again with the same credentials. It validates what exists and finishes the rest.
-
Store the database URLs in the Secrets that your product’s install guide describes. Keep the schema-owner credential with the operator instead of placing it in Kubernetes. Never copy
POSTGRES_PASSWORDor its URL into a Kubernetes Secret or workload.
Install the chart
Section titled “Install the chart”-
Leave these values at their defaults (disabled) for a fresh database. They apply only to older installations:
migrations:planningDatabaseBootstrap: falsecloudSqlRoleBootstrap:enabled: false -
Follow the install steps for your product: Pro on Kubernetes or Enterprise on Kubernetes. The bootstrap already created the schema, so the migration hooks only validate and reconcile it in one Helm install.
-
When the product is Ready, rotate or remove the Cloud SQL administrator password from your operator environment.
Rotate an application login
Section titled “Rotate an application login”- Create the next Secret before you change a workload.
- Point
migrations.applicationDatabaseUrlSecretat the next URL whilesecrets.databaseUrlSecretstill selects the current URL. - Run the hooks and switch the workload selector.
- Verify readiness, then delete the old credential.