Como você carrega dados em massa de forma eficiente com COPY?

Question

Accepted Answer

**`COPY`** é o comando de alto desempenho do PostgreSQL para **carregamento em massa e exportação** de dados — movimentando grandes quantidades de dados entre um arquivo (ou stream) e uma tabela muito mais rapidamente do que usando instruções `INSERT` individuais. É a ferramenta padrão para importação/exportação de grandes conjuntos de dados.

## Carregamento em massa rápido com COPY

```sql
-- load data from a CSV file into a table (server-side; needs file access + privileges)
COPY users (name, email, age) FROM '/path/data.csv' WITH (FORMAT csv, HEADER true);

-- export a table to a CSV file
COPY users TO '/path/export.csv' WITH (FORMAT csv, HEADER true);

-- from psql (client-side — works without server file access): use \copy
\copy users FROM 'data.csv' WITH (FORMAT csv, HEADER true)
```

`COPY` lê/escreve um arquivo inteiro em uma única operação — dramaticamente mais rápido do que executar milhares de INSERTs individuais.

## Por que COPY é muito mais rápido que INSERT

```text
❌ thousands of individual INSERTs:
   each is a separate statement → per-statement overhead, possibly per-row transactions,
   network round-trips → SLOW for large data (can be 10-100x slower)

✅ COPY:
   one bulk operation, minimal overhead, optimized data path → FAST
→ For loading large datasets, COPY is the go-to; INSERTs are for small/individual rows.
```

## COPY vs \copy (lado do servidor vs lado do cliente)

```text
COPY (SQL command) → reads/writes files on the SERVER, needs superuser/file privileges
\copy (psql command) → reads/writes files on the CLIENT, no special privileges
→ Use \copy when running from your machine against a remote database.
```

## Dicas para carregamento em massa de grandes conjuntos de dados

```text
✓ Use COPY (not INSERTs) for large data
✓ Consider dropping/disabling indexes and constraints during a huge load, then
  recreating them after (building an index once is faster than maintaining it per-row)
✓ Load within a single transaction; increase maintenance_work_mem for index rebuilds
✓ For programmatic bulk inserts, use multi-row INSERT or the driver's COPY support
```

## Por que isso importa

`COPY` é a ferramenta essencial do PostgreSQL para **carregamento e exportação eficiente de dados em massa**, e compreendê-la é valioso para qualquer cenário envolvendo grandes conjuntos de dados — migrações de dados, ETL, importações/exportações, seed de dados e análises, que são necessidades comuns do mundo real.

O valor-chave é **desempenho**: carregar grandes quantidades de dados com instruções `INSERT` individuais é dramaticamente lento (sobrecarga por declaração, round-trips — potencialmente 10-100x mais lento), enquanto `COPY` realiza o carregamento como uma única operação em massa otimizada, tornando-se a solução padrão para importação ou exportação de grandes conjuntos de dados (milhares a milhões de linhas).

Compreender *por que* COPY é tão mais rápido (operação em massa vs sobrecarga por linha) esclarece quando usá-lo (dados grandes) versus INSERTs (linhas pequenas/individuais).

Conhecer a distinção prática entre **`COPY`** (comando SQL no lado do servidor, requer acesso/privilégios de arquivo) e **`\ copy`** (comando no lado do cliente psql, sem privilégios especiais — funciona contra banco de dados remotos da sua máquina) é importante para realmente usá-lo em diferentes contextos.

As **dicas de carregamento em massa** (usar COPY em vez de INSERTs, descartar/recriar índices em torno de carregamentos enormes, já que criar um índice uma vez é melhor do que mantê-lo por linha, carregar em uma transação) são conhecimentos de otimização valiosos para grandes importações.

Como operações de dados em massa (migrações, importações, exportações, ETL) são comuns, e como COPY é a forma padrão e de alto desempenho para lidar com elas no PostgreSQL (superando vastamente INSERTs para dados grandes), compreender COPY — seu benefício de desempenho, a distinção COPY vs \copy e as melhores práticas de carregamento em massa — é conhecimento valioso e praticamente relevante para movimentar eficientemente grandes conjuntos de dados para dentro e fora do Postgres, uma necessidade operacional frequente onde usar a ferramenta correta (COPY) faz uma diferença significativa.