Importando dados de arquivos CSV usando o comando `COPY`

E aí, galera! Imagina que você tem uma tabela do Excel com 10.000 linhas e o chefe manda: "Joga isso aí no banco!" Hmm... se você tentar inserir tudo na mão, provavelmente vai precisar não só de skills em SQL, mas também de umas férias. 😅

Por sorte, o PostgreSQL tem um comando que funciona tipo um teletransporte do CSV pro banco — é o COPY. Ele carrega os dados na hora, em massa e sem enrolação. Hoje vamos ver como o COPY funciona, como preparar os dados e o que fazer se aparecer uma "vírgula flutuante" ou um caractere estranho no arquivo. Bora lá!

O básico do comando COPY

COPY é um comando do PostgreSQL que permite mover dados entre uma tabela e o sistema de arquivos. Ele é útil pra carregar dados em massa pro banco ou exportar eles.

Exemplo de sintaxe do COPY pra carregar dados numa tabela:

COPY table_name FROM 'path/to/your/file.csv' DELIMITER ',' CSV HEADER;

Principais parâmetros:

• FROM 'path/to/your/file.csv': define o caminho pro seu arquivo CSV.
• DELIMITER ',': indica qual é o separador (nesse caso, a vírgula).
• CSV HEADER: diz que o arquivo CSV tem cabeçalho (primeira linha com os nomes das colunas).

O comando COPY roda direto no servidor, o que faz ele ser super rápido pra trabalhar com grandes volumes de dados.

Diferença entre COPY e \COPY

Às vezes você pode ficar meio confuso entre COPY e \COPY.

• COPY: executa no lado do servidor. Usado pra carregar arquivos que estão no servidor.
• \COPY: comando do cliente, disponível no psql. O upload dos dados é feito do seu computador local.

Se você tá trabalhando na sua máquina, provavelmente vai usar o \COPY. A gente fala dele daqui a pouco.

Exemplo de uso do COPY

Bora direto pro exemplo, que é o melhor jeito de entender como funciona na prática.

Passo 1: Preparando a tabela

Imagina que a gente vai criar uma tabela pra guardar informações dos estudantes:

CREATE TABLE students (
    student_id SERIAL PRIMARY KEY,
    first_name VARCHAR(50),
    last_name VARCHAR(50),
    date_of_birth DATE,
    grade FLOAT
);

Passo 2: Preparando o arquivo CSV

O formato do seu arquivo CSV tem que bater com a tabela. Exemplo do arquivo students.csv:

first_name,last_name,date_of_birth,grade
John,Doe,2001-05-15,85.5
Jane,Smith,2000-12-22,90.0
Alice,Johnson,2002-03-10,78.0
Bob,Brown,2001-08-30,NULL

Repara: a ordem das colunas no CSV tem que ser igual à da tabela, e os tipos de dados também (por exemplo, a data tem que estar no formato YYYY-MM-DD).

Passo 3: Carregando os dados

Pra carregar o arquivo students.csv na tabela students, usa esse comando aqui:

COPY students (first_name, last_name, date_of_birth, grade)
FROM '/path/to/your/students.csv'
DELIMITER ',' 
CSV HEADER;

O que tá rolando aqui?

• A gente indica o nome da tabela students e as colunas onde os dados vão entrar.
• O caminho do arquivo mostra onde ele tá salvo.
• O separador , diz que os dados estão separados por vírgula.
• O parâmetro CSV HEADER avisa pro PostgreSQL que a primeira linha do arquivo tem os nomes das colunas.

Resultado:

Depois de rodar o comando, os dados do arquivo vão pra tabela e você já pode conferir na hora:

SELECT * FROM students;

Limitações e detalhes importantes

Pra não dar ruim, garante que seu arquivo CSV segue esses requisitos:

1. Nada de caracteres escondidos ou espaços na linha do cabeçalho.
2. Usa a codificação certa: no PostgreSQL, normalmente é UTF-8.
3. O separador tem que ser igual ao parâmetro DELIMITER que você colocou.

Erros comuns ao carregar com COPY:

Estrutura dos dados diferente. Por exemplo, se você tentar jogar um texto numa coluna que espera número:

ERROR: invalid input syntax for type numeric: "abc"

Pra evitar isso, confere se os dados tão no tipo certo.

Erro no caminho do arquivo.

Se o arquivo não estiver numa pasta acessível pelo PostgreSQL no servidor, vai aparecer esse erro:

ERROR: could not open file "/path/to/your/file.csv" for reading: Permission denied

Pra resolver, ajusta as permissões do arquivo certinho.

Como conferir se os dados foram carregados certinho?

Depois de carregar os dados, é bom garantir que deu tudo certo. Por exemplo:

Conferindo o total de linhas:

SELECT COUNT(*) FROM students;

Procurando valores vazios (tipo se a coluna grade tem NULL):

SELECT * FROM students WHERE grade IS NULL;

Dicas úteis pra usar o COPY

Loga os erros. Se quiser salvar os erros num arquivo separado, usa o parâmetro LOG ERRORS. (No PostgreSQL versão 12+).

Desativa índices e triggers.

Quando for carregar muitos dados, pode desativar os índices temporariamente:

ALTER TABLE students DISABLE TRIGGER ALL;

Usa transações.

Assim você carrega os dados de forma "atômica" — ou vai tudo, ou nada se der erro:

BEGIN;
COPY students FROM '/path/to/your/file.csv' CSV HEADER;
COMMIT;

Aplicações práticas

Saber usar o comando COPY não é só pra quem administra banco — pra dev também facilita muito a vida. Imagina que você recebe um monte de dados de uma API externa: primeiro salva num CSV, depois joga rapidinho no PostgreSQL — e já pode começar a analisar. Ou então, o pessoal pede pra migrar o banco antigo pra um novo no PostgreSQL. Nessas horas, o COPY é tipo um superpoder.

Arquivos CSV aparecem o tempo todo nos projetos reais. Por exemplo:

• Você carrega estatísticas de vendas pra um sistema de análise.
• Importa uma lista de usuários de um CRM externo.
• Transfere dados do Excel pro PostgreSQL sem dor de cabeça.

Por hoje é isso sobre o comando COPY. Na próxima aula, vamos falar sobre como preparar as tabelas pra receber os dados e pensar na estrutura delas pra tudo rodar rápido e sem stress. Enquanto isso, não tenha medo de testar — o COPY realmente abre portas pra trabalhar com grandes volumes de informação de um jeito prático.