Usando \COPY pra importar dados do seu computador local

O comando \COPY serve pra importar dados pro PostgreSQL direto do seu computador. Diferente do COPY, que mexe com arquivos lá no servidor do PostgreSQL, o \COPY trabalha com arquivos que estão aí no seu PC, tipo no seu notebook ou desktop.

Você usa o \COPY quando tá mexendo com arquivos no seu computador local, tipo no seu notebook. Diferente do COPY, que lê arquivos do servidor, o \COPY deixa você importar dados que tão aí na sua mão.

Isso é muito prático quando você tá desenvolvendo ou testando um projeto na sua máquina, ou quando não tem acesso ao sistema de arquivos do servidor PostgreSQL. Esse jeito é bem popular entre devs e analistas que precisam importar um CSV rapidinho pra testar alguma coisa sem complicação.

Diferença entre COPY e \COPY

À primeira vista, os comandos COPY e \COPY parecem iguais, mas o jeito que funcionam é diferente:

• COPY roda no lado do servidor e precisa que o arquivo esteja numa pasta que o PostgreSQL consiga acessar. O PostgreSQL tem que ter permissão pra ler esse arquivo.

• \COPY roda no lado do cliente, ou seja, o arquivo tem que estar acessível pro app cliente, tipo o psql. Usando \COPY, você pode importar arquivos que tão no seu PC, mesmo sem acesso ao servidor.

Como usar o \COPY

Sintaxe do comando

\COPY tabela FROM 'file_path' [WITH] (opções)

Onde:

• tabela: nome da tabela pra onde os dados vão ser importados.
• file_path: caminho do arquivo aí no seu computador.
• opções: parâmetros opcionais pra customizar o comportamento do comando.

Exemplo:

\COPY students FROM 'C:/data/students.csv' DELIMITER ',' CSV HEADER;

• students: nome da tabela pra onde os dados vão ser importados.
• 'C:/data/students.csv': caminho do arquivo aí no seu computador.
• DELIMITER ',': define o caractere separador dos dados no arquivo (aqui é vírgula).
• CSV HEADER: diz que a primeira linha do arquivo tem os nomes das colunas.

Exemplo:

Imagina que você tem um arquivo students.csv com dados dos estudantes, que tá numa pasta local, tipo C:/data/students.csv. O conteúdo dele é assim:

id,name,age,major
1,John Doe,20,Computer Science
2,Jane Smith,22,Mathematics
3,Emily White,21,Physics

A gente quer importar esses dados pra tabela students. Antes, eu criei a tabela no PostgreSQL com essa estrutura:

CREATE TABLE students (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    age INTEGER NOT NULL,
    major TEXT
);

Agora bora usar o comando \COPY pra importar os dados:

\COPY students FROM 'C:/data/students.csv' DELIMITER ',' CSV HEADER;

Depois de rodar esse comando, a tabela students vai ter três registros do arquivo students.csv. Você pode conferir assim:

SELECT * FROM students;

Resultado esperado:

Parâmetros do comando \COPY

Quando você usa o \COPY, principalmente com CSV, é bom entender os principais parâmetros que ajudam a controlar o formato dos dados e facilitam o processo. Aqui vão os mais usados.

Parâmetro FORMAT

Define o formato dos dados. Os mais comuns são: text, csv.

Exemplo:

\COPY users FROM 'users.csv' WITH (FORMAT csv)

Pra que serve: sem esse parâmetro, o PostgreSQL acha que você tá usando formato texto com tabulação. csv é mais universal e fácil de ler.

Parâmetro HEADER

Diz que a primeira linha do CSV tem os nomes das colunas, não os dados.

Exemplo:

\COPY users FROM 'users.csv' WITH (FORMAT csv, HEADER)

Pra que serve: evita importar o cabeçalho como dado — muito útil quando você exporta do Excel ou outros sistemas.

Parâmetro DELIMITER

Define o caractere separador dos campos. Por padrão é vírgula no CSV, tabulação no TEXT.

Exemplo:

\COPY products FROM 'products.csv' WITH (FORMAT csv, DELIMITER ';')

Pra que serve: deixa você adaptar a importação/exportação pra CSVs diferentes, tipo com ponto e vírgula (bem comum na Europa).

Parâmetro ENCODING

Define a codificação do arquivo.

Exemplo:

\COPY clients FROM 'clients.csv' WITH (FORMAT csv, HEADER, ENCODING 'WIN1251')

Pra que serve: permite importar arquivos em codificação do Windows ou outros sistemas sem precisar converter manualmente.

Parâmetro NULL

Define qual valor de texto no arquivo vai ser considerado NULL.

Exemplo:

\COPY orders FROM 'orders.csv' WITH (FORMAT csv, NULL 'NULL')

Pra que serve: quando o arquivo usa a string 'NULL' pra valores ausentes, isso ajuda a interpretar os campos vazios certinho.

Limitações e detalhes do uso do \COPY

1. Requisitos do cliente PostgreSQL

psql é o cliente PostgreSQL que suporta o comando \COPY. Confere se você tá usando ele pra mexer no banco. Outros clientes, tipo o pgAdmin, podem não suportar o \COPY.

2. Codificação do arquivo

Fica ligado na codificação do arquivo que você vai importar. O PostgreSQL espera que o arquivo esteja em UTF-8. Se for outra codificação (tipo Windows-1251), pode dar erro. Você pode converter a codificação com ferramentas tipo iconv ou editores de texto (tipo VS Code).

3. Caminho do arquivo

No Windows, o caminho pode ter barra invertida (\). Troca por barra normal (/). Por exemplo, em vez de C:\data\students.csv usa C:/data/students.csv.

Erros comuns e como resolver

1. Erro de acesso ao arquivo.

Se aparecer algo tipo:

could not open file "C:/data/students.csv" for reading: No such file or directory

Confere se:

• O arquivo existe nesse caminho.
• Você colocou o caminho absoluto certinho.
• Você tem permissão pra acessar o arquivo.

2. Erro de estrutura dos dados. Se a estrutura do arquivo for diferente da tabela, vai dar erro. Por exemplo, se o arquivo tem colunas a mais ou tipos de dados errados, vai aparecer mensagem de erro. Confere os nomes das colunas e os tipos antes de importar.

3. Problemas de codificação. Se o arquivo não for UTF-8, vai aparecer uns caracteres estranhos no lugar do texto. Solução: converte o arquivo pra UTF-8 antes de importar.

Vantagens de usar o \COPY

1. Facilidade de uso. Você importa dados com um comando só. Não precisa mover arquivos pro servidor.

2. Versatilidade. psql roda em todos os sistemas operacionais principais, então dá pra usar \COPY em qualquer lugar.

3. Sem dor de cabeça com permissão. Como o comando roda no cliente, você não precisa se preocupar com permissão de arquivo no servidor.

Limitações e recomendações

Apesar de ser prático, o \COPY tem algumas limitações:

• Não é legal pra arquivos muito grandes, porque os dados passam pela rede entre o cliente e o servidor. Pra esses casos, é melhor usar o COPY direto no servidor.
• Confere se seu arquivo tá pronto pra importar: sem erros, sem linhas extras, e a estrutura igual à tabela.

Pra projetos grandes, é melhor testar a importação com um arquivo pequeno antes de mandar o arquivo completo.