Uso de \COPY para cargar datos desde tu ordenador local

El comando \COPY está pensado para cargar datos en PostgreSQL directamente desde tu ordenador local. A diferencia de COPY, que interactúa con archivos en el servidor de PostgreSQL, el comando \COPY trabaja con archivos accesibles desde el lado del cliente, o sea, tu portátil o tu PC de escritorio.

El comando \COPY se usa cuando trabajas con archivos en tu propio ordenador, por ejemplo, tu portátil. A diferencia de COPY, que lee archivos desde el servidor, \COPY te permite cargar datos que tienes justo a mano.

Esto es súper útil cuando estás desarrollando o probando un proyecto en tu máquina, o cuando no tienes acceso al sistema de archivos del servidor de PostgreSQL. Este enfoque es especialmente popular entre desarrolladores y analistas que necesitan cargar un archivo CSV rápido para comprobar algo sin complicaciones.

Diferencias entre COPY y \COPY

A primera vista los comandos COPY y \COPY parecen iguales, pero su funcionamiento es distinto:

• COPY se ejecuta en el lado del servidor y requiere que el archivo esté en un directorio accesible para PostgreSQL. Además, PostgreSQL debe tener permisos de lectura sobre ese archivo.

• \COPY se ejecuta en el lado del cliente, o sea, el archivo debe estar accesible para la aplicación cliente, como psql. Usando \COPY, puedes cargar datos desde archivos que tienes en tu ordenador, incluso si no tienes acceso al servidor.

Bases del uso de \COPY

Sintaxis del comando

\COPY tabla FROM 'file_path' [WITH] (opciones)

Dónde:

• tabla: nombre de la tabla donde se van a cargar los datos.
• file_path: ruta al archivo en tu ordenador local.
• opciones: parámetros opcionales para personalizar el comportamiento de la función.

Ejemplo:

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

• students: nombre de la tabla donde se cargan los datos.
• 'C:/data/students.csv': ruta al archivo en tu ordenador local.
• DELIMITER ',': indica el carácter separador de datos en el archivo (coma en este caso).
• CSV HEADER: indica que la primera línea del archivo contiene los nombres de las columnas.

Ejemplo:

Supón que tienes un archivo students.csv con datos de estudiantes, que está en tu carpeta local, por ejemplo, C:/data/students.csv. Su contenido es:

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

Queremos cargar estos datos en la tabla students. Antes, he creado la tabla en PostgreSQL con esta estructura:

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

Ahora usamos el comando \COPY para cargar los datos:

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

Después de ejecutar este comando, la tabla students tendrá tres registros del archivo students.csv. Puedes comprobarlo así:

SELECT * FROM students;

Resultado esperado:

Parámetros del comando \COPY

Al usar \COPY, sobre todo en formato CSV, es importante conocer los parámetros clave que te permiten controlar el formato de los datos y facilitar el proceso. Aquí tienes los más populares.

Parámetro FORMAT

Define el formato de los datos. Los valores más usados son: text, csv.

Ejemplo:

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

¿Para qué sirve?: sin este parámetro, PostgreSQL asumirá que usas formato texto con tabulaciones. csv es más universal y fácil de leer.

Parámetro HEADER

Indica que la primera línea del archivo CSV contiene los nombres de las columnas, no los datos.

Ejemplo:

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

¿Para qué sirve?: permite excluir la cabecera del import — muy útil si exportas desde Excel u otros sistemas.

Parámetro DELIMITER

Define el carácter separador de los campos. Por defecto es coma para CSV, tabulación para TEXT.

Ejemplo:

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

¿Para qué sirve?: te permite adaptar el import/export a formatos CSV no estándar, por ejemplo, con punto y coma (muy usado en Europa).

Parámetro ENCODING

Indica la codificación del archivo.

Ejemplo:

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

¿Para qué sirve?: permite cargar archivos en codificación Windows u otros sistemas sin tener que recodificar a mano.

Parámetro NULL

Define qué valor de texto en el archivo se considerará como NULL.

Ejemplo:

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

¿Para qué sirve?: si en los archivos los valores ausentes aparecen como 'NULL', esto ayuda a interpretar bien los campos vacíos.

Limitaciones y particularidades de \COPY

1. Requisitos del cliente de PostgreSQL

psql es el cliente de PostgreSQL que soporta el comando \COPY. Asegúrate de usarlo para trabajar con la base de datos. Ten en cuenta que otros clientes, como pgAdmin, pueden no soportar \COPY.

2. Codificación del archivo

Fíjate en la codificación del archivo que vas a cargar. PostgreSQL espera que el archivo esté en UTF-8. Si el archivo tiene otra codificación (por ejemplo, Windows-1251), pueden aparecer errores. Puedes convertir la codificación con utilidades como iconv o editores de texto (por ejemplo, VS Code).

3. Localización de la ruta al archivo

En Windows la ruta al archivo puede tener barras invertidas (\). En ese caso, cámbialas por barras normales (/). Por ejemplo, en vez de C:\data\students.csv usa C:/data/students.csv.

Errores típicos y cómo solucionarlos

1. Error de acceso al archivo.

Si ves algo como:

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

Asegúrate de que:

• El archivo existe en la ruta indicada.
• Has puesto la ruta absoluta correcta.
• Tienes permisos de acceso al archivo.

2. Error de estructura de datos diferente. Si la estructura del archivo que cargas es distinta a la de la tabla, tendrás un error. Por ejemplo, si el archivo tiene columnas extra o tipos de datos incorrectos, aparecerá un mensaje de error. Revisa los nombres de las columnas y sus tipos antes de cargar.

3. Problemas de codificación. Si el archivo no está en UTF-8, verás caracteres raros en vez de texto. Solución: convierte el archivo a UTF-8 antes de cargarlo.

Ventajas de usar \COPY

1. Facilidad de uso. Puedes cargar datos desde un archivo con un solo comando. No necesitas mover archivos al servidor.

2. Versatilidad. psql está disponible en todos los sistemas operativos principales, así que puedes usar \COPY casi en cualquier sitio.

3. Sin problemas de permisos. Como el comando funciona en el lado del cliente, no tienes que preocuparte por los permisos de los archivos en el servidor.

Limitaciones y recomendaciones

Aunque es muy cómodo, el comando \COPY tiene algunas limitaciones:

• No es adecuado para archivos muy grandes, ya que los datos se transfieren por la red entre el cliente y el servidor. En esos casos, es mejor usar COPY en el servidor.
• Asegúrate de que tu archivo está listo para cargar: corrige errores, elimina líneas sobrantes y que la estructura coincida con la tabla.

Para proyectos grandes, es recomendable probar primero la carga con un conjunto pequeño de datos y solo después procesar el archivo completo.