Database connection behavior reference

This reference documents database connection behavior that the control plane API enforces during Deployment upsert.

Scope

This document focuses on how Astro Private Cloud configures Deployment metadata and result backend connections.

It doesn’t cover infrastructure-level replication, backup, or recovery procedures.

For complete setup steps, see the following documents:

• Database architecture for database components, connection pooling, high availability, and production recommendations.
• Access Airflow database for connecting to the database, running queries, and backup and restore procedures.
• Bring your own Airflow database for manual metadata and result backend connections.
• Configure Kerberos authentication for Airflow databases for Kerberos-specific database setup.
• Programmatically create or update Deployments on Astro Private Cloud for upsert workflow details.

Default deployment database behavior

By default, Astro Private Cloud generates deployment-specific database connection details from:

• Global deployment configuration.
• Deployment release name.
• Cluster database type.

Generated connection details use:

• One deployment database name derived from release name.
• airflow schema for metadata.
• celery schema for result backend.
• Separate generated credentials for metadata and result backend access.

Configure provisioning behavior

Set global database behavior in deployment config:

1
deployments:
2
  databaseManagement:
3
    database:
4
      enabled: true
5
      retainOnDelete: false
6
      allowRootAccess: false

• enabled: false skips automatic generation of deployment connection details.
• retainOnDelete: true keeps deployment database resources after deployment deletion.
• allowRootAccess: true leaves root grants in place.

You can also set per-deployment behavior on upsert:

1
skipAirflowDatabaseProvisioning: Boolean

Manual connection input

Manual connection strings are disabled by default. To pass manual connection values in upsert payloads, set deployments.databaseManagement.manualConnectionStrings.enabled to true. In APC 2.x this is a deployments.* setting, so cluster, Workspace, and Deployment overrides take precedence over values.yaml. The recommended path is to add the following to the data plane cluster’s Configuration Override (cluster overrides apply to deployments.*, so don’t include the deployments. prefix):

1
databaseManagement:
2
  manualConnectionStrings:
3
    enabled: true

If disabled (the default), upsert rejects manual connection fields.

For manual connection setup and examples, see Bring your own Airflow database. For precedence between platform config and cluster, Workspace, and Deployment overrides, see Configure Astro Private Cloud.

PgBouncer input behavior

PgBouncer behavior applies through deployment chart config:

1
deployments:
2
  helm:
3
    airflow:
4
      pgbouncer:
5
        enabled: true

When PgBouncer is enabled for PostgreSQL-based Deployments:

• URI-style manual connection input is rejected.
• JSON-style manual connection input is required.

Expected JSON fields:

• metadataConnectionJson
• resultBackendConnectionJson

For Kerberos-driven PgBouncer usage, see Configure Kerberos authentication for Airflow databases.

Kerberos validation behavior

When kerberosEnabled is true in an upsert payload:

• Provide both metadata and result backend connections, either URI pair or JSON pair.
• Provide pgbouncerConfig.
• Set pgbouncerConfig.extraIniMetadata with user=.
• Set pgbouncerConfig.extraIniResultBackend with user=.
• Set pgbouncerConfig.sslmode.
• Set pgbouncerConfig.extraIni with:
  • server_gssauth_negotiate = allow
  • server_krb_spn

For payload examples and prerequisites, see Configure Kerberos authentication for Airflow databases and Bring your own Airflow database.