BigHammer setup scripts

The bighammer Helm chart includes two setup scripts under scripts/. Use them to prepare Cloud SQL and Secret Manager before the platform chart is installed.

Script	Purpose
`bighammer_db_setup.sql`	Create database, roles, schemas, and grants on Cloud SQL
`bh_gsm_onetime_setup.sh`	One-time GSM secrets (platform prerequisites verified via gcloud)

Both files ship inside the chart package under scripts/.

Get the scripts from the chart

After you mirror or pull the chart, extract it and open scripts/:

# Example: chart already pulled to the current directory
tar -xzf bighammer-<version>.tgz
cd bighammer/scripts
ls
# bighammer_db_setup.sql  bh_gsm_onetime_setup.sh

From your mirrored GAR (after helm registry login):

helm pull oci://<region>-docker.pkg.dev/<project>/bh-helm-release/bighammer \
  --version <CHART_VERSION>
tar -xzf bighammer-<CHART_VERSION>.tgz
cd bighammer/scripts

Recommended order

Step	Action	When
0	Provision Cloud SQL instance, databases, users, and platform GSM passwords (Terraform, console, or automation)	Once per environment
1	`bighammer_db_setup.sql`	Schemas and grants inside the application database
2	`bh_gsm_onetime_setup.sh`	Verifies platform prerequisites in GSM; creates one-time app secrets
3	Cluster preparation	ESO, edge, RabbitMQ, TLS
4	Helm install	Platform Deployment

Keycloak database — Terraform only

The Keycloak server pod (bhkeycloak) is not on bighammer_db_<env>. Terraform provisions:

Resource	Reference name	Chart mapping
Database	`keycloak_db_<env>`	`global.bhkeycloak.env.KC_DB_URL` (JDBC path)
User	`keycloak_db_user`	`global.bhkeycloak.env.KC_DB_USERNAME`
Password	GSM `bh-kcdbpwd`	`KC_DB_PASSWORD` via `global.remoteSecrets.keycloak.dbPassword`

bighammer_db_setup.sql does not create or grant on keycloak_db_<env>. After Terraform, ensure keycloak_db_user has CONNECT and CREATE on keycloak_db_<env> (Keycloak creates its own tables in public).

If database or user names differ from the reference defaults, see Renaming databases or users for every Helm values field to update.

See Secret Manager Secrets and Infrastructure — Cloud SQL.

Keycloak database (Terraform)

Reference environments provision keycloak_db_<env> and keycloak_db_user with Terraform alongside bighammer_db_<env>. Only the bhkeycloak chart subchart consumes them.

# values-<env>.yaml (reference)
global:
  remoteSecrets:
    keycloak:
      dbPassword: bh-kcdbpwd          # GSM → KC_DB_PASSWORD

  bhkeycloak:
    env:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://<PRIVATE_IP>:5432/keycloak_db_<env>?ssl=true&sslmode=verify-ca&...
      KC_DB_USERNAME: keycloak_db_user
      KC_DB_HOST: <PRIVATE_IP>
      KC_DB_PORT: 5432

Item	Notes
`keycloak_db_<env>`	Separate from application DB; Keycloak SSO tables only
`keycloak_db_user`	Not `bh_dev_user` / `bh_app_user`; password in `bh-kcdbpwd` only
`bhkeycloakapi`	Uses `bighammer_db_<env>` + schema `keycloakapi_db` — different from Keycloak server DB

Renaming during provisioning: Infrastructure — rename checklist (1 KC_DB_URL + 1 KC_DB_USERNAME in chart values).

`bighammer_db_setup.sql`

PostgreSQL bootstrap for the application database on Cloud SQL. Run as postgres over a secure connection.

Database name

Reference environments use bighammer_db_<env> (created by Terraform). The script defaults to bighammer_db — comment out CREATE DATABASE and change \connect to bighammer_db_<env> when the database already exists.

What it creates (inside the application database)

Object	Name / detail
Database	`bighammer_db` in script — use `bighammer_db_<env>` when Terraform already created it
Roles	`bh_dev_user` (migrations / DDL), `bh_app_user` (runtime DML) — usually already exist from Terraform
Schemas	`catalog_db`, `agent_db`, `llm_observability_db`, `celery_db`, `audit_db`, `keycloakapi_db`
Extension	`vector` in `catalog_db` (pgvector)
Grants	`bh_dev_user` — full DDL on schemas; `bh_app_user` — DML + execute; default privileges for future objects

Dual-role database users

The setup script defines two PostgreSQL roles on bighammer_db_<env>. Helm services that run Alembic at startup and serve traffic at runtime mount both credential pairs:

Role	Chart env vars	GSM password secret	Purpose
`bh_dev_user`	`POSTGRES_USER`, `POSTGRES_PASSWORD`	`bh-dev-user-password`	Alembic migrations — `CREATE`/`DROP`/`ALTER` tables, schema DDL
`bh_app_user`	`BH_APP_USER`, `BH_APP_USER_PASSWORD`	`bh-app-user-password`	Runtime SQLAlchemy — `SELECT`/`INSERT`/`UPDATE`/`DELETE` only

Privileges from the script (cross-validated with bighammer_db_setup.sql):

Role	Schemas	Tables / sequences / functions
`bh_dev_user`	`USAGE`, `CREATE` on `catalog_db`, `agent_db`, `llm_observability_db`, `celery_db`, `audit_db`, `keycloakapi_db`	ALL PRIVILEGES (DDL + DML)
`bh_app_user`	`USAGE` only — no `CREATE`	DML on tables; `USAGE`/`SELECT` on sequences; `EXECUTE` on functions

ALTER DEFAULT PRIVILEGES FOR ROLE bh_dev_user grants future objects created during migrations to bh_app_user automatically.

Chart services that use both env var pairs:

Service	Schema
`bhcatalogapi`, `bhcatalogworker`	`catalog_db`
`bhauditapi`, `bhauditworker`	`audit_db`
`bhaiagent`, `bhaiagentworker`	`agent_db`
`bhcelerybeat`	`celery_db`
`bhkeycloakapi`	`keycloakapi_db`

Configure values so POSTGRES_USER: bh_dev_user and BH_APP_USER: bh_app_user, and set global.remoteSecrets.postgres.password to bh-dev-user-password. See Secret Manager Secrets — dual-role.

Does not provision keycloak_db_<env> — that database is separate; see Infrastructure.

Before you run

Replace placeholders in the file (if creating roles manually):
- REPLACE_ME_BH_DEV_USER → password for bh_dev_user (must match GSM bh-dev-user-password)
- REPLACE_ME_BH_APP_USER → password for bh_app_user (must match GSM bh-app-user-password)
If bighammer_db_<env> already exists (Terraform), comment out CREATE DATABASE and use \connect bighammer_db_<env>.
If roles already exist from Terraform, the CREATE ROLE block is skipped safely (IF NOT EXISTS).
Ensure Cloud SQL SSL is configured if you connect with sslmode=require.

Run

From the extracted chart directory (bighammer/scripts/):

# Option 1 — host/port env vars
export POSTGRES_HOST=<cloud-sql-private-ip>
export POSTGRES_PORT=5432
psql -h "$POSTGRES_HOST" -p "$POSTGRES_PORT" -U postgres -d postgres \
  -v ON_ERROR_STOP=1 \
  -f bighammer_db_setup.sql

# Option 2 — connection string (SSL)
psql "host=$POSTGRES_HOST port=$POSTGRES_PORT user=postgres dbname=postgres sslmode=require" \
  -v ON_ERROR_STOP=1 \
  -f bighammer_db_setup.sql

Run from a host that can reach Cloud SQL (bastion, Cloud Shell with authorized network, or VPN).

Verify

psql "host=$POSTGRES_HOST ... sslmode=require" -U postgres -d bighammer_db_<env> -c "\dn"
psql "host=$POSTGRES_HOST ... sslmode=require" -U bh_app_user -d bighammer_db_<env> -c "SELECT 1"

`bh_gsm_onetime_setup.sh`

One-time Google Secret Manager setup for application secrets. Platform prerequisite secrets must already exist in GSM (provisioned via Terraform, console, or other automation). This script verifies them with gcloud secrets describe and creates one-time secrets only if they do not already exist.

Platform prerequisites (gcloud verify only)

Must exist in Secret Manager before Helm deploy — not created by this script:

GSM secret	Required	Purpose
`bh-dev-user-password`	Yes	`bh_dev_user` (migrations)
`bh-app-user-password`	Yes	`bh_app_user` (runtime)
`db-postgres-password`	Yes	`postgres` admin
`bh-kcdbpwd`	Yes	`keycloak_db_user`
`db-client-cert`	No	Cloud SQL client cert (if SSL client auth enabled)
`db-server-ca-cert`	No	Cloud SQL server CA (if SSL client auth enabled)
`db-client-private-key`	No	Cloud SQL client key PEM (if SSL client auth enabled)

The script lists required secrets as OK or MISSING and exits with an error if any required secret is missing. Optional SSL secrets print WARN when absent — skip them if postgresSSLMode does not require client certs.

One-time setup (created by this script if missing)

GSM secret	Env var	Purpose
`bh-kcadminpwd`	`KC_ADMIN_PWD`	Keycloak admin password
`bh-keycloak-grant-type`	`KC_GRANT_TYPE`	Grant type (default: `password`)
`bh-catalog-decryption-key`	`DECRYPTION_KEY`	Catalog decryption key
`bh-temp-tenant-user-password`	`TEMP_TENANT_PASSWORD`	Temporary tenant password
`bh-rabbitmq-password`	`RABBITMQ_PASSWORD`	RabbitMQ password
`bh-redis-password`	`REDIS_PASSWORD`	Redis password
`bh-langchain-api-key`	`LANGCHAIN_API_KEY`	LangChain API key
`bh-oauth-token`	`OAUTH_TOKEN`	OAuth token
`license-catalog`	`LICENSE_CATALOG`	Catalog license
`license-catalog-pub-key`	`LICENSE_CATALOG_PUB_KEY`	License public key
`db-client-private-key-der`	(file)	Keycloak JDBC SSL DER key — see below
`bh-gcp-sa-key`	`GCP_SA_KEY_FILE`	Service account JSON for bhkeycloakapi — dev overlay only (`global.dev.enabled: true`)

TLS secrets <env>-gcp-bighammer-tls-crt / <env>-gcp-bighammer-tls-key are normally created by cert-manager PushSecret (script prints a reminder only).

Usage

cd bighammer/scripts

# Default project (<your-gcp-project>) or pass PROJECT_ID as first argument
./bh_gsm_onetime_setup.sh

# Specific project
./bh_gsm_onetime_setup.sh <GCP_PROJECT_ID>

# Or set GCP_PROJECT and edit placeholder values / env vars in the script
export GCP_PROJECT=<GCP_PROJECT_ID>
export RABBITMQ_PASSWORD='...' REDIS_PASSWORD='...'  # optional overrides
./bh_gsm_onetime_setup.sh

Default project: first argument, then GCP_PROJECT env var, then <your-gcp-project>.

Optional: `db-client-private-key-der`

Convert from the PEM client key in GSM (db-client-private-key):

gcloud secrets versions access latest --secret=db-client-private-key --project=<PROJECT> > certs/client-key.pem
openssl pkcs8 -topk8 -inform PEM -outform DER -in certs/client-key.pem -out certs/client-key.der -nocrypt

Re-run the script; it creates db-client-private-key-der from certs/client-key.der.

Optional: `bh-gcp-sa-key` (dev overlay only)

Required only when deploying with global.dev.enabled: true (e.g. values-dev.yaml). The bhkeycloakapi chart syncs this secret to a dummy.json mount. Skip if your values overlay does not enable the dev block.

export GCP_SA_KEY_FILE=/path/to/service-account-key.json
gcloud secrets create bh-gcp-sa-key \
  --project=<GCP_PROJECT_ID> \
  --replication-policy=automatic \
  --data-file="$GCP_SA_KEY_FILE"

Or re-run this script after placing the file at certs/gcp-sa-key.json in the chart directory.

Verify

gcloud secrets list --project=<GCP_PROJECT_ID> \
  --filter='name~bh-|name~db-|name~license|name~dev-gcp'

Topic	Link
GSM name mapping	Secret Manager Secrets
Keycloak DB (`keycloak_db_<env>`, `keycloak_db_user`)	Keycloak server database
Renaming DBs / users in chart values	Infrastructure — rename checklist
Cloud SQL prerequisites	Infrastructure
Mirror the chart	Release Manifest & Distribution
Pre-install checklist	Deployment Checklist

Get the scripts from the chart​

Recommended order​

Keycloak database (Terraform)​

bighammer_db_setup.sql​

What it creates (inside the application database)​

Dual-role database users​

Before you run​

Run​

Verify​

bh_gsm_onetime_setup.sh​

Platform prerequisites (gcloud verify only)​

One-time setup (created by this script if missing)​

Usage​

Optional: db-client-private-key-der​

Optional: bh-gcp-sa-key (dev overlay only)​

Verify​

Related​

Get the scripts from the chart

Recommended order

Keycloak database (Terraform)

`bighammer_db_setup.sql`

What it creates (inside the application database)

Dual-role database users

Before you run

Run

Verify

`bh_gsm_onetime_setup.sh`

Platform prerequisites (gcloud verify only)

One-time setup (created by this script if missing)

Usage

Optional: `db-client-private-key-der`

Optional: `bh-gcp-sa-key` (dev overlay only)

Verify

Related