> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 does not cover infrastructure-level replication, backup, or recovery procedures.

For complete setup steps, see the following documents:

* [Database architecture](/docs/astro-private-cloud/v-1-x/database-architecture) for database components, connection pooling, high availability, and production recommendations.
* [Access Airflow database](/docs/astro-private-cloud/v-1-x/access-airflow-database) for connecting to the database, running queries, and backup and restore procedures.
* [Bring your own Airflow database](/docs/astro-private-cloud/v-1-x/multi-db) for manual metadata and result backend connections.
* [Configure Kerberos authentication for Airflow databases](/docs/astro-private-cloud/v-1-x/kerberos-database-setup) for Kerberos-specific database setup.
* [Programmatically create or update Deployments on Astro Private Cloud](/docs/astro-private-cloud/v-1-x/create-deployment-programmatic) 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:

```yaml wrap theme={null}
deployments:
  database:
    enabled: true
    retainOnDelete: false
    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:

```graphql wrap theme={null}
skipAirflowDatabaseProvisioning: Boolean
```

## Manual connection input

Manual connection strings are disabled by default. To pass manual connection values in upsert payloads, set `deployments.manualConnectionStrings.enabled` to `true`. Add the following to the data plane cluster's **Configuration Override**:

```json wrap theme={null}
{
  "manualConnectionStrings": {
    "enabled": true
  }
}
```

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

For manual connection setup and examples, see [Bring your own Airflow database](/docs/astro-private-cloud/v-1-x/multi-db). For precedence between platform config and cluster overrides, see [Configure Astro Private Cloud](/docs/astro-private-cloud/v-1-x/configure-astro-private-cloud).

## PgBouncer input behavior

PgBouncer behavior applies through deployment chart config:

```yaml wrap theme={null}
deployments:
  helm:
    airflow:
      pgbouncer:
        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](/docs/astro-private-cloud/v-1-x/kerberos-database-setup).

## 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](/docs/astro-private-cloud/v-1-x/kerberos-database-setup) and [Bring your own Airflow database](/docs/astro-private-cloud/v-1-x/multi-db).