Como importar CSV para o Supabase

Um script pontual é um meio-termo adequado. Defina explicitamente seu formato de entrada, faça um ensaio e guarde evidências suficientes para determinar o que aconteceu. Para uma importação que um engenheiro executará uma única vez, um script revisado costuma bastar.

Para uploads recorrentes de clientes, use a lista de verificação da arquitetura de um importador de CSV. O restante desta página pressupõe que um engenheiro esteja preparando uma importação específica.

Comece com uma cópia da exportação. Preserve o original para que seja possível explicar uma correção. Registre o delimitador, a codificação, a linha de cabeçalho e o significado dos valores em branco. Se um campo for um identificador externo, trate-o como texto mesmo que todos os valores visíveis contenham dígitos.

Para uma tabela de contatos, a origem aprovada pode conter apenas estes dois campos:

email,display_name
first@example.test,First Contact
second@example.test,"Second, Contact"

A vírgula entre aspas faz parte do nome do segundo contato. Separar cada linha pelas vírgulas criaria um terceiro campo. Um campo entre aspas também pode conter uma quebra de linha, portanto contar linhas físicas não é uma forma confiável de contar registros.

Revise cabeçalhos duplicados e mapeamentos antes da importação. Duas colunas de origem chamadas “Email” exigem uma escolha explícita. Colunas extras devem ser excluídas deliberadamente. Não deduza que os campos id, tenant_id ou created_at de um arquivo devam aceitar gravação só porque os nomes coincidem.

Exporte a aba desejada como CSV em UTF-8 e use o mesmo caminho de importação. No Google Sheets, use Arquivo → Fazer download → Valores separados por vírgulas para a aba atual. No Excel, salve uma cópia no formato CSV UTF-8. Uma pasta de trabalho pode conter várias abas; um CSV representa uma única tabela plana. Renomear um arquivo XLSX para CSV não o converte.

Inspecione o texto exportado antes do upload. Confira um identificador com zeros à esquerda, uma data, um número decimal e qualquer célula derivada de fórmula. Se a planilha já transformou 00042 em 42, exportar em UTF-8 não recupera os zeros perdidos. Volte à origem ou obtenha uma correção aprovada.

Esclareça datas como 04/05/2026 com o responsável pelos dados. Não suponha que signifique 5 de abril ou 4 de maio. Registre o fuso horário pretendido para timestamps; uma data de aniversário sem horário não deve sofrer uma conversão de fuso acidental. A sincronização contínua com uma planilha ativa é um requisito diferente desta exportação pontual.

Faça uma lista curta de responsabilidades por campo antes da primeira gravação. Por exemplo: o e-mail e o nome de exibição vêm da origem aprovada; o tenant vem do contexto autorizado da aplicação; um valor de identidade vem do PostgreSQL; um timestamp de auditoria segue a regra escolhida pela aplicação.

Um valor padrão comum não proíbe valores da origem. Uma expressão gerada é diferente. Uma coluna ausente, um NULL explícito e uma string vazia também podem produzir resultados diferentes. O guia de valores padrão e valores gerados demonstra essas diferenças.

Confira o que sua tabela de destino espera com o PG Import Check se você tiver SQL de migração ou DDL. Ele informa as declarações estruturais suportadas localmente no navegador. Não inspeciona registros em um banco ativo, não valida o CSV, não determina as regras efetivas de RLS nem aprova uma importação em produção. Confira por conta própria se a entrada fornecida corresponde ao esquema efetivamente implantado.

Este pequeno ensaio usa uma tabela temporária em um banco PostgreSQL 17 descartável. Ele testa a mecânica do CSV sem tocar em uma tabela da aplicação. Em uma sessão conectada do psql, crie a tabela:

CREATE TEMP TABLE import_contacts_demo (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  email text NOT NULL UNIQUE,
  display_name text,
  created_at timestamptz NOT NULL DEFAULT now()
);

Salve o CSV acima como contacts.csv no diretório de trabalho do cliente e execute o seguinte em uma única linha no psql:

\copy import_contacts_demo (email, display_name) FROM 'contacts.csv' WITH (FORMAT csv, HEADER MATCH, ENCODING 'UTF8')

SELECT id, email, display_name, created_at
FROM import_contacts_demo
ORDER BY id;

O resultado esperado são duas linhas, IDs gerados distintos, a vírgula preservada no segundo nome e timestamps do banco de dados. A lista explícita de colunas deixa a geração do ID e do timestamp a cargo do banco. No PostgreSQL 17, HEADER MATCH verifica nomes e ordem. A opção simples HEADER true ignora o cabeçalho; ela não mapeia valores pelo nome.

O comando de cópia com barra invertida do psql lê um arquivo na máquina cliente e o transmite pela conexão com o banco. No lado do servidor, COPY FROM '/path' lê o sistema de arquivos do servidor do banco de dados. O Supabase não consegue ler um caminho no seu laptop dessa forma.

Para uma conexão real com o Supabase, obtenha o endpoint e a configuração de SSL corretos nas instruções de conexão do projeto. Mantenha senhas fora de comandos salvos, do Git e de capturas de tela. Peça ao responsável pelo banco que escolha o papel de execução e o modo de conexão; este exemplo com tabela temporária não estabelece permissões de produção.

Um arquivo de cliente pode conter um rótulo como “Conta ativa” onde seu enum espera active. Uma representação em staging permite manter o valor original ao lado do valor proposto e do motivo da alteração. O responsável pelo negócio aprova essa conversão; o importador a aplica de forma consistente.

O staging pode ser uma tabela temporária, um banco de dados descartável separado ou uma área persistente e restrita para uma tarefa mais longa. Escolha conforme a sensibilidade dos dados e as necessidades de recuperação. Não deve ser uma tabela desprotegida exposta pela API da aplicação. Teste as restrições e o comportamento de gravação relevantes para produção em um ambiente isolado e registre o que o ensaio não consegue reproduzir.

O comportamento padrão do COPY no PostgreSQL interrompe a execução ao encontrar um erro. Uma transação revertida não deixa suas linhas inseridas confirmadas, mas lotes anteriores confirmados separadamente permanecem. Um script com dez requisições bem-sucedidas e uma décima primeira com falha tem um resultado parcial. Não reinicie o arquivo inteiro com base apenas no último erro.

Inclua restrições e triggers na revisão. Uma chave estrangeira precisa de uma referência no destino, e não apenas de um número com o tipo correto. Um trigger pode rejeitar ou alterar uma linha e pode iniciar outros trabalhos. Não desative verificações de integridade como solução de rotina para um arquivo rejeitado. Consulte o guia de importação com chaves estrangeiras quando os IDs de origem e de destino forem diferentes.

Para arquivos grandes, meça o tempo de execução, o uso de disco, o crescimento do WAL, os bloqueios e a latência da aplicação em um ensaio representativo. Escolha lotes de tamanho limitado ou uma janela de manutenção com base nessas evidências. O limite de tamanho de arquivo do painel não é uma garantia de desempenho para qualquer outro caminho.

Conte os registros de origem interpretados pelo parser, registre as exclusões aprovadas e compare o conjunto aceito resultante com o destino. Se 200 contatos foram aceitos, 200 linhas inseridas são uma evidência útil. Ainda assim, é possível ter os 200 contatos errados ou os contatos certos atribuídos ao tenant errado.

Compare chaves de negócio estáveis, inspecione os campos transformados importantes e teste o caminho normal de leitura da aplicação. Dentro do tenant autorizado, identifique as linhas desta importação usando uma identificação confiável da importação ou um mapa revisado de IDs de origem para destino. Um filtro de tenant sozinho inclui linhas existentes. Se não houver identificação da importação, compare com uma expectativa explícita do estado completo após a importação e declare essa limitação.

O guia de verificação pós-importação oferece exemplos executáveis para chaves ausentes e valores divergentes. Guarde a origem aprovada, o mapeamento e o resultado juntos, conforme uma política de retenção acordada. Esses registros facilitam bastante a resolução de uma tentativa com falha ou de uma correção solicitada pelo cliente.