Implementation:Apache Airflow Database Connection Config

Knowledge Sources	Apache Airflow
Domains	Database, Kubernetes
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for configuring Airflow database connections in Kubernetes provided by the Helm chart values.yaml database sections.

Description

The Helm chart provides database configuration through the data.metadataConnection section (inline credentials) or data.metadataSecretName (existing Kubernetes Secret). The PostgreSQL subchart can be enabled for embedded database deployment. PgBouncer provides connection pooling as an optional sidecar.

Usage

Set database connection details in values.yaml. For production, use existing Kubernetes Secrets with external managed databases.

Code Reference

Source Location

Repository: Apache Airflow
File: chart/values.yaml (database sections at ~L3300-3400)
File: chart/values.schema.json (connection property schemas)

Signature

# Embedded PostgreSQL (development)
postgresql:
  enabled: true    # Deploy Bitnami PostgreSQL subchart

# External database
data:
  metadataSecretName: ~   # Use existing Kubernetes Secret
  metadataConnection:
    user: postgres
    pass: postgres
    protocol: postgresql
    host: ~
    port: 5432
    db: postgres
    sslmode: disable

# Connection pooling
pgbouncer:
  enabled: false
  maxClientConn: 100
  metadataPoolSize: 10

# Celery result backend
data:
  resultBackendSecretName: ~
  resultBackendConnection:
    user: postgres
    pass: postgres
    protocol: db+postgresql
    host: ~
    port: 5432
    db: postgres

# Redis (Celery broker)
redis:
  enabled: true

Import

# Deploy with external database
helm install airflow apache-airflow/airflow \
  --set postgresql.enabled=false \
  --set data.metadataSecretName=my-db-secret

I/O Contract

Inputs

Name	Type	Required	Description
postgresql.enabled	bool	No	Whether to deploy embedded PostgreSQL
data.metadataConnection	dict	Conditional	Inline DB credentials (if not using Secret)
data.metadataSecretName	str	Conditional	Existing K8s Secret name
pgbouncer.enabled	bool	No	Enable PgBouncer connection pooling

Outputs

Name	Type	Description
Database connection	Environment vars	Connection string mounted as AIRFLOW__DATABASE__SQL_ALCHEMY_CONN
Migrated schema	Database	Metadata DB with current Airflow schema
PgBouncer sidecar	Pod	Connection pooling proxy (if enabled)

Usage Examples

Production Database Setup

# my-values.yaml — Production with external RDS
postgresql:
  enabled: false

data:
  metadataSecretName: airflow-metadata-secret

pgbouncer:
  enabled: true
  maxClientConn: 200
  metadataPoolSize: 20

Related Pages

Implements Principle

Principle:Apache_Airflow_Database_Backend_Configuration

Requires Environment

Uses Heuristic

Heuristic:Apache_Airflow_Database_Lock_Handling

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment