Cloud Data Ingestion for Amazon Redshift
This page covers everything you need to sync data from Amazon Redshift to Braze using Cloud Data Ingestion (CDI): the resources to create in Redshift, how to connect the source and create a sync in Braze, the source table for each data type, and Redshift-specific troubleshooting.
Setup overview
- In your Redshift instance, set up the tables or views you want to sync to Braze.
- Choose one of the supported authentication methods for Braze, and grant the Braze database user access to your tables.
- Make sure Braze access is allowed to the Redshift tables you want to sync. Braze connects to Redshift over the internet.
- Create a new source and sync in the Braze dashboard.
- Validate the integration and start the sync.

Rows processed per sync depend on your warehouse performance, network latency, and how much new data matches the sync query. Use the integration Sync history in the dashboard to see duration and row counts for recent runs.
Step 1: Set up your source table
The steps in this section create a table with a PAYLOAD column. If you plan to shape your data on the Data definition step instead, you can use an existing table or view. Skip the table creation step, and grant Braze read access to the tables or views you want to sync. For a comparison of options, see Choose a data definition option.
You can name the database, schema, and table as you’d like, but the column names should match the definitions in the following tabs. You may also use a view or a materialized view instead of a table.
Optionally, set up a new database and schema to hold your source table:
CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;

If you use a PAYLOAD column, your source table or view can include columns that aren’t listed in the following tabs (for example, auditing or hashing). Braze reads only the columns described in these tabs; other columns are not used during Cloud Data Ingestion syncs.
Select the tab for the data type you want to sync.
User attributes, custom events, and purchase events all use the same source table shape. Only the contents of PAYLOAD differ.
CREATE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.USERS_ATTRIBUTES_SYNC (
updated_at timestamptz default sysdate,
--at least one of external_id, alias_name and alias_label, or braze_id is required
external_id varchar,
--if using user alias, both alias_name and alias_label are required
alias_label varchar,
alias_name varchar,
--braze_id can only be used to update existing users created through the Braze SDK
braze_id varchar,
--If you include both email and phone, email is used as the primary identifier
email varchar,
phone varchar,
payload varchar(max)
)
UPDATED_AT- The time this row was updated in or added to the table. Braze syncs rows whereUPDATED_ATis later than the last synced value. Rows at the exact boundary timestamp may be re-synced if new rows share that same timestamp.- User identifier columns - Your table may contain one or more user identifier columns. Each row should only contain one identifier (either
external_id, the combination ofalias_nameandalias_label,braze_id,emailorphone). A source table may have columns for one, two, three, four, or all five identifier types.EXTERNAL_ID- This identifies the user you want to update. This should match theexternal_idvalue used in Braze.ALIAS_NAMEandALIAS_LABEL- These two columns create a user alias object.alias_nameshould be a unique identifier, andalias_labelspecifies the type of alias. Users may have multiple aliases with different labels but only onealias_nameperalias_label.BRAZE_ID- The Braze user identifier. This is generated by the Braze SDK, and new users cannot be created using a Braze ID through Cloud Data Ingestion. To create new users, specify an external user ID or user alias.EMAIL- The user’s email address. If multiple profiles with the same email address exist, the most recently updated profile is prioritized for updates. If you include both email and phone, email is used as the primary identifier.PHONE- The user’s phone number. If multiple profiles with the same phone number exist, the most recently updated profile is prioritized for updates.
PAYLOAD- This is a JSON string of the fields you want to sync to the user in Braze.
For attribute syncs, PAYLOAD follows the user attributes object format. You can include nested custom attributes, arrays of objects, and subscription group statuses. For payload examples, see Table setup.
Custom events use the same source table as user attributes. Create the table shown in the User attributes tab, then populate PAYLOAD with an events object.
To sync events, an event name is required. Format the time field as an ISO 8601 string or in yyyy-MM-dd'T'HH:mm:ss:SSSZ format. If the time field is not present, Braze uses the UPDATED_AT column value as the event time. Other fields, including app_id and properties, are optional.
You can sync one event per row.
{
"app_id" : "your-app-id",
"name" : "rented_movie",
"time" : "2013-07-16T19:20:45+01:00",
"properties": {
"movie": "The Sad Egg",
"director": "Alex Smith"
}
}
Purchase events use the same source table as user attributes. Create the table shown in the User attributes tab, then populate PAYLOAD with a purchases object.
To sync purchase events, product_id, currency, and price are required. Format the optional time field as an ISO 8601 string or in yyyy-MM-dd'T'HH:mm:ss:SSSZ format. If the time field is not present, Braze uses the UPDATED_AT column value as the event time. Other fields, including app_id, quantity, and properties, are optional.
You can sync one purchase event per row.
{
"app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
"product_id" : "Completed Order",
"currency" : "USD",
"price" : 219.98,
"time" : "2013-07-16T19:20:30+01:00",
"properties" : {
"products" : [ { "name": "Monitor", "category": "Gaming", "product_amount": 19.99 },
{ "name": "Gaming Keyboard", "category": "Gaming ", "product_amount": 199.99 }
]
}
}
Before you create a catalog sync, create the target catalog in Braze. For the full catalog workflow, see Sync and delete catalog data.
CREATE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC (
updated_at timestamptz default sysdate not null,
--ID of the catalog item to be created or updated
id varchar not null,
--Catalog fields and values that should be added or updated
payload varchar(max),
--The catalog item associated with this ID should be deleted
deleted boolean
)
Grant the Braze user access to this table alongside your other source tables:
GRANT SELECT ON TABLE CATALOGS_SYNC TO braze_user;
The name of the integration must exactly match the name of the catalog you created in Braze.
Braze recommends creating a view from your catalog data so the source table fully refreshes each time a sync runs. For example, if you have a table of product data (product_catalog_1) with product_id and three additional attributes, you could sync the following:
CREATE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC AS
SELECT
CURRENT_TIMESTAMP as UPDATED_AT,
Product_id as id,
JSON_SERIALIZE(
OBJECT (
'attribute_1',
attribute_1,
'attribute_2',
attribute_2,
'attribute_3',
attribute_3)
) as PAYLOAD FROM "product_catalog_1";
Before you create a data object sync, create the data object type and its fields in Braze. For the full workflow, see Sync data objects.
CREATE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.ACCOUNTS_SYNC (
updated_at timestamptz default sysdate not null,
object_id varchar not null,
payload varchar(max) not null,
--the data object record associated with this object_id should be deleted
deleted boolean
)
| Field name | Type | Mode |
|---|---|---|
UPDATED_AT |
timestamptz | REQUIRED |
OBJECT_ID |
varchar | REQUIRED |
PAYLOAD |
varchar(max) | REQUIRED |
DELETED |
boolean | NULLABLE |
UPDATED_AT- The time this row was updated in or added to the table. Braze syncs rows whereUPDATED_ATis later than the last synced value. Rows at the exact boundary timestamp may be re-synced if new rows share that same timestamp.OBJECT_ID- The identifier of the data object record. This must match theobject_idvalue used in Braze for this data object type.PAYLOAD- A JSON string of the fields and values to sync. Each key must match a field defined on the data object type in Braze.DELETED- Whentrue, Braze deletes the record instead of updating it. Leave this null orfalsefor rows you want to create or update.
Field names inside PAYLOAD are case-sensitive. A key named NAME does not match a field named name. If the casing doesn’t match, validation reports the key as an undefined field and reports the field it was meant to populate as missing. Name your keys exactly as the fields appear in Data Settings > Data Objects.
Braze does not create or change data object types during a sync. Define the type and all of its fields in Braze before you create the sync. To add a field later, add it to the type first, then update your source table or query.
For example, a PAYLOAD value for an account with a name and a team_id field looks like this:
{"name": "Acme Corp", "team_id": 42}
Grant the Braze user access to this table:
GRANT SELECT ON TABLE ACCOUNTS_SYNC TO braze_user;
On the Data definition step, select the Data Objects data type, then choose your Data object type. Data object syncs support Table and SQL.
Use this sync to connect users to data object records, such as linking users to the accounts they belong to. Create the relationship in Braze before you sync it.
CREATE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.ACCOUNT_USERS_SYNC (
updated_at timestamptz default sysdate not null,
object_id varchar not null,
--at least one of external_id, alias_name and alias_label, email, or phone is required
external_id varchar,
--if using user alias, both alias_name and alias_label are required
alias_name varchar,
alias_label varchar,
email varchar,
phone varchar,
payload varchar(max),
deleted boolean
)
| Field name | Type | Mode |
|---|---|---|
UPDATED_AT |
timestamptz | REQUIRED |
OBJECT_ID |
varchar | REQUIRED |
EXTERNAL_ID |
varchar | NULLABLE |
ALIAS_NAME |
varchar | NULLABLE |
ALIAS_LABEL |
varchar | NULLABLE |
EMAIL |
varchar | NULLABLE |
PHONE |
varchar | NULLABLE |
PAYLOAD |
varchar(max) | NULLABLE |
DELETED |
boolean | NULLABLE |
Each row needs OBJECT_ID plus at least one user identifier: EXTERNAL_ID, the combination of ALIAS_NAME and ALIAS_LABEL, EMAIL, or PHONE. Use PAYLOAD for any fields defined on the relationship itself.

BRAZE_ID is not supported for user relationship syncs, unlike user attribute syncs. Use one of the identifiers listed previously.
UPDATED_AT- The time this row was updated in or added to the table. Braze syncs rows whereUPDATED_ATis later than the last synced value. Rows at the exact boundary timestamp may be re-synced if new rows share that same timestamp.OBJECT_ID- The identifier of the data object record. This must match theobject_idvalue used in Braze for this data object type.PAYLOAD- A JSON string of the fields and values to sync. Each key must match a field defined on the data object type in Braze.DELETED- Whentrue, Braze deletes the record instead of updating it. Leave this null orfalsefor rows you want to create or update.
Field names inside PAYLOAD are case-sensitive. A key named NAME does not match a field named name. If the casing doesn’t match, validation reports the key as an undefined field and reports the field it was meant to populate as missing. Name your keys exactly as the fields appear in Data Settings > Data Objects.
Braze does not create or change data object types during a sync. Define the type and all of its fields in Braze before you create the sync. To add a field later, add it to the type first, then update your source table or query.
On the Data definition step, select the Data Object User Relationships data type, then choose a Relationship name, such as User (Account-User).
Use this sync to connect data object records to each other, such as linking accounts to their parent accounts. Create the relationship in Braze before you sync it.
CREATE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.ACCOUNT_SUBACCOUNTS_SYNC (
updated_at timestamptz default sysdate not null,
object_id varchar not null,
related_object_id varchar not null,
payload varchar(max),
deleted boolean
)
| Field name | Type | Mode |
|---|---|---|
UPDATED_AT |
timestamptz | REQUIRED |
OBJECT_ID |
varchar | REQUIRED |
RELATED_OBJECT_ID |
varchar | REQUIRED |
PAYLOAD |
varchar(max) | NULLABLE |
DELETED |
boolean | NULLABLE |
OBJECT_ID is the record the relationship starts from, and RELATED_OBJECT_ID is the record it points to. Both are required in every row. Use PAYLOAD for any fields defined on the relationship itself.
UPDATED_AT- The time this row was updated in or added to the table. Braze syncs rows whereUPDATED_ATis later than the last synced value. Rows at the exact boundary timestamp may be re-synced if new rows share that same timestamp.OBJECT_ID- The identifier of the data object record. This must match theobject_idvalue used in Braze for this data object type.PAYLOAD- A JSON string of the fields and values to sync. Each key must match a field defined on the data object type in Braze.DELETED- Whentrue, Braze deletes the record instead of updating it. Leave this null orfalsefor rows you want to create or update.
Field names inside PAYLOAD are case-sensitive. A key named NAME does not match a field named name. If the casing doesn’t match, validation reports the key as an undefined field and reports the field it was meant to populate as missing. Name your keys exactly as the fields appear in Data Settings > Data Objects.
Braze does not create or change data object types during a sync. Define the type and all of its fields in Braze before you create the sync. To add a field later, add it to the type first, then update your source table or query.
On the Data definition step, select the Data Object Relationships data type, then choose a Relationship name, such as Subaccount (Account-Account).
Canvas triggers power zero-copy personalization. For the destination Canvas setup and considerations, see Zero-copy personalization.
CREATE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC (
updated_at timestamptz default sysdate not null,
--at least one of external_id or alias_name and alias_label is required
external_id varchar not null,
--if using user alias, both alias_name and alias_label are required
alias_label varchar,
alias_name varchar,
properties varchar(max)
);
Canvas trigger syncs differ from other user data syncs in three ways:
- Only external ID or user alias identifiers are supported. Email and phone numbers are not supported identifiers.
- Only existing Braze users can be synced. New users cannot be created.
PROPERTIESreplaces thePAYLOADcolumn. This is a JSON string of the fields you want to use as Canvas entry properties for personalization.
Your Canvas triggers table needs the following columns:
UPDATED_AT- The time this row was updated or added to the table. Braze syncs rows whereUPDATED_ATis later than the last synced value. Rows at the exact boundary timestamp may be re-synced if new rows share that same timestamp.- Either
EXTERNAL_IDorALIAS_NAMEandALIAS_LABELas the user identifier column. These identify the users for whom you want to trigger Canvas messaging.EXTERNAL_ID- Identifies the user to enter into the Canvas. This should match theexternal_idvalue used in Braze.ALIAS_NAMEandALIAS_LABEL- These columns create a user alias object.alias_nameshould be a unique identifier, andalias_labelspecifies the alias type. Users may have multiple aliases with different labels, but only onealias_nameperalias_label.
PROPERTIES- A JSON string of fields to make available as personalization properties in your Canvas. This should contain user-specific information.

Properties are not required for every row or user. However, properties values must be a valid JSON string. Input an empty {} string if there are no properties for the row.
Grant the Braze user access to this table:
GRANT SELECT ON TABLE CANVAS_TRIGGERS_SYNC TO braze_user;
To get started, select the Canvas Triggers data type when creating a new sync.
Source tables for user deletes should include one or more user identifier types and an UPDATED_AT timestamp. Payload columns aren’t supported for user delete data.
UPDATED_AT- The time this row was updated or added to the table. Braze syncs rows whereUPDATED_ATis later than the last synced value. Rows at the exact boundary timestamp may be re-synced if new rows share that same timestamp.- User identifier columns - Each row should only contain one identifier: either
external_id, the combination ofalias_nameandalias_label, orbraze_id. A source table may contain columns for one, two, or all three identifier types.EXTERNAL_ID- This identifies the user you want to update. This should match theexternal_idvalue used in Braze.ALIAS_NAMEandALIAS_LABEL- These two columns create a user alias object.alias_nameshould be a unique identifier, andalias_labelspecifies the type of alias. Users may have multiple aliases with different labels but only onealias_nameperalias_label.BRAZE_ID- The Braze user identifier. This is generated by the Braze SDK and new users cannot be created using a Braze ID through Cloud Data Ingestion. To create new users, specify an external user ID or user alias.

Do not include a PAYLOAD column in your table for user removal. To prevent accidental, permanent removal of users, a sync fails if a payload column is provided in the source table. Any other columns are allowed but are ignored by Braze.
CREATE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.USERS_DELETES (
updated_at timestamptz default sysdate,
--at least one of external_id, alias_name and alias_label, or braze_id is required
external_id varchar,
--if using user alias, both alias_name and alias_label are required
alias_label varchar,
alias_name varchar,
--braze_id can only be used to update existing users created through the Braze SDK
braze_id varchar
);
On the Create import sync page, set the Data Type to Delete Users so that the proper actions are taken during the integration run. For more information, see Delete users with Cloud Data Ingestion.

Deleting user profiles cannot be undone. The delete action permanently removes users, which may cause discrepancies in your data. For details, see Effects of deleting user profiles.
Step 2: Set up authentication
Braze connects to Redshift as a database user. Choose one of the following authentication methods to set up that user:
| Method | How Braze authenticates | What you enter in Braze |
|---|---|---|
| IAM role | Braze assumes an AWS Identity and Access Management (IAM) role in your account, using an external ID that Braze generates for your workspace, and then requests temporary database credentials. | Role ARN, Region, Cluster type, and Workgroup name or Cluster identifier |
| Username and password | Braze connects as a Redshift database user with a password. | Username and Password |
IAM role
Braze assumes an AWS Identity and Access Management (IAM) role in your AWS account and requests temporary database credentials. Braze doesn’t store a database password. Braze assumes the role from the same AWS account that it uses for Amazon S3 sources.
Braze generates an external ID for your workspace. Your role uses this ID to confirm that a request to assume the role comes from your Braze workspace.
Your existing username and password credentials continue to work, so you don’t need to migrate them.
Prerequisites
You need permission to create IAM roles and policies in your AWS account. You also need permission to run CREATE USER and GRANT statements in your Redshift database.

Your role’s trust policy must require the exact external ID from the Braze credential form. When you test or save a credential, Braze tries to assume your role with a different external ID. If AWS allows that attempt, the connection test fails. This happens when the role doesn’t require an external ID, or when it accepts a pattern such as braze-cdi-*.
Copy the Braze account ID and external ID
- In the Braze dashboard, go to Data Settings > Cloud Data Ingestion > Sources.
- Select Add data source, and then select Amazon Redshift.
- For the authentication method, select IAM role.
- In the AWS setup step, copy the Braze Account ID and the External ID. Keep the form open, because you return to it in Enter the values in Braze.
Create the IAM role
- In the AWS console, go to IAM > Roles, and then select Create role.
- Select AWS account as the trusted entity type, and then select Another AWS account.
- Paste the Braze Account ID. Select Require external ID, and then paste the External ID.
- Skip the permissions step. Enter a role name, and then select Create role. You add the permissions policy in Add the permissions policy.
- Copy the role’s Amazon Resource Name (ARN). You enter it in Braze in Enter the values in Braze.
The trust policy for the role looks like the following example. Replace BRAZE_ACCOUNT_ID and EXTERNAL_ID with the values from the credential form.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::BRAZE_ACCOUNT_ID:root"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "EXTERNAL_ID"
}
}
}
]
}
Add the permissions policy
Add an inline permissions policy to the role. On the role’s Permissions tab, select Add permissions > Create inline policy, and then paste the JSON for your cluster type from the following tabs.
For Redshift Serverless, the policy must allow redshift-serverless:GetCredentials on your workgroup. In the Resource value, use the workgroup ID, which is different from the workgroup name. To find the ID, open your workgroup in the Redshift console, and copy the ID from the workgroup ARN.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "redshift-serverless:GetCredentials",
"Resource": "arn:aws:redshift-serverless:REGION:AWS_ACCOUNT_ID:workgroup/WORKGROUP_ID"
}
]
}
Replace REGION, AWS_ACCOUNT_ID, and WORKGROUP_ID with the values for your workgroup.
For a provisioned cluster, the policy must allow redshift:GetClusterCredentialsWithIAM on the database that you sync from.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "redshift:GetClusterCredentialsWithIAM",
"Resource": "arn:aws:redshift:REGION:AWS_ACCOUNT_ID:dbname:CLUSTER_IDENTIFIER/DATABASE_NAME"
}
]
}
Replace REGION, AWS_ACCOUNT_ID, CLUSTER_IDENTIFIER, and DATABASE_NAME with the values for your cluster.
Create the database user and grant access
Braze logs in to Redshift as a database user named IAMR:ROLE_NAME, where ROLE_NAME is the name of the IAM role you created. This user is different from braze_user, so permissions you granted to other database users don’t apply to it.
Before you test the connection in Braze, run the following statement in your Redshift database to create the user. The statement is safe to run before Braze connects for the first time:
CREATE USER "IAMR:ROLE_NAME" PASSWORD DISABLE;
Then grant this user access to your source table. Use the same GRANT statements as in Step 3: Grant permissions to the user, and replace braze_user with "IAMR:ROLE_NAME". Keep the double quotation marks, because the user name contains a colon.
If you also use Redshift as a connected source, grant this user the same permissions listed in that section.
Enter the values in Braze
Return to the Braze credential form. In the Braze setup step, enter the following values:
| Braze field | What to enter |
|---|---|
| Cluster type | Serverless (the default) or Provisioned. |
| Role ARN | The ARN of the role you created, in the form arn:aws:iam::123456789012:role/ROLE_NAME. |
| Region | The AWS Region where your Redshift cluster or workgroup runs, such as us-east-1. This can be different from the Region of your Braze instance. |
| Workgroup name or Cluster identifier | For Serverless, the name of your workgroup. For a provisioned cluster, the identifier of your cluster. |
| Host | The endpoint of your cluster or workgroup. For Serverless, Braze fills in this field from your Role ARN, Region, and Workgroup name, and you can edit it. For a provisioned cluster, enter the endpoint. |
| Port | The port of your cluster or workgroup. The default is 5439. Enter a value from 1024 to 65535. |

You can’t change these connection details after you save the credential. To change any of them, create a new credential. You can then move your source to the new credential.
IAM role authentication works with or without an SSH tunnel. For tunnel and IP allowlist setup, follow Step 4: Allow access to Braze IPs, the same as for other methods. After you save the credential, you can rename it. If you use a tunnel, you can also rotate the tunnel key.
How Braze tests the connection
When you test the connection, and each time Braze connects, Braze first tries to assume your role using a test external ID that doesn’t belong to any workspace: braze-cdi-000000000000000000000000. Your role must deny this attempt with an AccessDenied error. If AWS allows it, the connection test fails. For help, see Your IAM role doesn’t require its external ID.
AWS CloudTrail shows these attempts as AssumeRole calls with the session name Braze-CDI-Redshift. The denied attempt is expected and doesn’t give Braze access to your data. Don’t add a condition that rejects only this external ID, because your role would still trust other Braze workspaces.
Remove Braze access
To stop Braze from accessing your data, delete the role, or remove the trust statement for the Braze account from the role’s trust policy. You can also drop the IAMR:ROLE_NAME database user.
Set up with the AWS CLI
Alternatively, use the AWS Command Line Interface (CLI) to create the role and attach the permissions policy. This example uses a Serverless workgroup. For a provisioned cluster, replace the policy document with the policy from the Provisioned tab in Add the permissions policy.
aws iam create-role --role-name braze-cdi \
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {"AWS": "arn:aws:iam::BRAZE_ACCOUNT_ID:root"},
"Action": "sts:AssumeRole",
"Condition": {"StringEquals": {"sts:ExternalId": "EXTERNAL_ID"}}
}]
}'
aws iam put-role-policy --role-name braze-cdi \
--policy-name braze-cdi-redshift \
--policy-document '{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "redshift-serverless:GetCredentials",
"Resource": "arn:aws:redshift-serverless:REGION:AWS_ACCOUNT_ID:workgroup/WORKGROUP_ID"
}]
}'
Replace the following placeholders:
BRAZE_ACCOUNT_IDandEXTERNAL_ID: The values from the credential formREGION,AWS_ACCOUNT_ID, andWORKGROUP_ID: The values for your workgroup
The create-role command returns the role ARN in its output. For details, see create-role in the AWS CLI Command Reference. Copy the ARN, and then continue with Create the database user and grant access.
Username and password
Braze connects to Redshift as a database user with a password. Create a user for Braze:
CREATE USER braze_user PASSWORD '{password}';
Keep the username and password in a safe place until you need to enter them in the Braze dashboard when you create the source.
Step 3: Grant permissions to the user
Grant the database user that Braze connects as access to your source table. The following example uses braze_user. If you use IAM role authentication, replace braze_user with "IAMR:ROLE_NAME". For details, see Create the database user and grant access.
GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION to braze_user;
GRANT SELECT ON TABLE USERS_ATTRIBUTES_SYNC TO braze_user;
These are the minimum required permissions for this user. If creating multiple CDI integrations, you may want to grant permissions to a schema or manage permissions using a group.
Step 4: Allow access to Braze IPs
If you have a firewall or other network policies, you must give Braze network access to your Redshift instance. An example of the Redshift URL endpoint is “example-cluster.ap-northeast-2.redshift.amazonaws.com”.
Some important things to know:
- You may also need to change your security groups to allow Braze to access your data in Redshift.
- Make sure to explicitly allow inbound traffic on the IPs in the table and on the port used to query your Redshift cluster (default is 5439). You should explicitly allow Redshift TCP connectivity on this port even if the inbound rules are set to “allow all”.
- The endpoint for the Redshift cluster must be publicly accessible for Braze to connect to your cluster.
- If you don’t want your Redshift cluster to be publicly accessible, you can set up a VPC and EC2 instance to use an SSH tunnel to access the Redshift data. For more information, see the AWS Knowledge Center post.
Allow access from the following IPs corresponding to your Braze dashboard’s region.
For instances US-01, US-02, US-03, US-04, US-05, US-06, US-07, these are the relevant IP addresses:
23.21.118.19134.206.23.17350.16.249.952.4.160.21454.87.8.3454.156.35.25152.54.89.23818.205.178.15
For instance US-08, these are the relevant IP addresses:
52.151.246.5152.170.163.18240.76.166.15740.76.166.17040.76.166.16740.76.166.16140.76.166.15640.76.166.16640.76.166.16040.88.51.7452.154.67.1740.76.166.8040.76.166.8440.76.166.8540.76.166.8140.76.166.7140.76.166.14440.76.166.145
For instance US-10, these are the relevant IP addresses:
100.25.232.16435.168.86.17952.7.44.1173.92.153.1835.172.3.12950.19.162.19
For instances EU-01 and EU-02, these are the relevant IP addresses:
52.58.142.24252.29.193.12135.158.29.22818.157.135.973.123.166.463.64.27.363.65.88.253.68.144.1883.70.107.88
For instance AU-01, these are the relevant IP addresses:
13.210.1.14513.211.70.15913.238.45.5452.65.73.16754.153.242.23954.206.45.213
For instance ID-01, these are the relevant IP addresses:
108.136.157.246108.137.30.20716.78.128.7116.78.14.13416.78.162.20843.218.73.35
For instance JP-01, these are the relevant IP addresses:
13.159.155.21254.199.221.24113.192.23.1654.250.120.13918.181.114.2323.114.38.100
For instance KR-01, these are the relevant IP addresses:
43.200.215.452.79.67.17552.79.113.603.34.212.9254.116.134.2313.37.197.225
Step 5: Create a new source in the Braze dashboard
In the Braze dashboard, go to Data Settings > Cloud Data Ingestion > Sources, select Add data source, and then select Amazon Redshift.
Step 5.1: Add Redshift connection information and source table
Choose a name for your source and input your Redshift credentials and configuration. Select the authentication method you set up in Step 2, and enter its credentials:
- IAM role: Role ARN, Region, Cluster type, and Workgroup name or Cluster identifier
- Username and password: Username and Password
If you’re using a private network tunnel, toggle the slider and input the tunnel information. Then, proceed to the next step.

In the Braze dashboard, the Database name field only accepts letters (A–Z, a–z), numbers (0–9), and underscores (_), even though Amazon Redshift supports additional characters in database identifiers.
Step 5.2: Test connection and connect to source
Next, select Test connection. Once successful, finalize remaining settings and click Connect to Source. If the connection fails, an error message appears to help troubleshoot the issue.
Step 6: Create a new sync in the Braze dashboard
Go to Data Settings > Cloud Data Ingestion > Syncs, and select Create data sync.
Configure sync details and define your data
Enter a name for your sync. Then, select an active source and a sync data type. Next, select a sync mode and define your data. Then select Preview and validate.
After validation succeeds, a preview of the data appears. Select Next: Notifications to continue. If validation fails, an error message appears to help troubleshoot the issue.

You must successfully validate a sync before progressing to next steps. If you need to close out of the sync creation page, select Save as draft to keep your work in progress.
Add notification preferences
Input contact email(s) for sync error notifications. Braze uses this contact information to send notifications about integration errors, such as unexpected loss of table access.
Contact emails only receive notifications of global or sync-level errors such as missing tables, permissions, and others. They do not receive row-level issues. Global errors indicate critical problems with the connection that prevent syncs from running.
Such problems can include the following:
- Connectivity issues
- Lack of resources
- Permissions issues
- Catalog tier is out of space (catalog syncs only)
Set the schedule
Lastly, configure your sync as non-recurring or recurring.
Non-recurring syncs run only when you select Sync Now in the dashboard or call the Trigger a sync endpoint.
Recurring syncs can run as often as every 5 minutes or as rarely as once per month. By default, the shortest interval you can set in the dashboard is 15 minutes, which helps manage your warehouse compute costs and request volume. To sync as often as every 5 minutes, contact Braze Support or your customer success manager. Braze schedules recurring syncs in UTC.

You must successfully validate an integration before it can move from Draft to Active state. If you close the creation page, your integration is saved, and you can revisit the details page to make changes and validate.
Run the sync
When activated, your sync runs on the schedule configured during setup. If you want to run the sync outside its schedule or to fetch the most recent data, select Sync Now. This run does not impact regularly scheduled future syncs. To start a sync automatically when your data updates, call the Trigger a sync endpoint from your pipeline.
Set up additional integrations or users (optional)
You can set up multiple integrations with Braze. When creating additional syncs, you can reuse existing credentials if connecting to the same Redshift account.
If you reuse the same user across integrations, you cannot delete the user in the Braze dashboard until it’s removed from all active syncs.
Use Redshift as a connected source
A connected source is a zero-copy alternative to syncing data into Braze. Braze queries your Redshift instance directly to build CDI segments, without copying the underlying data. For concepts, limitations, and cost implications, see Connected sources.
Step 1: Create the user and grant permissions
Choose one of the methods in Step 2: Set up authentication for Braze. Then, grant the Braze database user the following permissions. The example uses braze_user. If you use IAM role authentication, replace braze_user with "IAMR:ROLE_NAME".
GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION to braze_user;
GRANT CREATE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION to braze_user;
GRANT SELECT ON TABLE USERS_ATTRIBUTES_SYNC TO braze_user;
Create a user for your connected source to use. This user is used to generate the list of tables available in your CDI Segment Extensions, and to query source tables to create new segments. After the connected source is created, Braze discovers the names and description of all tables available to the user in the source schema. If creating multiple CDI integrations, you may want to grant permissions to a schema or manage permissions using a group.
You may choose to grant access to all tables in a schema, or grant privileges only to specific tables. Whichever tables the Braze role has access to are available to query in the CDI Segment Extension. Be sure to grant access to any new tables to the user when they’re created, or set default permissions for the user.
The create table permission is required so Braze can create a table with your CDI Segment Extension query results before updating the segment in Braze. Braze creates a temporary table per segment, which only persists while Braze updates the segment.
Network access setup matches Step 4.
Step 2: Create the connected source in Braze
Go to Data Settings > Cloud Data Ingestion > Connected Sources, select Add data source, and then select Amazon Redshift.
In Setup source, enter the following:
-
Credentials: Redshift Host URL, Port, and the fields for your authentication method. For IAM role, enter Role ARN, Region, Cluster type, and Workgroup name or Cluster identifier. For Username and password, enter Username and Password.
-
Configuration: Database and Schema
If needed, enable Connect with SSH Tunnel and enter Tunnel Host, Tunnel Port, and Tunnel Username.
Choose a name for the connected source. This name is used in the list of available sources when you create a new CDI Segment Extension.
Configure a maximum runtime for this source. Braze automatically aborts any queries that exceed the maximum runtime. The maximum runtime allowed is 60 minutes; a lower runtime reduces costs incurred on your Redshift account. This setting applies to queries run through this source, including syncs and CDI Segment Extensions that use it.
Step 3: Finalize the Redshift configuration
If your credentials have Connect with SSH Tunnel selected, take note of the RSA public key in the Test connection step and add it to the SSH tunnel user.
After you add the key to the user, select Test Connection in Braze, and then select Done. Your connected source is now created and ready to use in CDI Segment Extensions.
You may set up multiple connected sources with Braze, but each source should be configured to connect a different schema. When creating additional sources, you may reuse existing credentials if connecting to the same Redshift account.
Format a payload from existing columns
If you prefer to store each attribute in its own column internally, you need to convert those columns to a JSON string to populate the sync with Braze. Use this query in Redshift to format source columns into CDI fields.
CREATE TABLE "EXAMPLE_USER_DATA"
(attribute_1 string,
attribute_2 string,
attribute_3 number,
my_user_id string);
SELECT
CURRENT_TIMESTAMP as UPDATED_AT,
my_user_id as EXTERNAL_ID,
JSON_SERIALIZE(
OBJECT (
'attribute_1',
attribute_1,
'attribute_2',
attribute_2,
'yet_another_attribute',
attribute_3)
) as PAYLOAD FROM "EXAMPLE_USER_DATA";
For more optimization guidance, see Cloud Data Ingestion best practices.
Troubleshooting
Test Connection runs slow
Test Connection is running on your data warehouse, so increasing warehouse capacity may improve its speed. Using a serverless SQL instance minimizes warmup time and improves query throughput, but may result in slightly higher integration costs.
Permission denied for relation {table_name}
If you receive this error:
- Grant the
usagepermission on the schema for that user. - Grant the
selectpermission on the table for that user.
Your IAM role doesn’t require its external ID
If you use IAM role authentication, the connection test can fail with the following error:
The IAM role on this credential does not require its external ID. Braze assumed the role with an external ID that belongs to no Braze workspace and AWS allowed it, so another Braze customer who learns the role ARN could read this data. In the role’s trust policy, add a StringEquals condition on sts:ExternalId with the external ID shown in the credential form to every statement that allows Braze’s AWS principal to assume the role. A pattern that also matches other Braze workspaces, such as braze-cdi-*, does not require it. Then test the connection again.
This error means AWS allowed the test external ID described in How Braze tests the connection. To fix this, update your role’s trust policy:
- In the AWS console, open the role and select the Trust relationships tab.
- For every statement that allows the Braze account to assume the role, add a
StringEqualscondition onsts:ExternalIdthat uses the exact external ID from the credential form. Remove any pattern condition, such asbraze-cdi-*. - In Braze, test the connection again.
Braze couldn’t confirm that your role requires its external ID
If you use IAM role authentication, the connection test can fail with the following error:
Braze could not confirm that the IAM role on this credential requires its external ID. The check needs AWS to explicitly refuse an attempt to assume the role with a different external ID, and this attempt failed for another reason instead. Please try again; if it keeps happening, contact support.
Braze couldn’t complete the check, so this error doesn’t mean your role is too broad. Test the connection again. If the error continues, contact Braze Support.
Unable to assume IAM role
If you use IAM role authentication and the connection test fails with an error that starts with “Unable to assume IAM role”, check the following:
- The role’s trust policy lists the Braze Account ID from the credential form as the trusted principal.
- The role’s trust policy requires the exact external ID from the credential form.
- The Role ARN you entered in Braze matches the ARN of the role you created.
- If your Braze instance is in an AWS Region that isn’t enabled by default, such as Jakarta (ID-01), your AWS account has that Region enabled.
AWS returns the same AccessDenied error for all of these causes, so check each one.
Unable to get Redshift database credentials
If you use IAM role authentication and the connection test fails with an error that starts with “Unable to get Redshift database credentials as IAM role”, check the following:
- The role’s permissions policy allows
redshift-serverless:GetCredentialsfor Serverless, orredshift:GetClusterCredentialsWithIAMfor a provisioned cluster. - For Serverless, the policy
Resourcevalue uses the workgroup ID, which is different from the workgroup name. - For a provisioned cluster, the policy
Resourcevalue is thedbnameARN for your cluster and database, in the formarn:aws:redshift:REGION:AWS_ACCOUNT_ID:dbname:CLUSTER_IDENTIFIER/DATABASE_NAME. - The Region, Workgroup name, or Cluster identifier you entered in Braze matches your cluster or workgroup.
Permission denied after a successful connection test
If the connection test succeeds but a sync or validation returns a permission denied error, you probably granted access to a different user, such as braze_user. With IAM role authentication, Braze logs in as "IAMR:ROLE_NAME". Grant the schema and table permissions to that user. For details, see Create the database user and grant access.
Create Connection Error
If you receive this error, verify the Redshift endpoint and port are correct.
Create SSH Tunnel Error
If you receive this error:
- Verify the public key on your Braze dashboard is on the EC2 host used for SSH tunneling.
- Verify your username is correct.
- Verify the SSH tunnel is correct.
Invalid snapshot identifier
If Braze returns an Invalid snapshot identifier error during Test connection or sync setup, Redshift can’t resolve the snapshot reference used when your source object is queried.
In Redshift, a snapshot is a point-in-time backup of a cluster. Each snapshot has a unique identifier used by Redshift to reference that backup state. For more information, see Amazon Redshift snapshots and backups.
This error can occur when metadata changes while Braze validates the source object, such as during snapshot copy, restore, or replication-related operations. For more information, see copying snapshots to another AWS Region and restoring a cluster from a snapshot.
To troubleshoot:
- Verify source settings in Braze, including cluster endpoint, database, schema, and object name.
- Run the same query directly in Redshift to confirm the table or view is readable and stable.
- Retry after active snapshot, restore, resize, or replication activity finishes.
- If the issue persists, query a materialized view instead of a frequently changing base table.
A materialized view stores precomputed query results that you can refresh on a schedule, which can make reads more stable for CDI syncs. For more information, see materialized views in Amazon Redshift.
Example:
CREATE MATERIALIZED VIEW ingestion.users_attributes_mv AS
SELECT updated_at, external_id, alias_label, alias_name, braze_id, email, phone, payload
FROM ingestion.users_attributes_sync;
REFRESH MATERIALIZED VIEW ingestion.users_attributes_mv;
After you create the materialized view, use the materialized view name as the source object in your Braze CDI sync instead of the base table.
Where to run SQL checks
Run validation checks directly in the Redshift SQL editor, against the same table or view used by your CDI integration. Use Query Editor v2. For more information, see Using Amazon Redshift Query Editor v2.
Related pages
- Table setup for required columns and payload formatting
- Best practices for sync scheduling and data point efficiency
- Sync logs and observability for monitoring sync runs
- FAQ for common questions across all sources