Użycie \COPY do ładowania danych z lokalnego komputera

Komenda \COPY służy do ładowania danych do PostgreSQL bezpośrednio z twojego lokalnego kompa. W przeciwieństwie do COPY, która działa na plikach na serwerze PostgreSQL, \COPY pracuje z plikami dostępnymi po stronie klienta, czyli np. na twoim laptopie albo pececie.

Komendy \COPY używasz wtedy, gdy masz pliki na swoim lokalnym kompie, np. na laptopie. W odróżnieniu od COPY, która czyta pliki z serwera, \COPY pozwala ładować dane, które masz pod ręką.

To mega wygodne, gdy rozwijasz albo testujesz projekt u siebie na maszynie, albo nie masz dostępu do systemu plików samego serwera PostgreSQL. Takie podejście jest szczególnie popularne wśród devów i analityków, którzy chcą szybko wrzucić CSV do bazy, żeby coś sprawdzić bez zbędnych ceregieli.

Różnice między COPY a \COPY

Na pierwszy rzut oka COPY i \COPY wyglądają podobnie, ale ich działanie się różni:

• COPY działa po stronie serwera i wymaga, żeby plik był w katalogu dostępnym dla PostgreSQL. Serwer musi mieć prawa do odczytu tego pliku.

• \COPY działa po stronie klienta, czyli plik musi być dostępny dla aplikacji klienckiej, np. psql. Dzięki \COPY możesz ładować dane z plików na swoim kompie, nawet jeśli nie masz dostępu do serwera.

Podstawy użycia \COPY

Składnia komendy

\COPY tabela FROM 'file_path' [WITH] (opcje)

Gdzie:

• tabela: nazwa tabeli, do której ładujesz dane.
• file_path: ścieżka do pliku na twoim lokalnym kompie.
• opcje: opcjonalne parametry, które pozwalają dostosować zachowanie funkcji.

Przykład:

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

• students: nazwa tabeli, do której ładujesz dane.
• 'C:/data/students.csv': ścieżka do pliku na twoim lokalnym kompie.
• DELIMITER ',': określa znak separatora danych w pliku (tu przecinek).
• CSV HEADER: mówi, że pierwszy wiersz pliku to nagłówki kolumn.

Przykład:

Załóżmy, że masz plik students.csv z danymi o studentach, który leży w twoim lokalnym folderze, np. C:/data/students.csv. Zawartość pliku:

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

Chcemy załadować te dane do tabeli students. Najpierw stworzyłem tabelę w PostgreSQL o takiej strukturze:

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

Teraz używamy komendy \COPY do załadowania danych:

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

Po wykonaniu tej komendy tabela students będzie miała trzy rekordy z pliku students.csv. Możesz to sprawdzić tak:

SELECT * FROM students;

Oczekiwany wynik:

Parametry komendy \COPY

Przy użyciu \COPY, szczególnie w formacie CSV, warto ogarniać kluczowe parametry, które pozwalają kontrolować format danych i ułatwiają robotę. Poniżej najpopularniejsze z nich.

Parametr FORMAT

Określa format danych. Najczęściej używane wartości: text, csv.

Przykład:

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

Po co to: bez tego parametru PostgreSQL zakłada, że używasz formatu tekstowego z tabulatorem. csv jest bardziej uniwersalny i czytelny.

Parametr HEADER

Mówi, że pierwszy wiersz pliku CSV to nagłówki kolumn, a nie dane.

Przykład:

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

Po co to: pozwala pominąć nagłówek przy imporcie — szczególnie przydatne przy eksporcie z Excela albo innych systemów.

Parametr DELIMITER

Ustawia znak separatora pól. Domyślnie to przecinek dla CSV, tabulator dla TEXT.

Przykład:

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

Po co to: pozwala dostosować import/eksport do niestandardowych formatów CSV, np. z średnikiem (często w Europie).

Parametr ENCODING

Określa kodowanie pliku.

Przykład:

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

Po co to: pozwala poprawnie załadować pliki w kodowaniu Windows albo innych systemów bez ręcznego przekodowywania.

Parametr NULL

Określa, jaka wartość tekstowa w pliku będzie traktowana jako NULL.

Przykład:

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

Po co to: jeśli w pliku brakujące wartości są zapisane jako 'NULL', to ten parametr pozwala poprawnie je zinterpretować.

Ograniczenia i specyfika użycia \COPY

1. Wymagania dotyczące klienta PostgreSQL

psql to klient PostgreSQL, który obsługuje komendę \COPY. Upewnij się, że właśnie jego używasz do pracy z bazą. Pamiętaj, że inne klienty, np. pgAdmin, mogą nie obsługiwać \COPY.

2. Kodowanie pliku

Zwróć uwagę na kodowanie pliku, który ładujesz. PostgreSQL oczekuje UTF-8. Jeśli plik ma inne kodowanie (np. Windows-1251), mogą pojawić się błędy. Możesz przekonwertować plik narzędziami typu iconv albo edytorami tekstu (np. VS Code).

3. Lokalizacja ścieżki do pliku

Na Windowsie ścieżka do pliku może mieć backslashe (\). Zamień je na slashe (/). Zamiast C:\data\students.csv użyj C:/data/students.csv.

Typowe błędy i jak je ogarnąć

1. Błąd dostępu do pliku.

Jeśli widzisz coś takiego:

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

Sprawdź, czy:

• Plik istnieje pod wskazaną ścieżką.
• Podałeś poprawną ścieżkę absolutną.
• Masz prawa dostępu do pliku.

2. Błąd niezgodności struktury danych. Jeśli struktura pliku różni się od struktury tabeli, dostaniesz błąd. Np. jeśli plik ma dodatkowe kolumny albo złe typy danych, pojawi się komunikat o błędzie. Sprawdź nagłówki i typy kolumn przed ładowaniem.

3. Problemy z kodowaniem. Jeśli plik nie jest w UTF-8, zobaczysz "krzaki" zamiast tekstu. Rozwiązanie — przekonwertuj plik do UTF-8 przed ładowaniem.

Zalety użycia \COPY

1. Prosta obsługa. Możesz załadować dane z pliku jedną komendą. Nie musisz przerzucać plików na serwer.

2. Uniwersalność. psql działa na wszystkich głównych systemach operacyjnych, więc \COPY możesz używać praktycznie wszędzie.

3. Brak problemów z dostępem. Ponieważ komenda działa po stronie klienta, nie musisz się martwić o prawa do plików na serwerze.

Ograniczenia i rekomendacje

Mimo wygody, komenda \COPY ma pewne ograniczenia:

• Nie nadaje się do bardzo dużych plików, bo dane lecą przez sieć między klientem a serwerem. W takich przypadkach lepiej użyć COPY na serwerze.
• Upewnij się, że twój plik jest w pełni przygotowany do ładowania: poprawione błędy, usunięte zbędne wiersze, a struktura pliku zgadza się z tabelą.

Przy większych projektach polecam najpierw przetestować ładowanie na małych próbkach danych, a dopiero potem wrzucać cały plik.