Utilizzo di \COPY per caricare dati dal computer locale

Il comando \COPY serve per caricare dati in PostgreSQL direttamente dal tuo computer locale. A differenza di COPY, che lavora con file sul server PostgreSQL, il comando \COPY lavora con file disponibili sul lato client, tipo sul tuo portatile o PC di lavoro.

Usi \COPY quando lavori con file che hai sul tuo computer, tipo il portatile. A differenza di COPY, che legge file dal server, \COPY ti permette di caricare dati che hai proprio lì sotto mano.

È super comodo quando stai sviluppando o testando un progetto sulla tua macchina, oppure quando non hai accesso al filesystem del server PostgreSQL. Questo metodo è molto popolare tra dev e analyst che devono caricare al volo un file CSV per fare qualche check senza troppi sbatti.

Differenza tra COPY e \COPY

A prima vista i comandi COPY e \COPY sembrano simili, ma funzionano in modo diverso:

• COPY gira sul server e richiede che il file sia in una cartella accessibile da PostgreSQL. Serve che PostgreSQL abbia i permessi per leggere quel file.

• \COPY gira sul client, cioè il file deve essere accessibile dall'app client, tipo psql. Con \COPY puoi caricare dati da file che hai sul tuo computer, anche se non hai accesso al server.

Basi dell'utilizzo di \COPY

Sintassi del comando

\COPY tabella FROM 'file_path' [WITH] (opzioni)

Dove:

• tabella: nome della tabella dove carichi i dati.
• file_path: percorso del file sul tuo computer locale.
• opzioni: parametri opzionali per personalizzare il comportamento della funzione.

Esempio:

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

• students: nome della tabella dove carichi i dati.
• 'C:/data/students.csv': percorso del file sul tuo computer.
• DELIMITER ',': indica il carattere separatore dei dati nel file (in questo caso la virgola).
• CSV HEADER: indica che la prima riga del file contiene le intestazioni delle colonne.

Esempio:

Supponiamo di avere un file students.csv con dati sugli studenti, che si trova in una cartella locale, tipo C:/data/students.csv. Ecco il suo contenuto:

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

Vogliamo caricare questi dati nella tabella students. Prima ho creato la tabella in PostgreSQL con questa struttura:

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

Ora usiamo il comando \COPY per caricare i dati:

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

Dopo aver lanciato questo comando, la tabella students avrà tre record presi dal file students.csv. Puoi controllare così:

SELECT * FROM students;

Risultato atteso:

Parametri del comando \COPY

Quando usi \COPY, soprattutto in formato CSV, è importante capire i parametri chiave che ti permettono di controllare il formato dei dati e semplificare il lavoro. Qui sotto trovi i più usati.

Parametro FORMAT

Definisce il formato dei dati. I valori più usati sono: text, csv.

Esempio:

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

A cosa serve: senza questo parametro PostgreSQL pensa che usi il formato testo con tabulazione. csv è più universale e leggibile.

Parametro HEADER

Indica che la prima riga del file CSV contiene le intestazioni delle colonne, non i dati veri.

Esempio:

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

A cosa serve: ti permette di escludere l'intestazione dall'import — super utile se esporti da Excel o altri sistemi.

Parametro DELIMITER

Imposta il carattere separatore dei campi. Di default è la virgola per CSV, tabulazione per TEXT.

Esempio:

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

A cosa serve: ti permette di adattare l'import/export a CSV non standard, tipo con punto e virgola (molto usato in Europa).

Parametro ENCODING

Specifica la codifica del file.

Esempio:

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

A cosa serve: ti permette di caricare correttamente file in codifica Windows o altri sistemi senza doverli convertire a mano.

Parametro NULL

Definisce quale valore stringa nel file sarà considerato NULL.

Esempio:

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

A cosa serve: se nel file i valori mancanti sono scritti come 'NULL', questo aiuta a interpretarli giusti come campi vuoti.

Limitazioni e particolarità di \COPY

1. Requisiti del client PostgreSQL

psql è il client PostgreSQL che supporta il comando \COPY. Assicurati di usare proprio lui per lavorare col database. Occhio che altri client, tipo pgAdmin, potrebbero non supportare \COPY.

2. Codifica del file

Fai attenzione alla codifica del file che carichi. PostgreSQL si aspetta che il file sia in UTF-8. Se il file ha un'altra codifica (tipo Windows-1251), potrebbero esserci errori. Puoi convertire la codifica con tool come iconv o editor di testo (tipo VS Code).

3. Percorso del file su Windows

Su Windows il percorso del file può avere backslash (\). In questo caso sostituiscili con slash (/). Ad esempio, invece di C:\data\students.csv usa C:/data/students.csv.

Errori tipici e come risolverli

1. Errore di accesso al file.

Se vedi qualcosa tipo:

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

Controlla che:

• Il file esista davvero in quel percorso.
• Hai scritto il percorso assoluto giusto.
• Hai i permessi per accedere al file.

2. Errore di struttura dati non corrispondente. Se la struttura del file che carichi è diversa da quella della tabella, avrai un errore. Tipo, se il file ha colonne in più o tipi di dati sbagliati, ti arriva un messaggio di errore. Controlla le intestazioni delle colonne e i tipi prima di caricare.

3. Problemi di codifica. Se il file non è in UTF-8, vedrai caratteri strani invece del testo. Soluzione: converti il file in UTF-8 prima di caricare.

Vantaggi dell'utilizzo di \COPY

1. Semplicità d'uso. Puoi caricare dati da un file con un solo comando. Non serve spostare file sul server.

2. Universalità. psql gira su tutti i sistemi operativi principali, quindi puoi usare \COPY praticamente ovunque.

3. Niente problemi di permessi. Visto che il comando gira sul client, non devi preoccuparti dei permessi sui file del server.

Limitazioni e consigli

Nonostante sia comodo, il comando \COPY ha qualche limite:

• Non va bene per file enormi, perché i dati passano sulla rete tra client e server. In questi casi è meglio usare COPY direttamente sul server.
• Assicurati che il tuo file sia pronto per il caricamento: correggi errori, togli righe inutili e controlla che la struttura sia uguale a quella della tabella.

Per progetti grossi, ti consiglio di testare prima il caricamento su piccoli set di dati e solo dopo lavorare col file completo.