COPY

Nombre

COPY  --  Copia datos entre ficheros y tablas

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.

Nota

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.

Sugerencia

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
uint32numero de tuplas
Para cada tupla
uint32Longitud total de la tupla de datos
uint32identificador (si se especifica)
uint32numero 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
  

Compatibility

SQL92

No existe la sentencia COPY en SQL 92.