Skip to content

Preparing the database

This section guides you through configuring the optional persistent database storage for your IQ Integrator.

Production deployments require a PostgreSQL database to maintain conversation state and session memory across pod restarts and deployments. Select one of the three persistent storage options based on your deployment environment.

Warning

If you do not configure a persistent database, the system defaults to a temporary, in-memory SQLite database that deletes all session data whenever a pod restarts.

Choose from the following database configurations:

  • An internal PostgreSQL database provisioned automatically by your Digital Experience (DX) Persistence Node for Kubernetes-only deployments.
  • An external PostgreSQL instance located outside your DX deployment, such as a cloud-managed, on-premises, or separate Kubernetes cluster database.
  • A PostgreSQL database provisioned and managed automatically within your DX deployment by your DX Runtime Controller (RTC).

Configuring an internal database

Use this option to automatically provision a PostgreSQL database within your DX deployment. Upgrade the DX deployment to create the database, and then deploy IQ to connect to it.

Important

  • When upgrading the IQ release (dx-iq) in this section, always use -f custom-iq-values.yaml without --reuse-values. The --reuse-values flag can cause configuration drift by preserving old values not in your custom values file.
  • Use the same custom-iq-values.yaml file you created in Deploying IQ services. Add the database configuration values shown in this section to that file, then run all helm upgrade commands with -f custom-iq-values.yaml.

Prerequisites

Before configuring the internal database, verify that your DX deployment (<DX_RELEASE_NAME>) is fully operational within your target namespace (<DX_NAMESPACE>) and includes an active Persistence Node.

Verifying an existing database setup

If your DX deployment was recently provisioned or upgraded with IQ database credentials and networking configuration, the iqdb database and user might already exist. Run the following commands to verify.

  1. Check for an existing IQ database:

    kubectl exec -n <DX_NAMESPACE> <DX_RELEASE_NAME>-persistence-node-0 -c persistence-node -- \
  psql -U postgres -c "\l" | grep iq
    • <DX_NAMESPACE>: The DX deployment namespace.
    • <DX_RELEASE_NAME>: The DX Helm release name.

  2. Check for an existing IQ user:

    kubectl exec -n <DX_NAMESPACE> <DX_RELEASE_NAME>-persistence-node-0 -c persistence-node -- \
  psql -U postgres -c "\du" | grep -i iq

If both exist, you can go directly to Deploying IQ with database configuration. If either is missing, proceed to the following provisioning section.

Provisioning the database

DX configuration management

The custom-values.yaml file is the primary configuration file for DX deployments. For detailed information on how to create and manage this file, refer to Prepare Configuration.

  1. Add the IQ database configuration to your DX custom-values.yaml file:

    security:
  iq:
    dbUser: "dx_iq_db_user"
    dbPassword: "<SECURE_PASSWORD>"

networking:
  dxIqService: "<IQ_RELEASE_NAME>-integrator"
    • <SECURE_PASSWORD>: A secure password for the IQ database user.
    • <IQ_RELEASE_NAME>: The IQ Helm release name (for example, dx-iq). The service name typically follows the <IQ_RELEASE_NAME>-integrator format.

    Important

    Setting networking.dxIqService enables the Persistence Node to pass the IQ_DB_USER and IQ_DB_PASSWORD environment variables to the PostgreSQL initialization script. This is required for automatic database and user creation.

  2. Upgrade your DX deployment to enable IQ database provisioning and automatically generate the database secret:

    helm upgrade <DX_RELEASE_NAME> \
  https://<YOUR_REPOSITORY_FQDN_AND_PATH>/<DX_HELM_CHART_VERSION>.tgz \
  --namespace <DX_NAMESPACE> \
  -f custom-values.yaml
    • <DX_RELEASE_NAME>: The DX Helm release name.
    • <DX_NAMESPACE>: The DX deployment namespace.
    • <YOUR_REPOSITORY_FQDN_AND_PATH>: The repository fully qualified domain name (FQDN) and path.
    • <DX_HELM_CHART_VERSION>: The DX Helm chart version.

    Configuration management

    Do not use --reuse-values in production environments to prevent configuration drift.

    To find available Helm chart versions in your repository, search in the user interface or run a curl command. For example, in JFrog Artifactory:

    curl -u <USERNAME>:<TOKEN> "https://<YOUR_REPOSITORY_FQDN_AND_PATH>/"

  3. Monitor the Persistence Node logs to track database and user initialization:

    1. Monitor the Persistence Node logs:

      kubectl logs -n <DX_NAMESPACE> <DX_RELEASE_NAME>-persistence-node-0 | grep -i "iq"

      Output:

      Creating IQ user "dx_iq_db_user"...
Creating IQ database "iqdb"...

    2. Run the following command to verify database and user creation:

      kubectl exec -n <DX_NAMESPACE> <DX_RELEASE_NAME>-persistence-node-0 -c persistence-node -- \
  psql -U postgres -c "\du" | grep dx_iq_db_user

Deploying IQ with database configuration

  1. Update your custom-iq-values.yaml file with the database configuration using one of the following options:

    Add the following configuration block to your custom-iq-values.yaml file:

    configuration:
  database:
    enabled: true
    dbHost: "<DX_RELEASE_NAME>-persistence-node-0.<DX_RELEASE_NAME>-persistence-headless-svc.<DX_NAMESPACE>.svc.cluster.local"
    dbPort: 5432
    dbName: "iqdb"
    dbUser: "dx_iq_db_user"
    dbPassword: "<SECURE_PASSWORD>"

    Add the following configuration block to your custom-iq-values.yaml file, referencing the secret generated by your DX deployment upgrade in Step 2 of Provisioning the database:

    configuration:
  database:
    enabled: true
    dbHost: "<DX_RELEASE_NAME>-persistence-node-0.<DX_RELEASE_NAME>-persistence-headless-svc.<DX_NAMESPACE>.svc.cluster.local"
    dbPort: 5432
    dbName: "iqdb"
    dbCustomSecret: "custom-credentials-iq-db"
    • <DX_RELEASE_NAME>: The DX Helm release name.
    • <DX_NAMESPACE>: The DX deployment namespace.

    Same namespace required

    This option only works when your IQ deployment is in the same Kubernetes namespace as your DX deployment. Kubernetes secrets are namespace-scoped and cannot be referenced across namespaces. If IQ is deployed in a different namespace, use the database credentials option.

  2. Upgrade your IQ deployment with your updated custom-iq-values.yaml file:

    helm upgrade dx-iq \
  https://<YOUR_REPOSITORY_FQDN_AND_PATH>/<IQ_HELM_CHART_VERSION>.tgz \
  --namespace <DX_NAMESPACE> \
  -f custom-iq-values.yaml
    • <YOUR_REPOSITORY_FQDN_AND_PATH>: The repository FQDN and path.
    • <IQ_HELM_CHART_VERSION>: The IQ Helm chart version.

  3. Verify that the database credentials are configured based on your chosen configuration option:

    Verify that the ConfigMap was created:

    kubectl get configmap -n <DX_NAMESPACE> dx-iq-integrator
kubectl describe configmap -n <DX_NAMESPACE> dx-iq-integrator

    Verify that the referenced DX secret exists in the namespace:

    kubectl get secret -n <DX_NAMESPACE> custom-credentials-iq-db
kubectl describe secret -n <DX_NAMESPACE> custom-credentials-iq-db

Configuring an external database

Use this option to connect to an existing PostgreSQL database located outside of your DX deployment. Create a Kubernetes secret to store the credentials, and then deploy IQ to connect to it.

Network connectivity requirement

Your Kubernetes cluster must have outbound network access to reach the external database server. If your cluster is isolated or behind a firewall, ensure:

  • Egress rules allow outbound traffic on the database port (TCP port 5432 for PostgreSQL).
  • Security groups (AWS) or firewall rules (GCP or Azure) permit connections to the external database host.
  • Network policies allow egress traffic to external networks when using Calico or another Container Network Interface (CNI).

If connectivity fails with ENETUNREACH or Network is unreachable errors, contact your infrastructure team to enable outbound access to the external database.

  1. Create a Kubernetes secret to store your external database credentials:

    Note

    This section uses the static name custom-external-db-credentials. If you modify this name, you must update the dbCustomSecret property in later steps to match.

    kubectl create secret generic custom-external-db-credentials \
  --namespace <YOUR_NAMESPACE> \
  --from-literal=username=<DB_USERNAME> \
  --from-literal=password=<DB_PASSWORD>
    • <YOUR_NAMESPACE>: The Kubernetes namespace.
    • <DB_USERNAME>: The database username.
    • <DB_PASSWORD>: The database password.

  2. Verify that the secret was created successfully:

    kubectl get secret custom-external-db-credentials -n <YOUR_NAMESPACE>
kubectl describe secret custom-external-db-credentials -n <YOUR_NAMESPACE>

  3. Update your custom-iq-values.yaml file to define the external database connection settings, referencing the custom-external-db-credentials secret name from Step 1:

    configuration:
  database:
    enabled: true
    dbHost: "<EXTERNAL_DB_HOST>"
    dbPort: 5432
    dbName: "<DB_NAME>"
    dbCustomSecret: "custom-external-db-credentials"

    • <EXTERNAL_DB_HOST>: The hostname or IP address of the external PostgreSQL server. For example:

      External server Values
      AWS RDS PostgreSQL iq-postgres.c9akciq32.us-east-1.rds.amazonaws.com
      Azure Database for PostgreSQL myserver.postgres.database.azure.com
      Google Cloud SQL Use Cloud SQL Auth proxy or instance IP (for example, 10.0.1.5)
      Different Kubernetes cluster The fully qualified DNS name or IP address of the PostgreSQL server accessible from the cluster network
      On-premises or external The reachable hostname or IP address (for example, postgres.company.internal or 192.168.1.50)

    • dbHost: The actual PostgreSQL server hostname or IP.

    • dbName: The IQ database name.
    • custom-external-db-credentials: The secret name from Step 1.

  4. Upgrade your IQ deployment with your updated custom-iq-values.yaml file:

    helm upgrade dx-iq \
  https://<YOUR_REPOSITORY_FQDN_AND_PATH>/<IQ_HELM_CHART_VERSION>.tgz \
  --namespace <YOUR_NAMESPACE> \
  -f custom-iq-values.yaml
    • <YOUR_REPOSITORY_FQDN_AND_PATH>: The repository FQDN and path.
    • <IQ_HELM_CHART_VERSION>: The IQ Helm chart version.

  5. Upgrade your DX deployment to enable IQ:

    1. Retrieve your current DX deployment Helm chart version:

      helm list -n <YOUR_NAMESPACE>
helm get all <DX_RELEASE_NAME> --namespace <YOUR_NAMESPACE>

    2. Add the IQ service configuration to your DX custom-values.yaml file:

      networking:
  dxIqService: "<IQ_SERVICE_NAME>"

      <IQ_SERVICE_NAME>: The Kubernetes service name for the IQ deployment, which typically follows the {{ .Release.Name }}-integrator format (for example, if the release name is dx-iq, the service name is dx-iq-integrator).

    3. Upgrade the DX deployment with your updated custom-values.yaml file:

      helm upgrade <DX_RELEASE_NAME> \
  https://<YOUR_REPOSITORY_FQDN_AND_PATH>/<DX_HELM_CHART_VERSION>.tgz \
  --namespace <YOUR_NAMESPACE> \
  -f custom-values.yaml
      • <DX_RELEASE_NAME>: The DX Helm release name (for example, dx-deployment).
      • <DX_HELM_CHART_VERSION>: The DX Helm chart version.

      Configuration management

      Always use your custom-values.yaml file for configuration changes instead of --set flags. For more information refer to Prepare configuration.

      To find available Helm chart versions in your repository, search in the user interface or run a curl command. For example, in JFrog Artifactory:

      curl -u <USERNAME>:<TOKEN> "https://<YOUR_REPOSITORY_FQDN_AND_PATH>/"

Configuring an RTC-managed database

Use this option to automatically provision and manage a PostgreSQL database within the DX deployment using the DX RTC.

  1. Create the IQ database credentials secrets:

    1. Delete the existing IQ database credentials secrets if they exist from a previous installation:

      kubectl delete secret custom-credentials-iq-db -n <YOUR_NAMESPACE> --ignore-not-found
kubectl delete secret <DX_RELEASE_NAME>-custom-credentials-iq-db -n <YOUR_NAMESPACE> --ignore-not-found
kubectl delete secret <DX_RELEASE_NAME>custom-credentials-iq-db-previous-value -n <YOUR_NAMESPACE> --ignore-not-found
      • <YOUR_NAMESPACE>: The Kubernetes namespace.
      • <DX_RELEASE_NAME>: The DX Helm release name (for example, dx-deployment).

    2. Create the new secrets:

      1. Create the base secret:

        kubectl create secret generic custom-credentials-iq-db \
--namespace <YOUR_NAMESPACE> \
--from-literal=username=<DB_USERNAME> \
--from-literal=password=<DB_PASSWORD>
        • <DB_USERNAME>: The database username.
        • <DB_PASSWORD>: The database password.

      2. Create the release-specific secret:

        kubectl create secret generic <DX_RELEASE_NAME>-custom-credentials-iq-db \
--namespace <YOUR_NAMESPACE> \
--from-literal=username=<DB_USERNAME> \
--from-literal=password=<DB_PASSWORD>

      3. Create the previous-value secret:

        kubectl create secret generic <DX_RELEASE_NAME>custom-credentials-iq-db-previous-value \
--namespace <YOUR_NAMESPACE> \
--from-literal=username=<DB_USERNAME> \
--from-literal=password=<DB_PASSWORD>

  2. Verify that the secrets were created:

    1. Verify that the base secret exists:

      kubectl get secret custom-credentials-iq-db -n <YOUR_NAMESPACE>
kubectl describe secret custom-credentials-iq-db -n <YOUR_NAMESPACE>

    2. Verify that the release-specific secret exists:

      kubectl get secret <DX_RELEASE_NAME>-custom-credentials-iq-db -n <YOUR_NAMESPACE>
kubectl describe secret <DX_RELEASE_NAME>-custom-credentials-iq-db -n <YOUR_NAMESPACE>

    3. Verify that the previous-value secret exists:

      kubectl get secret <DX_RELEASE_NAME>custom-credentials-iq-db-previous-value -n <YOUR_NAMESPACE>
kubectl describe secret <DX_RELEASE_NAME>custom-credentials-iq-db-previous-value -n <YOUR_NAMESPACE>

  3. Upgrade the DX deployment to enable RTC database management for IQ:

    1. Retrieve the current DX deployment Helm chart version:

      helm list -n <YOUR_NAMESPACE>
helm get all <DX_RELEASE_NAME> --namespace <YOUR_NAMESPACE>

    2. Add the RTC database configuration to your DX custom-values.yaml file:

      configuration:
  digitalAssetManagement:
    newDbManagement: true

networking:
  dxIqService: "<IQ_SERVICE_NAME>"

security:
  iq:
    customDbSecret: "custom-credentials-iq-db"

      <IQ_SERVICE_NAME>: The Kubernetes service name for the IQ deployment, which typically follows the {{ .Release.Name }}-integrator format (for example, if the IQ release name is dx-iq, the service name is dx-iq-integrator).

    3. Upgrade the DX deployment with your updated custom-values.yaml file:

      helm upgrade <DX_RELEASE_NAME> \
  https://<YOUR_REPOSITORY_FQDN_AND_PATH>/<DX_HELM_CHART_VERSION>.tgz \
  --namespace <YOUR_NAMESPACE> \
  -f custom-values.yaml
      • <DX_HELM_CHART_VERSION>: The DX Helm chart version.
      • <YOUR_REPOSITORY_FQDN_AND_PATH>: The repository FQDN and path to specified package or image.

      To find available Helm chart versions in your repository, search in the user interface or run a curl command. For example, in JFrog Artifactory:

      curl -u <USERNAME>:<TOKEN> "https://<YOUR_REPOSITORY_FQDN_AND_PATH>/"

  4. Monitor the RTC logs to track database creation:

    kubectl logs -n <YOUR_NAMESPACE> deployment/<DX_RELEASE_NAME>-runtime-controller | grep -i "iq"

    Output:

    IQ database setup completed successfully.

    To verify persistence layer initialization:

    kubectl logs -n <YOUR_NAMESPACE> deployment/<DX_RELEASE_NAME>-runtime-controller | grep -E "persistence|pgpool"

  5. After the RTC pod is running and the database is initialized, run a shell script to configure pgpool to recognize the IQ database user:

    1. Create the add-iq-user-to-pgpool.sh script file:

      #!/bin/bash

IQ_USER="<DB_USERNAME>"
IQ_PASS="<DB_PASSWORD>"
POD_NAME=$(kubectl get pods -n <YOUR_NAMESPACE> -l app=dx-deployment-persistence-connection-pool -o jsonpath='{.items[0].metadata.name}')
NAMESPACE="<YOUR_NAMESPACE>"

echo "1. Generating MD5 hash..."
HASH=$(echo -n "${IQ_PASS}${IQ_USER}" | md5sum | awk '{print $1}')

echo "2. Appending credentials to ${POD_NAME}..."
kubectl exec -n $NAMESPACE $POD_NAME -- sh -c "echo '${IQ_USER}:md5${HASH}' >> /conf/pool_passwd"

echo "3. Reloading PgPool configuration smoothly..."
# Automatically finds the main parent PgPool process and sends the reload signal
kubectl exec -n $NAMESPACE $POD_NAME -- sh -c 'kill -HUP $(ps -o pid,args | grep "[b]in/pgpool" | awk "{print \$1}")'

echo "Done! Current configuration:"
kubectl exec -n $NAMESPACE $POD_NAME -- tail -n 1 /conf/pool_passwd

    2. Make the script executable:

      chmod +x add-iq-user-to-pgpool.sh

    3. Run the script:

      ./add-iq-user-to-pgpool.sh

      Expected output:

      1. Generating MD5 hash...
2. Appending credentials to dx-deployment-persistence-connection-pool-666c7d8476-qn2s9...
3. Reloading PgPool configuration smoothly...
Done! Current configuration:

    4. Verify that the IQ user was added to the pgpool configuration:

      POD_NAME=$(kubectl get pods -n <YOUR_NAMESPACE> -l app=dx-deployment-persistence-connection-pool -o jsonpath='{.items[0].metadata.name}')
kubectl exec -n <YOUR_NAMESPACE> $POD_NAME -- cat /conf/pool_passwd

      Verify that the output includes the IQ user entry with the MD5 hash (for example, <DB_USERNAME>:md5<HASH_VALUE>).

  6. Verify that the database, user, environment variables, and secrets are successfully created and configured:

    1. Confirm the database and user roles exist in the persistence node:

      kubectl exec -n <YOUR_NAMESPACE> <DX_RELEASE_NAME>-persistence-node-0 -c persistence-node -- \
  psql -U postgres -c "\l" | grep iq

      kubectl exec -n <YOUR_NAMESPACE> <DX_RELEASE_NAME>-persistence-node-0 -c persistence-node -- \
  psql -U postgres -c "\du" | grep iq

    2. Confirm the database management flags are active and the credentials secret exists:

      kubectl exec -n <YOUR_NAMESPACE> deployment/<DX_RELEASE_NAME>-runtime-controller -- env | grep -E "IQ_|NEW_DB"
kubectl get secret custom-credentials-iq-db -n <YOUR_NAMESPACE>

  7. Update your custom-iq-values.yaml file with the RTC-managed database configuration:

    Important

    The dbName must be iqdb. This is the fixed name that the RTC creates. Do not use a custom name.

    configuration:
  database:
    enabled: true
    dbHost: "<DX_RELEASE_NAME>-persistence-node-0.<DX_RELEASE_NAME>-persistence-headless-svc.<DX_NAMESPACE>.svc.cluster.local"
    dbPort: 5432
    dbName: "iqdb"
    dbCustomSecret: "custom-credentials-iq-db"

    <DX_NAMESPACE>: The DX deployment namespace.

  8. Upgrade the IQ deployment with your updated custom-iq-values.yaml file:

    helm upgrade dx-iq \
  https://<YOUR_REPOSITORY_FQDN_AND_PATH>/<IQ_HELM_CHART_VERSION>.tgz \
  --namespace <YOUR_NAMESPACE> \
  -f custom-iq-values.yaml

    <IQ_HELM_CHART_VERSION>: The IQ Helm chart version.

Next steps

After configuring your database:

  1. Verify that the IQ pod can connect to the database successfully.
  2. Configure IQ Integrator authentication for LiteLLM access.
  3. Run regular backups to ensure data recovery if a failure occurs.
Related information