IAM Authentication

Use AWS RDS or GCP Cloud SQL IAM authentication with mirrord DB branching

mirrord supports IAM authentication for AWS RDS and GCP Cloud SQL. Credentials are read from the target pod's environment, just like connection URLs. For general concepts and the full list of config fields, see the DB Branching overview.

DynamoDB branches also authenticate to the source account with "iam_auth": { "type": "aws_rds" } (the aws_rds type name is reused across AWS engines). For DynamoDB, iam_auth is required when "copy": { "mode": "all" } is set. See the DynamoDB page.

Default environment variables: If you do not specify custom credential sources, mirrord automatically looks for standard environment variables in the target pod (e.g., AWS_REGION, GOOGLE_APPLICATION_CREDENTIALS). You only need additional configuration if your pod uses non-standard variable names.

AWS RDS IAM Authentication

Minimal Configuration

Uses the standard AWS environment variables already present in the target pod.

{
  "feature": {
    "db_branches": [
      {
        "type": "pg",
        "version": "16",
        "connection": { "url": "DATABASE_URL" },
        "iam_auth": { "type": "aws_rds" }
      }
    ]
  }
}

Default AWS environment variables

mirrord reads the following variables from the target pod, not from your local shell.

Field	Default fallback
region	AWS_REGION, AWS_DEFAULT_REGION
access_key_id	AWS_ACCESS_KEY_ID
secret_access_key	AWS_SECRET_ACCESS_KEY
session_token	AWS_SESSION_TOKEN

Custom AWS environment variables

Use this only if your pod uses non-standard variable names.

{
  "iam_auth": {
    "type": "aws_rds",
    "region": { "type": "env", "variable": "MY_CUSTOM_REGION" },
    "access_key_id": { "type": "env", "variable": "MY_ACCESS_KEY" },
    "secret_access_key": { "type": "env", "variable": "MY_SECRET_KEY" }
  }
}

GCP Cloud SQL IAM Authentication

Minimal Configuration

Uses the standard GOOGLE_APPLICATION_CREDENTIALS file path from target pod

{
  "feature": {
    "db_branches": [
      {
        "type": "pg",
        "version": "17",
        "connection": { "url": "DATABASE_URL" },
        "iam_auth": { "type": "gcp_cloud_sql" }
      }
    ]
  }
}

Default GCP environment variables

Field	Default fallback
credentials_path	GOOGLE_APPLICATION_CREDENTIALS
project	GOOGLE_CLOUD_PROJECT, GCP_PROJECT, GCLOUD_PROJECT

Custom GCP credentials

You can override the default behavior in one of the following ways.

Option 1: Inline JSON credentials Load the service account JSON directly from an environment variable.

{
  "iam_auth": {
    "type": "gcp_cloud_sql",
    "credentials_json": { "type": "env", "variable": "GOOGLE_APPLICATION_CREDENTIALS_JSON" }
  }
}

Option 2: Custom credential file path

Read credentials from a file path provided via an environment variable (for example, a mounted Kubernetes Secret).

{
  "iam_auth": {
    "type": "gcp_cloud_sql",
    "credentials_path": { "type": "env", "variable": "MY_GCP_CREDENTIALS_PATH" }
  }
}

Use either credentials_json OR credentials_path, not both.

Required Database Settings

GCP Cloud SQL requires TLS. Make sure your DATABASE_URL includes: sslmode=require