Conectando a Klaviyo e o Redshift

Visão geral

Este guia orienta administradores do Redshift a preparar o Amazon Redshift para o Klaviyo, conceder o acesso mínimo necessário e concluir a conexão para que você possa importar dados de perfil em uma programação. Você vai aprender como:

1. Crie os esquemas KLAVIYO_TMP e KLAVIYO_IMPORT_FROM_DWH
2. Crie um usuário de serviço dedicado para o Klaviyo
3. Conceda permissões de privilégio mínimo
4. (Opcional) Validar permissões do banco de dados
5. Conecte o Redshift ao Klaviyo e crie uma sincronização agendada de perfis

Para ter um contexto sobre como o Data Warehouse Import funciona — incluindo objetos compatíveis e práticas recomendadas para a estrutura das tabelas — consulte Entendendo o Data Warehouse Import no Klaviyo.

Crie os esquemas obrigatórios

Crie 2 esquemas no banco de dados do Redshift que você vai usar para a Klaviyo:

-- Run as a Redshift DB admin or a role with CREATE SCHEMA
CREATE SCHEMA IF NOT EXISTS klaviyo_import_from_dwh;
CREATE SCHEMA IF NOT EXISTS klaviyo_tmp;

• KLAVIYO_IMPORT_FROM_DWH – Coloque aqui suas tabelas ou visualizações finais, prontas para sincronizar. Durante a configuração, a Klaviyo lista os objetos nesse esquema para você escolher, então inclua apenas as tabelas que você planeja importar.
• KLAVIYO_TMP – Usado exclusivamente pela Klaviyo para tabelas temporárias/de preparação durante trabalhos de sincronização. Não modifique os dados aqui — a Klaviyo gerencia e limpa esse esquema automaticamente.

Crie o usuário de serviço do Klaviyo Service

Crie um usuário de banco de dados dedicado para o Klaviyo com uma senha forte que você possa alternar de forma independente.

-- Replace with your own names and a strong password
CREATE USER klaviyo_data_transfer_user WITH PASSWORD 'REPLACE_WITH_STRONG_PASSWORD';

Crie uma função para gerenciar concessões para o usuário do serviço:

CREATE ROLE klaviyo_data_transfer_role;
GRANT ROLE klaviyo_data_transfer_role TO klaviyo_data_transfer_user;

Armazene o nome de usuário e a senha com segurança — você vai usá-los ao conectar o Klaviyo ao Redshift.

Conceda as permissões necessárias (menor privilégio)

Execute estas instruções como administrador do Redshift no banco de dados que você preparou. Essas concessões se aplicam a tabelas e visualizações existentes. Conceda acesso a novas tabelas ou visualizações de origem antes de adicioná-las a uma sincronização.

-- 1) Permissions on the staging schema Klaviyo manages
GRANT USAGE ON SCHEMA klaviyo_tmp TO ROLE klaviyo_data_transfer_role;
GRANT CREATE ON SCHEMA klaviyo_tmp TO ROLE klaviyo_data_transfer_role;

-- 2) Read-only access to existing tables and views in your import schema
GRANT USAGE ON SCHEMA klaviyo_import_from_dwh TO ROLE klaviyo_data_transfer_role;
GRANT SELECT ON ALL TABLES IN SCHEMA klaviyo_import_from_dwh TO ROLE klaviyo_data_transfer_role;
-- Remember to grant access to new tables and views in the future

-- Alternatively, grant SELECT on each specific source table or view:
-- GRANT SELECT ON TABLE klaviyo_import_from_dwh.example_view_name TO ROLE klaviyo_data_transfer_role;

(Opcional) Verifique sua configuração

Conecte-se ao banco de dados que você preparou como usuário do Klaviyo Service e, em seguida, execute estas verificações. Substitua EXAMPLE_TABLE por uma tabela de origem ou visualização que você planeja sincronizar. Essas verificações não substituem a etapa Testar conexão no Klaviyo.

-- 1) Validate create/read access in KLAVIYO_TMP
-- Use a new test table name if klaviyo_permission_check already exists
CREATE TABLE klaviyo_tmp.klaviyo_permission_check (id INT);
INSERT INTO klaviyo_tmp.klaviyo_permission_check VALUES (1);
SELECT COUNT(*) FROM klaviyo_tmp.klaviyo_permission_check;  -- expect 1
DROP TABLE klaviyo_tmp.klaviyo_permission_check;

-- 2) Confirm visibility of source tables and views
SELECT DISTINCT table_name FROM information_schema.columns
WHERE table_schema = 'klaviyo_import_from_dwh'
ORDER BY table_name
LIMIT 25;

-- 3) Confirm SELECT on a source table or view
SELECT * FROM klaviyo_import_from_dwh.EXAMPLE_TABLE LIMIT 1;

Acesso à rede

A Klaviyo precisa conseguir alcançar seu ponto de extremidade do Redshift.

• Ponto de extremidade público do Redshift: adicione os IPs estáticos da Klaviyo à lista de permissões no seu firewall ou grupo de segurança.
• Ponto de extremidade privado (por exemplo, PrivateLink): garanta a conectividade por meio do caminho da sua rede interna e das políticas de segurança.

Se você estiver usando grupos de segurança, permita o acesso de entrada na sua porta do Redshift (padrão 5439) para os intervalos de IP do Klaviyo:

184.72.183.187/32
52.206.71.52/32
3.227.146.32/32
44.198.39.11/32
35.172.58.121/32
3.228.37.244/32
54.88.219.8/32
3.214.211.176/32

Prepare suas tabelas de importação (estrutura e desempenho)

Garanta que todas as tabelas que você planeja importar sigam estas convenções para sincronizações incrementais precisas e eficientes:

• Coluna de carimbo de data/hora: Inclua um carimbo de data/hora de criação ou da última atualização por linha (por exemplo, inserted_at, updated_at, modified_at). Use uma coluna TIMESTAMP ou TIMESTAMPTZ com um valor para cada linha. As colunas Text e DATE não estão disponíveis para detecção de alterações.
• Atualizações monotônicas: o carimbo de data/hora deve aumentar sempre que uma linha for alterada.
• Fuso horário: Use UTC ou inclua informações de fuso horário. Se estiver ausente, a Klaviyo presume UTC.
• Identificadores consistentes: Inclua pelo menos 1 identificador de perfil (email, phone, external_id etc.). Use identificadores consistentes em todas as tabelas de importação para evitar perfis duplicados.
• Formatos de consentimento: ao sincronizar dados de consentimento, siga os mesmos valores/formatos válidos usados em uploads de arquivo ou SFTP.
• Desempenho: Considere uma chave de ordenação na sua coluna de registro de data/hora para leituras incrementais eficientes.
• Visualizações: Você pode importar de tabelas ou visualizações, desde que um SELECT simples funcione para o usuário da Klaviyo.

Conectar o Redshift e criar uma sincronização de perfil

1. Na Klaviyo, vá até Avançado > Gerenciamento de dados > Sincronização.
2. Se você já tiver uma conexão configurada, clique em Criar sincronização. Se esta for sua primeira conexão, continue para a próxima etapa.
3. Selecione Importe dados do seu data warehouse.
4. Escolha Amazon Redshift.
5. Clique em Conectar ao Redshift e insira os seguintes detalhes de conexão:

1. Clique em Próximo para abrir Testar conexão e, em seguida, clique em Testar. A Klaviyo verifica sua conexão, os esquemas obrigatórios e as permissões de staging e, em seguida, lista as tabelas e visualizações acessíveis em klaviyo_import_from_dwh. Pelo menos 1 fonte precisa estar disponível para continuar. Depois que o teste for bem-sucedido e uma fonte estiver disponível, clique em Avançar.
2. Insira um nome de sincronização exclusivo em Name, selecione sua tabela ou visualização em Data source e selecione Perfis em Data object types.
3. Em Cadência, selecione Agendar execução. Escolha o intervalo em A cada e, em seguida, defina Data de início, Horário de início e Fuso horário. Clique em Avançar.
4. Em Map properties, selecione sua coluna de carimbo de data/hora em Change detection > New Row Detection. Mapeie pelo menos 1 identificador de perfil e as Propriedades do perfil que você quer importar. Remova os mapeamentos das colunas que você não quer importar. Você também não pode mapear a coluna de detecção de alterações para uma Propriedade do perfil.
5. Clique em Concluído para salvar a conexão e sincronizar. O Klaviyo leva você de volta para Sincronizando, e a sincronização é executada de acordo com a programação que você selecionou.

Dicas para solucionar problemas

O teste de conexão falha

• Verifique se as regras do firewall ou do grupo de segurança permitem que os IPs da Klaviyo alcancem o ponto de extremidade do Redshift na porta correta.
• Confirme as configurações de SSL e se você está usando o ponto de extremidade correto (cluster vs. workgroup), a região e a porta.

As tabelas não aparecem

• Garanta que as tabelas estejam em klaviyo_import_from_dwh.
• Confirme se o usuário da Klaviyo tem USAGE no esquema e SELECT nas tabelas ou visualizações.

Nenhuma nova linha sincronizando

• Verifique se sua coluna de carimbo de data/hora é atualizada em alterações de linha e usa UTC ou inclui informações de fuso horário.

Erros de permissão no tempo de execução

• Execute novamente o SQL de validação como o usuário do Klaviyo.
• Reaplique concessões ou privilégios padrão, se necessário.

Segurança e manutenção

• Faça a rotação da senha do usuário de serviço regularmente e após mudanças de equipe. Depois de alterar a senha no Redshift, atualize-a na guia Configuração da sua conexão com a Klaviyo e clique em Salvar.
• Limite o usuário do Klaviyo aos 2 esquemas acima e conceda USAGE apenas quando necessário.
• Mantenha um runbook simples documentando suas instruções GRANT exatas e os intervalos de IP que você colocou na allowlist.

Perguntas frequentes

Posso importar de vários bancos de dados do Redshift?
Sim. Crie os 2 esquemas e conceda acesso em cada banco de dados; em seguida, crie uma conexão do Redshift separada no Klaviyo para cada banco de dados. Adicione sincronizações separadas para as tabelas ou visualizações de origem em cada conexão.

Posso usar visualizações materializadas?
Sim. Conceda SELECT na visualização materializada para o usuário da Klaviyo.

Apêndice: exemplo de DDL para uma tabela de importação simples

CREATE TABLE klaviyo_import_from_dwh.profile_base (
  external_id   VARCHAR(128),
  email         VARCHAR(320),
  phone         VARCHAR(32),
  first_name    VARCHAR(128),
  last_name     VARCHAR(128),
  country       VARCHAR(64),
  inserted_at   TIMESTAMP
);

-- ensure monotonically increasing timestamp on inserts/updates
-- (use your ETL/ELT to set inserted_at = GETDATE() at load time)