COPY

PostgreSQL
Anterior		Siguiente

Synopsis

COPY [ BINARY ] table [ WITH OIDS ]
    FROM { 'filename' | stdin }
    [ [USING] DELIMITERS 'delimiter' ]
    [ WITH NULL AS 'null string' ]
COPY [ BINARY ] table [ WITH OIDS ]
    TO { 'filename' | stdout }
    [ [USING] DELIMITERS 'delimiter' ]
    [ WITH NULL AS 'null string' ]

Inputs

BINARY

Cambia el comportamiento del formato de campos, forzando a todos los datos a almacenarse o leerse como objetos binarios, en lugar de como texto.

table

El nombre de una tabla existente.

WITH OIDS

Copia el identificador de objeto interno único (OID) para cada fila.

filename

La ruta absoluta en formato Unix del fichero de entrada o salida.

stdin

Especifica que la entrada viene de un conducto o terminal.

stdout

Especifica que la salida va a un conducto o terminal.

delimiter

UN caracter que delimita los campos de entrada o salida.

null print

Una cadena para representar valores NULL. El valor por defecto es "\N" (backslash-N), por razones históricas. Puede preferir, por ejemplo, una cadena vacía.

En una copia de entrada, cualquier dato que coincida con esta cadena será almacenado como un valor NULL, por lo que debería asegurarse de usar la misma cadena que usó para la copia de salida-

Outputs

COPY: La copia se completó satisfactoriamente.
ERROR: reason: La copia falló por la razón indicada en el mensaje de error.

Descripción

COPY mueve datos entre tablas de Postgres y ficheros del sistema de archivos estandar. COPY indica al servidor Postgres que lea o escriba de o a un fichero. El fichero ha de ser diréctamente visible para el servidor, y el nombre completo ha de especificarse desde el punto de vista del servidor. Si se especifica stdin o stdout, los datos van de la aplicación cliente al servidor ( o viceversa).

Notes

La palabra clave BINARY obliga a que todos los datos se almacenen o lean como objetos binarios en lugar de como texto. Esto es elgo más rápido que el comportamiento normal de COPY pero el resultado no es generalmente portable, y los ficheros generados son algo más grandes aunque este es un factor que depende de los datos en sí. Por defecto, cuando se copia un texto se usa un tabulador ("\t") como delimitador. El delimitador puede cambiarse por cualquier otro caracter empleando la palabra clave USING DELIMITERS. Los caracteres dentro de los campos de datos que resulten coincidir con el delimitador serán encerrados entre comillas.

Ha de hacerse primero un select access en cualquier tabla cuyos valores sean leidos por COPY, y insert or update access en la tabla en la que se vayan a insertar los valores. El servidor necesita los permisos Unix adecuados sobre cualquier fichero que vaya a leerse o escribirse con este comando.

la palabra clave USING DELIMITERS especifica un caracter que se usará para delimitar entre columnas. Si se especifican varios caracteres en la cadena delimitadora, solo se usará el primer caracter.

No confunda COPY con la instrucción \copy de psql.

COPY no invoca regla ni acciones por defecto en las columnas. Sin embargo, puede invocar procedimientos disparados.

COPY detiene las operaciones en el primer error. Esto no produce problemas en el caso de COPY FROM, pero el destino, por supuesto, será parcialmente modificado en el caso de un COPY TO. VACUUM puede usarse para limpiar tras una copia fallida.

Debido a que el directorio de trabajo del servidor de Postgres no es normalmente el mismo que el directorio de trabajo del usuario, el resultado de copiar el fichero "foo" (sin añadir información de la ruta) puede dar lugar a resultados inesperados para el usuario inadvertido. En este caso, en lugar de foo, acabamos con $PGDATA/foo. Por lo general, debería usarse la ruta completa tal como se vería desde el servidor, al especificar los ficheros a copiar.

Los ficheros usados como argumentos para COPY deben residir o ser accesible por parte de la máquina servidor de base de datos, en los discos locales o en un sistema de ficheros de red.

Cuando se emplea una conexión TCP/IP, y se especifica un fichero objetivo, dicho fichero se escribirá en la máquina donde se esté ejecutando el servidor, no en la máquina del usuario.

File Formats

Text Format

Cuando se usa COPY TO sin la opción BINARY, el fichero generado tendrá cada fila (instancia) en una sola linea, con cada una de las columnas (atributo) separada por el caracter delimitador. Los caracteres delimitadores internos (los caracteres internos que coincidan con el delimitador) se precederán del caracter barra atrás ("\"). Los valores de atributo son cadenas de texto generados por la función de salida asociada con cada uno de los tipos de atributo. La función de salida para un tipo no debería tratar de generar el caracter barra atrás; éste será generado por en comando COPY.

El formato para cada instancia es

<attr1><separator><attr2><separator>...<separator><attrn><newline>

El identificador se situa en el principio de la linea, cuando se especifica WITH OIDS

Si COPY envía su salida a la salida estandar en lugar de a un fichero, enviará una barra invertida ("\") y un punto, seguidos de un caracter de salto de linea en una linea separada, cuando termina su salida. Similarmente, si COPY está leyendo de una salida estandar, esperará una barra invertida y un punto seguidos por un fin de linea, como los tres primeros caracteres de una linea para indicar el fin del fichero. Sin embargo, COPY terminará (y a continuación terminará la aplicación servidor) si se encuentra un EOF antes de que se encuentre esta cadena que indica el fin de fichero.

El caracter barra invertida tiene otros significados especiales. Un caracter barra invertida literal se representa como dos barras consecutivas ("\\". El caracter tabulador se representa con una barra invertida y un tabulador. EL caracter fin de linea se representa como una barra invertida y un fin de linea. Cuando se cargan datos de texto no generados por Postgres necesitará convertir el caracter barra invertida en un par de barras para asegurar que se carguen adecuadamente. (La secuencia "\N" siempre se interpretará como una barra invertida y un caracter "N", por compatibilidad. La solución más general es "\\N".)

Binary Format

EN el caso de COPY BINARY, los primeros cuatro bytes del fichero será el numero de instancias en el fichero. Si el numero es cero, el comando COPY BINARY leerá hasta que se encuentre el fin del fichero. En otro caso, dejará de leer cuando se lean ese numero de instancias. Los restantes datos en el fichero se ignorarán.

El formato para cada instancia en el fichero es como sigue. Nótese que este formato debe ser seguido exactamente. Las cantidades enteras de cuatro bytes sin signo se denominan uint32 en la tabal que sigue.

Tabla 1. Contenidos de un fichero binario de copy

En el principio del fichero
uint32	numero de tuplas
Para cada tupla
uint32	Longitud total de la tupla de datos
uint32	identificador (si se especifica)
uint32	numero de atributos nulos
[uint32,...,uint32]	numeros de atributos, contando desde cero
-	<tupla data>

Alineación de datos binarios

Sobre equipos Sun-3s, los atributos de 2 bytes se alinean en grupos de cuatro bytes. Los atributos de caracteres se alinean en grupos de un solo byte. En la mayoría de las otras máquinas, todos los atributos mayores de un byte se alinean en grupos de cuatro bytes. Nótese que los atributos de longituv variable vienen precedidos de la longitud del atributo; las matrices son simplemente cadenas continuas del elemento tipo de la matriz.

Usage

El siguiente ejemplo copia una tabla a la salida estandar, usando una barra vertical como delimitador de campo:

COPY country TO stdout USING DELIMITERS '|';

Para copiar datos de un fichero Unix a la tabla "country":

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

Ha aquí un ejemplo de datos adecuados para ser copiados a una tabla desde stdin (dado que tienen la secuencia de terminación en la última linea):

   AF      AFGHANISTAN
   AL      ALBANIA
   DZ      ALGERIA
   ...
   ZM      ZAMBIA
   ZW      ZIMBABWE
   \.

Los mismos datos, como salida en formato binario en una máquina Linux/i586. Los datos se muestran tras ser filtrados con el comando Unix od -c. La tabla tiene tres campos; el primero es char(2) y el segundo es text. Todas las filas tienen un valor null en el tercer campo. Nótese como el campo char(2) está relleno con nulos hasta alcanzar los cuatro bytes y el campo de texto es precedido por su longitud:

   355  \0  \0  \0 027  \0  \0  \0 001  \0  \0  \0 002  \0  \0  \0
   006  \0  \0  \0   A   F  \0  \0 017  \0  \0  \0   A   F   G   H
     A   N   I   S   T   A   N 023  \0  \0  \0 001  \0  \0  \0 002
    \0  \0  \0 006  \0  \0  \0   A   L  \0  \0  \v  \0  \0  \0   A
     L   B   A   N   I   A 023  \0  \0  \0 001  \0  \0  \0 002  \0
    \0  \0 006  \0  \0  \0   D   Z  \0  \0  \v  \0  \0  \0   A   L
     G   E   R   I   A
   ...              \n  \0  \0  \0   Z   A   M   B   I   A 024  \0
    \0  \0 001  \0  \0  \0 002  \0  \0  \0 006  \0  \0  \0   Z   W
    \0  \0  \f  \0  \0  \0   Z   I   M   B   A   B   W   E

Anterior	Inicio	Siguiente
COMMIT	Subir	CREATE AGGREGATE