Descripción

COPY mueve datos entre tablas de PostgreSQL y archivos del sistema de archivos estándar. COPY TO copia el contenido de una tabla hacia un archivo, mientras que COPY FROM copia datos desde un archivo hacia una tabla (añadiendo los datos a lo que ya se encuentre en la tabla). COPY TO también puede copiar los resultados de una consulta SELECT.

Si se especifica una lista de columnas, COPY TO copia únicamente los datos de las columnas especificadas en el archivo. Para COPY FROM, cada campo en el archivo se inserta, en orden, en la columna especificada. Las columnas de la tabla no especificadas en la lista de columnas de COPY FROM recibirán sus valores por defecto.

COPY con un nombre de archivo le indica al servidor PostgreSQL que lea o escriba directamente en un archivo. El archivo debe ser accesible por el usuario de PostgreSQL (el ID de usuario bajo el cual se ejecuta el servidor) y el nombre debe especificarse desde el punto de vista del servidor. Cuando se especifica PROGRAM, el servidor ejecuta el comando dado y lee de la salida estándar del programa, o escribe en la entrada estándar del mismo. El comando debe especificarse desde el punto de vista del servidor y debe ser ejecutable por el usuario de PostgreSQL. Cuando se especifica STDIN o STDOUT, los datos se transmiten a través de la conexión entre el cliente y el servidor.

Cada proceso de respaldo (backend) que ejecute COPY informará de su progreso en la vista pg_stat_progress_copy. Consulta Section 27.4.3 para obtener más detalles.

Por defecto, COPY fallará si encuentra un error durante el procesamiento. Para casos de uso donde se desee un intento de mejor esfuerzo para cargar todo el archivo, se puede utilizar la cláusula ON_ERROR para especificar algún otro comportamiento.

Parámetros

Salidas

Al completarse con éxito, un comando COPY devuelve una etiqueta de comando de la forma

COPY count

El count es el número de filas copiadas.

Notas

COPY TO se puede utilizar con tablas normales y vistas materializadas pobladas. Por ejemplo, COPY table TO copia las mismas filas que SELECT * FROM ONLY table. Sin embargo, no admite directamente otros tipos de relaciones, como tablas particionadas, tablas hijas de herencia o vistas. Para copiar todas las filas de dichas relaciones, utiliza COPY (SELECT * FROM table) TO.

COPY FROM se puede utilizar con tablas normales, foráneas o particionadas, o con vistas que tengan disparadores (triggers) de tipo INSTEAD OF INSERT.

Debes tener el privilegio de selección (select) en la tabla cuyos valores son leídos por COPY TO, y el privilegio de inserción (insert) en la tabla en la cual se insertan los valores mediante COPY FROM. Es suficiente tener privilegios de columna en las columnas enumeradas en el comando.

Si la seguridad a nivel de fila está activada para la tabla, se aplicarán las políticas de selección SELECT pertinentes a las instrucciones COPY table TO. Actualmente, COPY FROM no es compatible con tablas que tengan activada la seguridad a nivel de fila. Utiliza instrucciones INSERT equivalentes en su lugar.

Los archivos nombrados en un comando COPY son leídos o escritos directamente por el servidor, no por la aplicación cliente. Por lo tanto, deben residir en la máquina del servidor de la base de datos o ser accesibles para ella, no para el cliente. Deben ser accesibles y legibles o escribibles por el usuario de PostgreSQL (el ID de usuario bajo el cual se ejecuta el servidor), no por el cliente. Del mismo modo, el comando especificado con PROGRAM es ejecutado directamente por el servidor, no por la aplicación cliente, y debe ser ejecutable por el usuario de PostgreSQL. El uso de COPY para especificar un archivo o programa solo se permite a los superusuarios de la base de datos o a los usuarios que tengan concedido alguno de los roles pg_read_server_files, pg_write_server_files o pg_execute_server_program, ya que permite leer o escribir cualquier archivo o ejecutar un programa al que el servidor tenga privilegios de acceso.

No confundas COPY con la instrucción de psql \copy. \copy invoca COPY FROM STDIN o COPY TO STDOUT, y luego recupera/almacena los datos en un archivo accesible para el cliente psql. Por lo tanto, la accesibilidad de los archivos y los derechos de acceso dependen del cliente y no del servidor cuando se utiliza \copy.

Se recomienda que el nombre del archivo utilizado en COPY se especifique siempre como una ruta absoluta. Esto es obligatorio para el servidor en el caso de COPY TO, pero para COPY FROM tienes la opción de leer de un archivo especificado mediante una ruta relativa. La ruta se interpretará en relación con el directorio de trabajo del proceso del servidor (normalmente el directorio de datos del clúster), no el directorio de trabajo del cliente.

La ejecución de un comando con PROGRAM puede estar restringida por los mecanismos de control de acceso del sistema operativo, como SELinux.

COPY FROM invocará cualquier disparador (trigger) y restricción de comprobación (check constraint) en la tabla de destino. Sin embargo, no invocará reglas.

Para las columnas de identidad, el comando COPY FROM siempre escribirá los valores de las columnas proporcionados en los datos de entrada, al igual que la opción OVERRIDING SYSTEM VALUE de INSERT.

La entrada y salida de COPY se ve afectada por DateStyle. Para garantizar la portabilidad a otras instalaciones de PostgreSQL que puedan utilizar configuraciones de DateStyle que no sean las por defecto, DateStyle debe establecerse en ISO antes de usar COPY TO. También es una buena idea evitar volcar datos con IntervalStyle establecido en sql_standard, porque los valores de intervalo negativos pueden ser malinterpretados por un servidor que tenga una configuración diferente para IntervalStyle.

Los datos de entrada se interpretan de acuerdo con la opción ENCODING o la codificación actual del cliente, y los datos de salida se codifican en la opción ENCODING o en la codificación actual del cliente, incluso si los datos no pasan a través del cliente sino que el servidor los lee o escribe directamente desde o hacia un archivo.

El comando COPY FROM inserta físicamente las filas de entrada en la tabla a medida que avanza. Si el comando falla, estas filas quedan en un estado eliminado; estas filas no serán visibles, pero seguirán ocupando espacio en disco. Esto podría equivaler a un desperdicio considerable de espacio en disco si el fallo ocurrió bien avanzada una operación de copia grande. Se debe usar VACUUM para recuperar el espacio desperdiciado.

FORCE_NULL y FORCE_NOT_NULL se pueden utilizar simultáneamente en la misma columna. Esto da como resultado la conversión de cadenas nulas entrecomilladas en valores nulos y cadenas nulas sin entrecomillar en cadenas vacías.

Formatos de archivo

Ejemplos

El siguiente ejemplo copia una tabla al cliente utilizando la barra vertical (|) como delimitador de campos:

COPY country TO STDOUT (DELIMITER '|');

Para copiar datos de un archivo en la tabla country:

COPY country FROM '/usr1/proj/bray/sql/country_data';

Para copiar en un archivo únicamente los países cuyos nombres comiencen con 'A':

COPY (SELECT * FROM country WHERE country_name LIKE 'A%') TO '/usr1/proj/bray/sql/a_list_countries.copy';

Para copiar en un archivo comprimido, puedes canalizar la salida a través de un programa de compresión externo:

COPY country TO PROGRAM 'gzip > /usr1/proj/bray/sql/country_data.gz';

Aquí hay una muestra de datos adecuados para copiar en una tabla desde STDIN:

AF      AFGHANISTAN
AL      ALBANIA
DZ      ALGERIA
ZM      ZAMBIA
ZW      ZIMBABWE

Ten en cuenta que el espacio en blanco en cada línea es en realidad un carácter de tabulación.

El siguiente código muestra los mismos datos, exportados en formato binario. Los datos se muestran después de filtrarlos a través de la utilidad de Unix od -c. La tabla tiene tres columnas; la primera tiene el tipo char(2), la segunda tiene el tipo text, y la tercera tiene el tipo integer. Todas las filas tienen un valor nulo en la tercera columna.

0000000   P   G   C   O   P   Y  \n 377  \r  \n  \0  \0  \0  \0  \0  \0
0000020  \0  \0  \0  \0 003  \0  \0  \0 002   A   F  \0  \0  \0 013   A
0000040   F   G   H   A   N   I   S   T   A   N 377 377 377 377  \0 003
0000060  \0  \0  \0 002   A   L  \0  \0  \0 007   A   L   B   A   N   I
0000100   A 377 377 377 377  \0 003  \0  \0  \0 002   D   Z  \0  \0  \0
0000120 007   A   L   G   E   R   I   A 377 377 377 377  \0 003  \0  \0
0000140  \0 002   Z   M  \0  \0  \0 006   Z   A   M   B   I   A 377 377
0000160 377 377  \0 003  \0  \0  \0 002   Z   W  \0  \0  \0  \b   Z   I
0000200   M   B   A   B   W   E 377 377 377 377 377 377

Compatibilidad

No existe una instrucción COPY en el estándar SQL.

La siguiente sintaxis se utilizaba antes de la versión 9.0 de PostgreSQL y todavía es compatible:

COPY table_name [ ( column_name [, ...] ) ]
    FROM { 'filename' | STDIN }
    [ [ WITH ]
          [ BINARY ]
          [ DELIMITER [ AS ] 'delimiter_character' ]
          [ NULL [ AS ] 'null_string' ]
          [ CSV [ HEADER ]
                [ QUOTE [ AS ] 'quote_character' ]
                [ ESCAPE [ AS ] 'escape_character' ]
                [ FORCE NOT NULL column_name [, ...] ] ] ]

COPY { table_name [ ( column_name [, ...] ) ] | ( query ) }
    TO { 'filename' | STDOUT }
    [ [ WITH ]
          [ BINARY ]
          [ DELIMITER [ AS ] 'delimiter_character' ]
          [ NULL [ AS ] 'null_string' ]
          [ CSV [ HEADER ]
                [ QUOTE [ AS ] 'quote_character' ]
                [ ESCAPE [ AS ] 'escape_character' ]
                [ FORCE QUOTE { column_name [, ...] | * } ] ] ]

Ten en cuenta que en esta sintaxis, BINARY y CSV se tratan como palabras clave independientes, no como argumentos de una opción FORMAT.

La siguiente sintaxis se utilizaba antes de la versión 7.3 de PostgreSQL y todavía es compatible:

COPY [ BINARY ] table_name
    FROM { 'filename' | STDIN }
    [ [USING] DELIMITERS 'delimiter_character' ]
    [ WITH NULL AS 'null_string' ]

COPY [ BINARY ] table_name
    TO { 'filename' | STDOUT }
    [ [USING] DELIMITERS 'delimiter_character' ]
    [ WITH NULL AS 'null_string' ]

Consulte también