host
Required
Type:
string
Description: Hostname of the PostgreSQL server.
Notes:
ngrok.io host is rejected.port
Required
Type:
string
Description:
Port of the PostgreSQL server, written as a string — "5432", not 5432.
Notes:
database
Required
Type:
string
Description: Name of the database RudderStack loads data into.
Notes:
user
RequiredSecret
Type:
string
Description: Database user with the permissions RudderStack needs to create schemas and load tables.
Notes:
password
RequiredSecret
Type:
string
Description:
Password for user.
{{ .VAR }} reference rather than a literal — see Secrets.
namespace
Type:
string
Description: Schema RudderStack creates its tables in. Defaults to the source name when omitted.
Notes:
pg_ in any capitalization.ssl_mode
Required
Type:
string
Description: How RudderStack secures its connection to the server.
Notes:
disable — no encryption.require — encrypted, without verifying the server.verify-ca — encrypted, and the server’s certificate is checked against server_ca. Needs all three certificate keys below.client_key
RequiredSecret
Type:
string
Description: Contents of the client key PEM file.
Notes:
ssl_mode is verify-ca. Leave it unset otherwise.client_cert
RequiredSecret
Type:
string
Description: Contents of the client certificate PEM file.
Notes:
ssl_mode is verify-ca. Leave it unset otherwise.server_ca
Required
Type:
string
Description: Contents of the server CA PEM file.
Notes:
ssl_mode is verify-ca. Leave it unset otherwise.use_ssh
Type:
boolean
Default value:
false
Description: Connect to PostgreSQL through an SSH tunnel via a bastion host.
ssh
Required
Type:
object
Description: Bastion host connection details.
Notes:
use_ssh is true, with all four fields. Leave it unset otherwise.host — IP address or hostname of the bastion host. At most 100 characters.port — SSH port of the bastion host, as a string. At most 100 characters.user — user RudderStack logs in to the bastion host as. At most 100 characters. Secret — see Secrets.public_key — the public key RudderStack generates for this destination. At most 1000 characters.use_ssh: true
ssh:
host: 203.0.113.10
port: "22"
user: "{{ .PG_SSH_USER }}"
public_key: "ssh-rsa AAAA..."RudderStack holds the private key; add public_key to the bastion host’s authorized_keys. The key comes from RudderStack, so the practical route is to enable SSH on the destination in the dashboard, then import it to pick up the value.
use_rudder_storage
Required
Type:
boolean
Description: Stage files in RudderStack-managed object storage instead of your own.
Notes:
false and configure a provider.false. Rudder CLI requires it explicitly.bucket_provider
Required
Type:
string
Description: Object storage provider for staging files.
Notes:
use_rudder_storage is false. Leave it unset otherwise.S3, GCS, AZURE_BLOB, or MINIO.bucket_name
Required
Type:
string
Description:
Name of the staging bucket. The bucket must already exist. Azure uses azure.container_name instead.
Notes:
use_rudder_storage is false and bucket_provider isn’t AZURE_BLOB. Leave it unset otherwise.S3: lowercase letters, digits, dots, and hyphens; not starting with xn--, no consecutive dots, not an IP address.GCS: lowercase letters, digits, dots, hyphens, and underscores; not starting with goog, not containing google, no consecutive dots, not an IP address.MINIO: lowercase letters, digits, dots, and hyphens; not an IP address.access_key_id
RequiredSecret
Type:
string
Description: Access key ID for S3 or MinIO. It sits at the top level because both providers use it.
Notes:
bucket_provider is MINIO, or S3 with s3.role_based_auth not true. Leave it unset otherwise.cleanup_object_storage_files
Type:
boolean
Default value:
false
Description: Delete staged files after a sync completes successfully.
Notes:
use_rudder_storage is false.s3
Required
Type:
object
Description: Amazon S3 settings.
Notes:
use_rudder_storage is false and bucket_provider is S3. Leave it unset otherwise.role_based_auth — boolean. true to use iam_role_arn; omitted or false to use access_key_id and access_key.iam_role_arn — ARN of the IAM role RudderStack assumes. Required when role_based_auth is true. At most 100 characters.access_key — AWS secret access key matching access_key_id. Required when role_based_auth isn’t true. At most 100 characters. Secret.bucket_provider: S3
bucket_name: acme-postgres-staging
s3:
role_based_auth: true
iam_role_arn: "arn:aws:iam::123456789012:role/RudderStackS3"gcs
Required
Type:
object
Description: Google Cloud Storage settings.
Notes:
use_rudder_storage is false and bucket_provider is GCS. Leave it unset otherwise.credentials — contents of the JSON key file for a service account that can create objects in the bucket. Required. Secret.bucket_provider: GCS
bucket_name: acme-postgres-staging
gcs:
credentials: '{{ .PG_GCS_CREDENTIALS }}'azure
Required
Type:
object
Description: Azure Blob Storage settings.
Notes:
use_rudder_storage is false and bucket_provider is AZURE_BLOB. Leave it unset otherwise.account_name — storage account name. Required. At most 100 characters.container_name — staging container, which must already exist. Required. 3 to 63 characters of lowercase letters, digits, and single hyphens.use_sas_tokens — boolean. true to authenticate with sas_token; omitted or false to use account_key.account_key — storage account key. Required when use_sas_tokens isn’t true. At most 100 characters. Secret.sas_token — shared access signature token. Required when use_sas_tokens is true. Secret.bucket_provider: AZURE_BLOB
azure:
account_name: acmestorage
container_name: rudder-staging
use_sas_tokens: true
sas_token: "{{ .PG_AZURE_SAS_TOKEN }}"minio
Required
Type:
object
Description:
MinIO settings. The access key ID goes in the top-level access_key_id.
Notes:
use_rudder_storage is false and bucket_provider is MINIO. Leave it unset otherwise.end_point — MinIO server endpoint. Required. 1 to 100 characters; an ngrok.io endpoint is rejected.secret_access_key — MinIO secret access key. Required. At most 100 characters. Secret.use_ssl — boolean. Connect to MinIO over TLS. Required, even when true.bucket_provider: MINIO
bucket_name: rudder-staging
access_key_id: "{{ .MINIO_ACCESS_KEY_ID }}"
minio:
end_point: minio.example.com:9000
secret_access_key: "{{ .MINIO_SECRET_ACCESS_KEY }}"
use_ssl: truesync_frequency
Required
Type:
string
Description: How often RudderStack syncs staged events into PostgreSQL, in minutes. Written as a string, not a number.
Notes:
5, 10, 15, 30, 60, 180, 360, 720, or 1440.180. Rudder CLI requires it explicitly.sync_start_at
Type:
string
Description:
Time of day, in UTC, that anchors the sync schedule. Subsequent syncs are computed from it at sync_frequency intervals. Written as HH:MM.
Notes:
exclude_window
Type:
object
Description: Daily window, in UTC, during which RudderStack doesn’t sync. Omit the block entirely to sync around the clock.
Notes:
start_time and end_time, each HH:MM.prefer_append
Type:
boolean
Default value:
true
Description:
Append incoming events to existing tables. Set it to false to merge instead, which guarantees no duplicates at the cost of noticeably longer syncs. This is what the dashboard calls Warehouse Append.
skip_users_table
Type:
boolean
Default value:
true
Description:
Send identify events only to the identifies table, skipping the users table. The users table holds one row per unique user and is maintained with a merge, which can add significant time to each sync.
skip_tracks_table
Type:
boolean
Default value:
false
Description:
Skip sending events to the tracks table. Per-event tables are unaffected.
json_paths
Type:
string
Description:
Comma-separated dot-notation paths whose values are stored as JSON columns instead of being flattened. Applies to every track event sent to this destination.
Notes:
underscore_divide_numbers
ImmutableInternal
Type:
boolean
Default value:
false
Description:
When false, numeric suffixes in column names are preserved: v3 stays v3 rather than being split into v_3.
allow_users_context_traits
ImmutableInternal
Type:
boolean
Default value:
false
Description:
When false, context.traits.* fields aren’t promoted to top-level traits and are stored only as context_traits_* columns.
connection_mode
Type:
object
Description: Maps each source type you connect to the mode its events reach PostgreSQL in, using the modes in Source types.
Notes:
connection_mode:
web: cloud
cloud: cloudconsent_management
Type:
object
Description:
Consent provider configuration per source type. The entry shape, accepted providers, and the rules on resolution_strategy and consents are shared across all destination types — see Consent management.
| Version | Change |
|---|---|
| v0.29.0 | Breaking: A null config value, written as key: null, key: ~, or key: with no value, fails validate with '<key>' must not be null; set a value or remove the key. Earlier releases accepted it: a top-level null planned an update on every apply, and a null inside a list item failed at the API.What to do: Remove the key to leave it unset, or give it a value. |
| v0.29.0 | Breaking: An empty string, "", on a key that takes one of a fixed set of values fails validate with '<key>' must be one of [...], unless "" is one of the key’s values. Earlier releases accepted it, and the API rejected it at apply.What to do: Remove the key to leave it unset, or set one of the listed values. |
| v0.29.0 | Changed: validate warns when a secret key holds anything but one {{ .VAR }} reference with no default, and when one variable fills two secret keys. It also masks secret values in the lines it prints. |
| v0.29.0 | Changed: rudder-cli import writes each secret reference single-quoted, as '{{ .VAR }}', so a value containing double quotes, like a JSON key file, substitutes as a string. A single quote in a value that fills such a reference is written as ''.What to do: In a spec imported by an earlier release, quote each reference to a JSON value by hand: '{{ .VAR }}'. |
| v0.29.0 | Changed: A multi-line value, like a PEM key, keeps its line breaks when it fills a quoted {{ .VAR }} reference, in either quote style. Earlier releases folded the line breaks into spaces, so the destination stored a broken key unless the value was written with \n in a double-quoted reference. That form still works. |
| v0.29.0 | Changed: validate reports a value of the wrong type once per key, such as 'email' must be a string, instead of one raw decoding error. |