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

# PostgreSQL Configuration

> Configuration for the in cluster PostgreSQL database used by the CrewAI Platform.

<Warning>
  The internal PostgreSQL option is **not intended for production use**. It
  provides no high-availability, automated backups, or enterprise-grade
  reliability features. Always use an external managed PostgreSQL service (AWS
  RDS, Azure Database, Google Cloud SQL, etc.) for production deployments.
</Warning>

<ParamField path="postgres.enabled" type="boolean" default="false">
  Enable or disable the built-in PostgreSQL subchart deployment.

  **Values:**

  * `true` - Deploy PostgreSQL as a StatefulSet in the cluster
  * `false` - Use external PostgreSQL database

  **When Enabled:** The chart creates:

  * PostgreSQL StatefulSet with 1 replica
  * PersistentVolumeClaim for data storage
  * ClusterIP Service at `<fullname>-postgres:5432`
  * Automatic `DB_HOST` environment variable configuration

  **When Disabled:** You must configure external database connection parameters:

  * `envVars.DB_HOST`
  * `envVars.DB_PORT`
  * `envVars.DB_USER`
  * `envVars.POSTGRES_DB`
  * `envVars.POSTGRES_CABLE_DB`
  * `envVars.POSTGRES_OAUTH_DB`
  * `secrets.DB_PASSWORD`

  **Pre-create databases:** With an external database, you must manually create all required databases before deploying: primary, cable, OAuth, and Wharf (`wharf` by default). See the [AWS](/cloud-providers/aws) or [GCP](/cloud-providers/gcp) guides for provider-specific instructions.
</ParamField>

<ParamField path="postgres.reset" type="boolean" default="false">
  <Warning>
    **Danger Zone:** When set to `true`, recreates the PostgreSQL data volume on next deployment, **permanently deleting all data**.
  </Warning>

  **Use Cases:**

  * Development environment reset
  * Testing clean installations
  * **Never use in production**
</ParamField>

<ParamField path="postgres.fullnameOverride" type="string" default="crewai-postgres">
  Override the full name used for PostgreSQL resources.

  **Purpose:** Controls the naming of PostgreSQL StatefulSet, Service, and other resources.

  **Default:** `"crewai-postgres"`

  **Impact:**

  * Service DNS name: `<fullnameOverride>.namespace.svc.cluster.local`
  * StatefulSet name: `<fullnameOverride>`
  * PVC name: `data-<fullnameOverride>-0`

  **When to Override:**

  * Deploying multiple PostgreSQL instances in same namespace
  * Specific naming requirements
  * Avoiding name conflicts

  **Note:** Changing this value after initial deployment may cause resource recreation.
</ParamField>

<ParamField path="postgres.image.host" type="string" default="">
  Container registry hosting the PostgreSQL image.

  **Default:** `""` (empty) - Automatically uses `global.imageRegistry` value

  **Fallback Behavior:**

  When `postgres.image.host` is empty or not set, the chart uses `global.imageRegistry` via the `crewai-platform.postgresImageRegistry` template helper. This allows you to configure the registry once at the global level.

  **When imageNamePrefixOverride is Set:**

  The image name is automatically simplified:

  * Original: `proxy/crewai/dockerhub/library/postgres`
  * With `imageNamePrefixOverride: "crewai/"` becomes: `crewai/postgres`

  See [global.imageNamePrefixOverride](/reference/chart-values/global#param-global-image-name-prefix-override) for details.

  **Example:**

  ```yaml theme={null}
  global:
    imageRegistry: "registry.company.com"

  postgres:
    enabled: true
    image:
      host: "" # Automatically uses registry.company.com
      name: "proxy/crewai/dockerhub/library/postgres"
      tag: "16"
  ```
</ParamField>

<ParamField path="postgres.image.name" type="string" default="proxy/crewai/dockerhub/library/postgres">
  PostgreSQL container image name.

  **Default:** `"proxy/crewai/dockerhub/library/postgres"` - Matches Replicated proxy path structure

  **Path Transformation:**

  When `global.imageNamePrefixOverride` is set, only the final component (`postgres`) is used with the override prefix.
</ParamField>

<ParamField path="postgres.image.tag" type="string" default="16">
  PostgreSQL version to deploy.

  **Supported Version:** PostgreSQL 16

  **Upgrade Consideration:** PostgreSQL major version upgrades require data migration. Do not change this value without planning for database migration.
</ParamField>

<ParamField path="postgres.image.pullPolicy" type="string" default="IfNotPresent">
  Image pull policy for PostgreSQL container.
</ParamField>

<ParamField path="postgres.image.pullSecret" type="string" default="">
  Image pull secret for PostgreSQL image. If empty, uses the global `image.pullSecret`.
</ParamField>

<ParamField path="postgres.database" type="string" default="crewai_plus_production">
  Name of the primary PostgreSQL database created during initialization.
</ParamField>

<ParamField path="postgres.cableDatabase" type="string" default="crewai_plus_cable_production">
  Name of the ActionCable database for WebSocket connections.

  **Purpose:** Rails ActionCable uses a separate database for pub/sub operations to isolate real-time communication from primary data operations.
</ParamField>

<ParamField path="postgres.oauthDatabase" type="string" default="oauth_db">
  Name of the Built-in Integrations service database for third-party integration token storage.

  **Purpose:** The Built-in Integrations service uses a separate database to store encrypted OAuth tokens for third-party integrations (Gmail, Google Calendar, Microsoft Outlook, etc.).

  **Auto-Creation:** When `postgres.enabled: true` and `oauth.enabled: true`, this database is automatically created during PostgreSQL initialization via an init script.

  **Database Isolation:** OAuth tokens are stored separately from the main application data for security and isolation.

  **Default:** `"oauth_db"`

  **Related Configuration:**

  * Built-in Integrations service: See [CrewAI Built-in Integrations Reference](/reference/chart-values/oauth)
  * OAuth secrets: See [Secrets Reference - Built-in Integrations Secrets](/reference/chart-values/secrets#built-in-integrations-secrets)
</ParamField>

<ParamField path="postgres.wharfDatabase" type="string" default="wharf">
  Name of the Wharf OTLP trace collector database for distributed tracing data storage.

  **Purpose:** The Wharf service uses a separate database to store OpenTelemetry traces and spans for application observability.

  **Auto-Creation:** When `postgres.enabled: true` and `wharf.enabled: true`, this database is automatically created during PostgreSQL initialization via an init script and before the Wharf service starts.

  **Database Isolation:** Trace data is stored separately from the main application data to isolate observability workloads and manage retention independently.

  **Default:** `"wharf"`

  **Related Configuration:**

  * Wharf service: See [Wharf OTLP Trace Collector Reference](/reference/chart-values/wharf)
  * Wharf secrets: See [Secrets Reference - Wharf Secrets](/reference/chart-values/secrets#wharf-secrets)
</ParamField>

<ParamField path="postgres.cubeDatabase" type="string" default="cube">
  Name of the Cube analytics database for cost tracking and execution analytics.

  **Purpose:** The Cube service uses a separate database to store analytics data, including provider usage metrics, cost tracking, and execution statistics.

  **Auto-Creation:** When `postgres.enabled: true` and `cube.enabled: true`, this database is automatically created during PostgreSQL initialization via an init script and before the Cube service starts.

  **Database Isolation:** Analytics data is stored separately from the main application data to isolate analytics workloads and manage retention independently.

  **Default:** `"cube"`

  **Related Configuration:**

  * Cube service: See [Cube Analytics Reference](/reference/chart-values/cube)
  * Cube secrets: See [Secrets Reference - Cube Analytics Secrets](/reference/chart-values/secrets#cube-analytics-secrets)
</ParamField>

<ParamField path="postgres.persistence.size" type="string" default="10Gi">
  Size of the persistent volume for PostgreSQL data.

  **Sizing Guidelines:**

  * **Small deployment (\< 100 users):** 10-20Gi
  * **Medium deployment (100-500 users):** 50-100Gi
  * **Large deployment (> 500 users):** 100Gi+

  **Note:** This value cannot be decreased after initial deployment. Plan for growth.
</ParamField>

<ParamField path="postgres.persistence.reclaimPolicy" type="string" default="keep">
  PersistentVolume reclaim policy when the PVC is deleted.

  **Valid Values:**

  * `"keep"` - Retain volume data after PVC deletion (recommended)
  * `"delete"` - Delete volume data when PVC is deleted
</ParamField>

<ParamField path="postgres.persistence.storageClassName" type="string" default="">
  Kubernetes StorageClass to use for the persistent volume.

  **Common Values:**

  * `""` - Use default StorageClass
  * `"gp3"` - AWS EBS GP3 volumes
  * `"managed-premium"` - Azure Premium SSD
  * `"standard-rwo"` - GKE Standard persistent disk

  **Performance Consideration:** Use SSD-backed storage classes for better database performance.
</ParamField>

### `postgres.resources.*`

Resource limits and requests for PostgreSQL container.

<ParamField path="postgres.resources.limits.cpu" type="string" default="1">
  CPU limit for PostgreSQL pod.

  **Sizing Guidelines:**

  * Small deployment: `"1"`
  * Medium deployment: `"2"`
  * Large deployment: `"4"` or higher
</ParamField>

<ParamField path="postgres.resources.limits.memory" type="string" default="2Gi">
  Memory limit for PostgreSQL pod.

  **Sizing Guidelines:**

  * Small deployment: `"2Gi"`
  * Medium deployment: `"4Gi"`
  * Large deployment: `"8Gi"` or higher
</ParamField>

<ParamField path="postgres.resources.requests.cpu" type="string" default="500m">
  Guaranteed CPU allocation for PostgreSQL pod.
</ParamField>

<ParamField path="postgres.resources.requests.memory" type="string" default="1Gi">
  Guaranteed memory allocation for PostgreSQL pod.
</ParamField>

<ParamField path="postgres.nodeSelector" type="object" default="{}">
  Kubernetes node selector for PostgreSQL pod placement.

  **Example:**

  ```yaml theme={null}
  postgres:
    nodeSelector:
      node-role.kubernetes.io/database: "true"
      topology.kubernetes.io/zone: us-west-2a
  ```

  **Use Cases:**

  * Pin database to specific nodes with fast local storage
  * Ensure database runs in specific availability zones
  * Separate database workload from application workload
</ParamField>