COPY

Documentation PostgreSQL 7.2
<<< Previous		Next >>>

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' ]

Entrées

BINARY

Change le comportement du formatage des champs, forçant toutes les données à être stockées ou lues comme objet binaire plus que comme texte. Les options DELIMITERS et WITH NULL sont non pertinentes pour le format binaire.

table

Nom d'un table existante.

WITH OIDS

Copie l'objet interne id (OID) pour chaque ligne.

filename

Le nom de fichier Unix absolu pour les fichiers entrée ou sortie.

stdin

Spécifie que l'entrée provient d'une application cliente.

stdout

Spécifie que la sortie va vers une application cliente.

delimiter

caractère qui sépare les champs dans chaque ligne du fichier.

null string

La chaîne qui représente une valeur NULL. Par défaut c'est "\N" (backslash-N). Vous pouvez préférer une chaîne vide, par exemple.

Sur un copy in, certaines données qui apparient cette chaîne seront stockées comme valeur NULL, ainsi vous devriez être sûr d'utiliser la même chaîne que vous utilisez pour copy out.

Sorties

COPY: La copie est effectuée correctement.
ERROR: reason: Copie non effectuée pour la raison indiquée dans le message d'erreur.

Description

COPY déplace les données entre les tables Postgres et les fichiers standards Unix. COPY TO copie le contenu entier d'une table vers un fichier, tandis que COPY FROM copie les données depuis un fichier vers une table.

COPY envoie l'instruction à Postgres d'écrire ou de lire vers un fichier. Le fichier doit être directement visible par le serveur et le nom doit être spécifié depuis le point de vue du serveur. Si stdin ou stdout sont spécifiés, les données passeront du client vers le serveur.

Ne confondez pas COPY avec l'instruction \copy de psql. \copy invoque COPY FROM stdin ou COPY TO stdout, et alors récupère/stocke les données dans un fichier accessible au client psql. Ainsi, l'accessibilité et les droits d'accès dépendent du client d'avantage que du serveur quand \copy est utilisé.

Notes

COPY ne peut être utilisé qu'avec des tables pleines, pas des vues.

Le mot-clé BINARY forcera toutes les données a être stockées/lues comme objets binaires plus que comme texte. C'est plus rapide que la commande copy normale, mais ce n'est généralement pas portable.

Par défaut, un copy texte utilise un caractère tab ("\t") comme délimiteur. Le délimiteur peut aussi être changé en quelque autre caractère avec la phrase USING DELIMITERS. Les caractères dans les zones d'information qui s'avèrent justement apparier le caractère de séparateur seront quotés avec des backslashes.

Vous devez avoir sélectionné des accès sur une table dont les valeurs sont lues par COPY, et soit insert soit update access vers une table dans laquelle les valeurs sont insérées par COPY. Le serveur nécessite aussi les permissions Unix appropriées pour chaque fichier lu ou écrit par COPY.

COPY TO n'invoque ni les règles ni agit sur les colonnes par défaut. Il peut invoquer des déclencheurs et des contraintes de vérification.

COPY arrête l'opération à la première erreur. Ceci ne pourrait pas conduire aux problèmes du COPY FROM, mais la relation cible aura déja reçu des lignes dans une commande COPY TO. Ces lignes ne seront pas visibles ni accessibles, mais elles peuvent toujours occuper de la place disque. Ceci peut augmenter considérablement l'espace disque de données parasites si l'erreur est apparue sur une grosse opération de copie. Vous devriez alors invoquer VACUUM pour récupérer cet espace.

Les fichiers nommés ans une commande COPY sont lus ou écrit directement par le serveur, pas par l'application cliente. Donc, elle doivent résider dans ou être accessibles par la machine serveur de la base, pas le client. Elles doivent être accessibles en lecture ou écriture par l'utilisateur PostgreSQL (l'ID utilisateur qu'utilise le serveur), pas le client. COPY désignant un fichier est uniquement permis aux superutilisateurs de la base, car il permet l'écriture sur certains fichiers dont les droits en écriture sont propres au serveur.

L'instruction \copy psql lit et écrit les fichiers sur la machine cliente avec les droits du client, ainsi elle n'est pas restreinte aux superutilisateurs.

Il est recommandé que le nom de fichier utilisé dans COPY soit toujours spécifié en tant que chemin absolu. Ceci est renforcé par le serveur en cas de COPY TO, mais pour COPY FROM vous devez avoir l'option de lecture du fichier spécifié par un chemin relatif. Le chemin sera interprété relativement au répertoire de travail du serveur (quelque part en dessous de $PGDATA), pas le répertoire de travail du client.

File Formats

Text Format

Quand COPY TO est utilisé sans l'option BINARY, le fichier généré aura chaque instance sur une seule ligne, avec chaque colonne (attribute) séparée par le caractère délimiteur. Les caractères délimiteurs intégrés seront précédés par un caractère backslash ("\"). Les valeurs attribut elles-même sont des chaînes générées par la fonction sortie associée avec chaque type attribut. La fonction sortie pour un type n'essaiera pas de générer le caractère backslash ; celui-ci sera généré par COPY lui-même.

Le format actuel pour chaque instance est

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

Notez la terminaison de chaque ligne est marquée par un saut de ligne de style Unix ("\n"). COPY FROM ne se comportera pas de cette façon si un fichier donné contient des sauts de lignes de style DOS ou Mac.

Le OID est émis comme première colonne si WITH OIDS est spécifié. (Une erreur apparaît si WITH OIDS est spécifié pour une table qui n'a pas d'OID).

Si COPY TO envoie ses résultats vers une sortie standard au lieu d'un fichier, après la dernière ligne, il sera envoyé un backslash ("\") et un point (".") suivi immédiatement par une nouvelle ligne. De façon similaire, si COPY FROM lit depuis une entrée standard, il sera attendu un backslash ("\") et un point (".") suivit par un saut de ligne, comme les trois premiers caractères sur une ligne pour noter la fin du fichier. Cependant, COPY FROM se terminera correctement (suivi par le serveur lui-même) si la connexion entrée est fermée avant que ce fin-de-fichier spécial soit trouvé.

Le caractère backslash a d'autres fonctionnalités. Un caractère backslash littéral est représenté avec deux backslashes consécutifs ("\\"). Un caractère de tabulation littéral est représenté avec un backslash et une tabulation (Si vous utilisez autre chose qu'une tabulation comme délimiteur de colonne, mettez un backslash comme caractère délimiteur pour l'inclure dans la donnée). Un caractère saut de ligne littéral est représenté par un backslash et un saut de ligne. Quand vous chargez des données texte non générées par PostgreSQL, vous devrez convertir les caractères backslash ("\") en double-backslashes ("\\") pour vous assurer qu'ils seront chargés correctement.

Format binaire

Le format de fichier utilisé pour COPY BINARY a changé depuis PostgreSQL v7.1. Le nouveau format consiste en un fichier en-tête, zero tuple ou plus, et un fichier annonce.

Fichier en-tête

Le fichier en-tête consiste en champs fixes de 24 octets, suivis par une zone en-tête de longueur variable. Les champs fixes sont :

Signature

séquence 12 octets PGBCOPY\n\377\r\n\0 --- notez que null est une partie nécessaire de la signature. (La signature est prévue pour permettre une identification facile des fichiers qui ont été tronqués par un transfert effectué sans 8bit propre. Cette signature sera changée par les filtres de traduction de saut de ligne, les null supprimés, et la parité changée).

Integer layout field

constante int32 0x01020304 dans l'ordre octet source. Potentiellement, un lecteur peut s'engager dans un saut d'octet des champs subséquents si un mauvais ordre d'octet est détecté ici.

Flags field

int32 bit mask pour noter d'importants aspects de format de fichier. Les bits sont numérotés de 0 (LSB) à 31 (MSB) --- notez que ce champ est stocké avec l'ordre des octets de la plate-forme source, comme le sont tous les champs entiers subséquents. Les bits 16-31 sont réservés pour noter les sorties de format de fichiers critiques; un lecteur échouera s'il trouve un ensemble de bits non attendu dans ce domaine. Les bits 0-15 sont réservés aux sorties de format de signal précédent-compatible; un lecteur ignorera simplement un ensemble de bits non attendus ici. Couramment, un seul bit flag est défini, le reste doit être à zero.

Bit 16: Si 1, les OID sont inclus dans l'extraction; si 0, non.

Header extension area length

longueur int32 en octet d'en-tête, non inclu lui-même. Dans la version initiale ce serait zero, et le premier tuple suit immédiatement. Des modifications futures du format pourraient permettre à des données supplémentaires d'être présentes dans l'en-tête. Un lecteur sautera sans avertissement les extensions de données dans l'en-tête.

La zone d'extension d'en-tête est envisagée pour contenir une suite d'auto-identifiants. Le champ flag n'indique pas aux lecteurs qu'il est dans la zone d'extension. La modélisation spécifique des contenus des extensions d'en-tête est laissée pour de futures versions.

Ce modèle permet les additions d'en-tête précédent-compatible (ajout d'extension d'en-têtes) et non-précédent-compatible.

Tuples

Chaque tuple commence avec un compte int16 du nombre de champs dans le tuple. (Actuellement, tous les tuples dans une table auront le même compte, mais ça peut ne pas toujours être vrai). Alors, répété pour chaque champ dans le tuple, il y a un mot-type int16 possiblement suivi par un champ de données. Le champ mot-type est interprété comme suit :

Zero: Le champ est NULL. Aucune donnée suit.
> 0: Le champ est un tpe de longueur fixe. Exactement N octets de données suivent le mot-type.
-1: Le champ est un type varlena. Les quatre octets suivants sont l'en-tête varlena, qui contient la valeur de longueur totale y compris lui-même..
< -1: Réservé pour un usage futur.

Pour les champs non-NULL, le lecteur peut vérifier que le mot-type apparie les mots-type attendus pour la colonne de destination. Ceci permet une simple mais très efficace vérification que les données sont celles qui sont attendues.

Il n'y a pas de remplissage ou autre données supplémentaires entre les champs. Notez aussi que le format ne distingue pas si un type est passé par référence ou par valeur. Ces deux dispositions sont délibérées : elles peuvent aider à l'amélioration de la portabilité des fichiers (bien que bien entendu endianness et les sorties au format décimal peuvent toujours vous permettre de déplacer un fichier binaire à travers plusieurs machines).

Si les OID sont inclus dans l'extraction, le champ OID suit immédiatement le mot compte-champ. It is a normal field except that it's not included in the field-count. In particular it has a typlen --- this will allow handling of 4-byte vs 8-byte OIDs without too much pain, and will allow OIDs to be shown as NULL if that ever proves desirable.

File Trailer

La marque de fin de fichier (file trailer) consiste en un mot int16 contenant -1. C'est facilement distinguable d'un mot compteur-de-champ d'un tuple.

Un lecteur rapportera une erreur si un mot compteur-de-champ n'est ni -1 ni le nombre de colonnes attendues. Ce qui permet une vérification suplémentaire.

Utilisation

L'exemple suivant copie une table vers une sortie standard, en utilisant une barre verticale (|) comme délimiteur de champ :

COPY country TO stdout USING DELIMITERS '|';

Pour copier des données depuis un fichier Unix dans une table country :

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

Ici un exemple de données appropriées pour la copie dans une table depuis stdin (ainsi la séquence de terminaison se situe sur la dernière ligne) :

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

Notez que l'espace blanc sur chaque ligne est une tabulation.

Les suivantes sont les mêmes données, sorties en format binaire sur une machine Linux/586. Les données sont montrées après filtrage par l'utilitaire Unix od -c. La table a trois champs; le premier est char(2), le second text, et le troisième integer. Toutes les lignes ont une valeur null dans le troisième champ.

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

<<< Previous	Home	Next >>>
COMMIT	Up	CREATE AGGREGATE