COPY

Description

COPY déplace des données entre les tables de PostgreSQL et les fichiers du système de fichiers standard. COPY TO copie le contenu d'une table dans un fichier alors que COPY FROM copie des données à partir d'un fichier dans une table (ajoutant les données à ce qui se trouve déjà dans la table).

Si une liste de colonnes est spécifiée, COPY copiera seulement les données des colonnes spécifiées vers ou à partir du fichier. S'il y a des colonnes dans la table qui ne se trouvent pas dans la liste de colonnes, COPY FROM insérera les valeurs par défaut de ces colonnes.

COPY avec un nom de fichier indique au serveur PostgreSQL de lire directement à partir d'un fichier ou d'écrire dans un fichier. Le fichier doit être accessible du serveur et le nom doit être spécifié à partir du point de vue du serveur. Lorsque STDIN ou STDOUT est indiqué, les données sont transmises via la connexion entre le client et le serveur.

Paramètres

Notes

COPY peut seulement être utilisé avec des tables réelles, pas avec des vues.

Le mot clé BINARY fait que toutes les données sont stockées/lues dans le format binaire plutôt qu'en texte. Il est un peu plus rapide que le mode texte standard mais un fichier binaire est moins portable au travers des architectures machine et des versions de PostgreSQL.

Vous devez avoir le droit SELECT sur la table dont les valeurs sont lues par COPY TO et le droit INSERT sur la table dont les valeurs sont insérées par COPY FROM.

Les fichiers nommés dans une commande COPY sont lus ou écrits directement par le serveur, et non pas par l'application cliente. Du coup, ils doivent résider ou être accessible par la machine du serveur de bases de données. Ils doivent être accessibles et lisibles ou modifiables par l'utilisateur PostgreSQL (l'identifiant de l'utilisateur qui a exécuté le serveur), et non pas par le client. COPY nommant un fichier est seulement autorisé pour les superutilisateurs de la base de données car il autorise la lecture ou l'écriture de tout fichier auquel a accès le serveur.

Ne confondez pas COPY avec l'instruction \copy de psql. \copy appelle COPY FROM STDIN ou COPY TO STDOUT, puis récupère/stocke la donnée dans un fichier accessible au client psql. Du coup, l'accès au fichier et les droits d'accès dépendent du client plutôt que du serveur quand \copy est utilisé.

Il est recommandé que le nom du fichier utilisé dans COPY soit toujours utilisé avec un chemin absolu. Ceci est renforcé par le serveur dans le cas d'un COPY TO mais, pour les COPY FROM, vous devez avoir l'option de lire à partir d'un fichier spécifié par un chemin relatif. Le chemin sera interprété de façon relative au répertoire de travail du processus serveur (quelque part en-dessous du répertoire de données), pas dans le répertoire de travail du client.

COPY FROM appellera tout déclencheur et vérifiera les contraintes sur la table de destination. Néanmoins, il n'appellera pas les règles.

COPY stoppe l'opération à la première erreur. Ceci ne devrait apporter aucun problème dans le cas d'un COPY TO mais la table cible aura déjà reçu des lignes précédentes dans un COPY FROM. Ces lignes ne seront pas visibles ou accessibles mais elle occuperont toujours de l'espace disque. Ceci pourrait totaliser une perte considérable d'espace disque si l'échec arrivait lors d'une grande opération de copie. Vous pourriez souhaiter appeler VACUUM pour récupérer l'espace perdu.

Formats de fichiers

Exemples

L'exemple suivant copie une table vers le client en utilisant la barre verticale (|) comme délimiteur de champ :

COPY pays TO STDOUT WITH DELIMITER '|';

Pour copier des données de la table pays vers un fichier :

COPY pays FROM '/usr1/proj/bray/sql/pays_donnees';

Voici un exemple de données convenable pour une table provenant de STDIN :

AF      AFGHANISTAN
AL      ALBANIA
DZ      ALGERIA
ZM      ZAMBIA
ZW      ZIMBABWE

Notez que l'espace blanc sur chaque ligne est en fait un caractère de tabulation.

Ce qui suit représente les même données, au format binaire. La donnée est affichée après filtrage à travers l'outil Unix od -c. La table a trois colonnes ; la première est de type integer. Toutes les lignes ont une valeur NULL sur la troisième colonne.

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

Compatibilité

Il n'existe pas d'instruction COPY dans le standard SQL.

La syntaxe suivante était utilisée avant PostgreSQL version 7.3 et est toujours supportée :

COPY [ BINARY ] nomtable [ WITH OIDS ]
    FROM { 'nomfichier' | STDIN }
    [ [USING] DELIMITERS 'délimiteur' ]
    [ WITH NULL AS 'chaîne NULL' ]

COPY [ BINARY ] nomtable [ WITH OIDS ]
    TO { 'nomfichier' | STDOUT }
    [ [USING] DELIMITERS 'délimiteur' ]
    [ WITH NULL AS 'chaîne NULL' ]