How pilot reaches its database

From a page request in the browser to PostgreSQL on RDS in Cape Town, with the real names of every Worker, Hyperdrive config, tunnel and network piece. As deployed on 30 October 2026.

10 November 2026: the pilot environment becomes prod, the one deployed environment (ADR-0058). This page is kept as written.

One page request, step by step

  1. The browser asks for test.platform.catalystholdings.global. Cloudflare runs the web Worker.
  2. web calls gateway through a service binding. Workers call each other inside Cloudflare, not over the internet.
  3. gateway checks the session (through its Hyperdrive config identity), then calls the service that holds the data, for example analysis.
  4. The service sends its SQL to its own Hyperdrive config. Hyperdrive keeps a pool of open connections, so most queries skip the set-up.
  5. When Hyperdrive needs a new connection, it goes to db-pilot.catalystholdings.global and shows the …-pilot-hyperdrive service token. Access checks it.
  6. Access passes the connection into the Tunnel. The Tunnel carries it over the link cloudflared already opened from AWS.
  7. cloudflared, inside the VPC, connects to RDS on port 5432. Postgres requires TLS, and Hyperdrive checks RDS's certificate against Amazon's RDS root CA for af-south-1 (verify-ca).
  8. Postgres checks the login (platform_svc_analysis in this example) and its row-level security rules, then answers back along the same path.

Why the internet cannot reach the database

  • RDS has no public address (publicly accessible: false). Its name resolves to a private 10.40.x.x address.
  • The data subnets have no route out: only 10.40.0.0/16 local. No internet gateway, no NAT.
  • RDS's security group admits port 5432 from one source: the cloudflared security group. No IP ranges.
  • Nothing in AWS accepts a connection from outside. cloudflared dials out to Cloudflare through the NAT gateway, and its own security group only allows Cloudflare's tunnel port, RDS and the private endpoints.
  • The one public name, db-pilot.catalystholdings.global, ends at Cloudflare Access, which turns away anything without one of the two service tokens.
  • Past all that, every connection still needs a database user and password, over SSL.

Which Worker uses which connection

WorkerBindingHyperdrive configDatabase login
catalyst-platform-web-pilotnonenonenone: pages only, calls the gateway
catalyst-platform-gateway-pilotHYPERDRIVEcatalyst-platform-pilot-identityplatform_svc_identity
catalyst-platform-identity-pilotHYPERDRIVEcatalyst-platform-pilot-identityplatform_svc_identity
catalyst-platform-xero-connector-pilotHYPERDRIVEcatalyst-platform-pilot-xero-connectorplatform_svc_xero_connector
catalyst-platform-analysis-pilotHYPERDRIVEcatalyst-platform-pilot-analysisplatform_svc_analysis
RULES_HYPERDRIVEcatalyst-platform-pilot-analysis-rulesplatform_svc_analysis_rules
catalyst-platform-report-pilotHYPERDRIVEcatalyst-platform-pilot-reportplatform_svc_report
catalyst-platform-datahouse-pilotHYPERDRIVEcatalyst-platform-pilot-datahouseplatform_svc_datahouse
HYPERDRIVE_REIDcatalyst-platform-pilot-datahouse-reidplatform_svc_datahouse_reid
catalyst-platform-vas-pilotHYPERDRIVEcatalyst-platform-pilot-vasplatform_svc_vas
catalyst-platform-audit-pilotHYPERDRIVEcatalyst-platform-pilot-auditplatform_svc_audit

How migrations reach it

  1. infra/deploy/rds-from-poc.sh reads the …-pilot-ci-migrations token from Terraform (needs your AWS login, aicfo-pilot).
  2. It runs cloudflared access tcp to db-pilot.catalystholdings.global, which opens 127.0.0.1:15432 on your Mac.
  3. psql connects to that port as platform_owner (migrations, staff accounts) or as the RDS master user (creating roles; its password is in AWS Secrets Manager).
  4. The connection travels the same Access, Tunnel and cloudflared path as Hyperdrive's, and closes when the command ends.

Where each piece is defined

  • AWS, the Tunnel, Access and the tokens: Terraform infra/terraform/envs/pilot-aws-db, state in an encrypted S3 bucket in the same AWS account.
  • Hyperdrive configs, logins' passwords, R2 buckets: Terraform infra/terraform/envs/poc with pilot.tfvars, state in R2.
  • Workers and their bindings: each repository's wrangler.jsonc, deployed with infra/deploy/deploy-poc.sh.
  • Database roles and logins: rds-from-poc.sh bootstrap; schema from 0011_platform_baseline.sql.

Monthly running cost of the AWS side is about $141 to $143: the NAT gateway and the five private endpoints are about two thirds of it, the database about a quarter.