Description

COPY transfère 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 vers un fichier tandis que COPY FROM copie des données depuis un fichier vers une table (ajoutant les données à celles déjà présentes dans la table). COPY TO peut aussi copier le résultat d'une requête SELECT.

Si une liste de colonnes est indiquée, COPY TO copie seulement les données des colonnes spécifiées dans le fichier. Pour COPY FROM, chaque champ du fichier est inséré, dans l'ordre, dans la colonne spécifiée. Les colonnes de la table non spécifiées dans la liste de colonnes de COPY FROM recevront leur valeur par défaut.

La commande COPY avec un nom de fichier force PostgreSQL à lire ou écrire directement dans un fichier. Il doit être accessible par l'utilisateur PostgreSQL (l'utilisateur exécutant le serveur) et le nom doit être spécifié du point de vue du serveur. Quand PROGRAM est indiqué, le serveur exécute la commande donnée, et lit la sortie standard du programme ou écrit dans l'entrée standard du programme. La commande doit être spécifiée du point de vue du serveur, et être exécutable par l'utilisateur PostgreSQL. Si STDIN ou STDOUT est indiqué, les données sont transmises au travers de la connexion entre le client et le serveur.

Chaque processus exécutant COPY indiquera sa progression dans la vue pg_stat_progress_copy. Voir Section 27.4.3 pour les détails.

Par défaut, COPY échouera s'il rencontre une erreur lors du traitement. Pour les cas où une tentative au mieux du chargement d'un fichier entier est souhaité, la clause ON_ERROR peut être utilisé pour proposer un autre comportement.

Paramètres

Affichage

En cas de succès, une commande COPY renvoie une balise de la forme

COPY nombre
   

Le nombre correspond au nombre de lignes copiées.

Notes

COPY TO ne peut être utilisé qu'avec des tables réelles, pas avec des vues, et ne peut pas copier les lignes des tables enfants ou des partitions enfants. Par exemple, COPY table TO copie les mêmes lignes que SELECT * FROM ONLY table. La syntaxe COPY (SELECT * FROM table) TO ... peut être utilisé pour sauvegarder toutes les lignes dans une hiérarchie d'héritage, dans une table partitionnée, ou une vue.

COPY FROM peut être utilisée avec une table standard et avec des vues ayant des triggers INSTEAD OF INSERT.

Le droit SELECT est requis 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. Il est suffisant d'avoir des droits sur les colonnes listées dans la commande.

Si la sécurité de niveau ligne est activée pour la table, les politiques SELECT associées seront exécutées pour les instructions COPY table TO. Actuellement, COPY FROM n'est pas supporté pour les tables ayant une sécurité au niveau ligne. Utilisez les instructions INSERT équivalentes à la place.

Les fichiers nommés dans une commande COPY sont lus ou écrits directement par le serveur, non par l'application cliente. De ce fait, la machine hébergeant le serveur de bases de données doit les héberger ou pouvoir y accéder. L'utilisateur PostgreSQL (l'identifiant de l'utilisateur qui exécute le serveur), et non pas le client, doit pouvoir y accéder et les lire ou les modifier. De la même façon, la commande qui utilise PROGRAM est exécutée directement par le serveur, et non pas par l'application cliente. Elle doit être exécutable par l'utilisateur PostgreSQL. L'utilisation de COPY avec un fichier n'est autorisé qu'aux superutilisateurs de la base de données ou aux utilisateurs membres des rôles pg_read_server_files, pg_write_server_files ou pg_execute_server_program car COPY autorise la lecture et l'écriture de tout fichier accessible au serveur.

Il ne faut pas confondre COPY et l'instruction \copy de psql. \copy appelle COPY FROM STDIN ou COPY TO STDOUT, puis lit/stocke les données dans un fichier accessible au client psql. L'accès au fichier et les droits d'accès dépendent alors du client et non du serveur.

Il est recommandé que le chemin absolu du fichier utilisé dans COPY soit toujours précisé. Ceci est assuré par le serveur dans le cas d'un COPY TO mais, pour les COPY FROM, il est possible de lire un fichier spécifié par un chemin relatif. Le chemin est interprété relativement au répertoire de travail du processus serveur (habituellement dans le répertoire des données), pas par rapport au répertoire de travail du client.

Exécuter une commande avec PROGRAM peut être restreint par des mécanismes de contrôle d'accès du système d'exploitation, comme par exemple SELinux.

COPY FROM appelle tous les triggers et contraintes de vérification sur la table de destination, mais pas les règles.

Pour les colonnes d'identité, la commande COPY FROM écrira toujours les valeurs des colonnes fournies dans les données en entrée, comme l'option INSERT pour OVERRIDING SYSTEM VALUE.

L'entrée et la sortie de COPY sont sensibles à datestyle. Pour assurer la portabilité vers d'autres installations de PostgreSQL qui éventuellement utilisent des paramétrages datestyle différents de ceux par défaut, il est préférable de configurer datestyle en ISO avant d'utiliser COPY TO. Éviter d'exporter les données avec le IntervalStyle configuré à sql_standard est aussi une bonne idée car les valeurs négatives d'intervalles pourraient être mal interprétées par un serveur qui a une autre configuration pour IntervalStyle.

Les données en entrée sont interprétées suivant la clause ENCODING ou suivant l'encodage actuel du client. Les données en sortie sont codées suivant la clause ENCODING ou suivant l'encodage actuel du client. Ceci est valable même si les données ne passent pas par le client, c'est-à-dire si elles sont lues et écrites directement sur un fichier du serveur.

La commande COPY FROM insère physiquement les lignes en entrée dans la table au fur et à mesure de sa progression. Si la commande échoue, ces lignes sont laissées dans un état supprimées ; ces lignes ne sont pas visibles mais occupent néanmoins de la place sur le disque. Cela pourrait finir par perdre un espace disque considérable si l'échec survenait tard dans une grosse opération de copie. VACUUM devrait être utilisé pour récupérer l'espace.

FORCE_NULL et FORCE_NOT_NULL peuvent être utilisés simultanément sur la même colonne. Cela a pour résultat la conversion des chaînes NULL entre guillemets en valeurs NULL et la conversion de chaînes NULL sans guillemets en chaînes vides.

Les données en entrée sont interprétées suivant l'encodage actuel du client et les données en sortie sont encodées suivant l'encodage client même si les données ne passent pas par le client mais sont lues à partir d'un fichier ou écrites dans un fichier.

Formats de fichiers

Exemples

Copier une table vers le client en utilisant la barre verticale (|) comme délimiteur de champ :

COPY pays TO STDOUT (DELIMITER '|');
   

Copier des données d'un fichier vers la table pays :

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

Pour copier dans un fichier les pays dont le nom commence par 'A' :

COPY (SELECT * FROM pays WHERE nom_pays LIKE 'A%') TO '/usr1/proj/bray/sql/une_liste_de_pays.copy';
   

Pour copier dans un fichier compressé, vous pouvez envoyer la sortie à un programme de compression externe :

COPY pays TO PROGRAM 'gzip > /usr1/proj/bray/sql/donnees_pays.gz';
   

Exemple de données convenables pour une copie vers une table depuis STDIN :

AF      AFGHANISTAN
AL      ALBANIE
DZ      ALGERIE
ZM      ZAMBIE
ZW      ZIMBABWE
   

L'espace sur chaque ligne est en fait un caractère de tabulation.

Les mêmes données, extraites au format binaire. Les données sont affichées après filtrage au travers de l'outil Unix od -c. La table a trois colonnes ; la première est de type char(2), la deuxième de type text et la troisième 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   E 377 377 377 377  \0 003  \0  \0  \0 002   D   Z  \0  \0  \0
0000120 007   A   L   G   E   R   I   E 377 377 377 377  \0 003  \0  \0
0000140  \0 002   Z   M  \0  \0  \0 006   Z   A   M   B   I   E 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 9.0 et est toujours supportée :

COPY nomtable [ ( colonne [, ...] ) ]
    FROM { 'nomfichier' | STDIN }
    [ [ WITH ]
        [ BINARY ]
	[ DELIMITER [ AS ] 'caractère_délimiteur' ]
	[ NULL [ AS ] 'chaîne NULL' ]
	[ CSV [ HEADER ]
	      [ QUOTE [ AS ] 'caractère_guillemet' ]
	      [ ESCAPE [ AS ] 'caractère_échappement' ]
	      [ FORCE NOT NULL colonne [, ...] ] ] ]

COPY { nomtable [ ( colonne [, ...] ) ] | ( requête ) }
    TO { 'nomfichier' | STDOUT }
    [ [ WITH ]
        [ BINARY ]
	[ DELIMITER [ AS ] 'caractère_délimiteur' ]
	[ NULL [ AS ] 'chaîne NULL' ]
	[ CSV [ HEADER ]
	      [ QUOTE [ AS ] 'caractère_guillemet' ]
	      [ ESCAPE [ AS ] 'caractère_échappement' ]
	      [ FORCE QUOTE colonne [, ...] | * } ] ] ]
   

Notez que, dans cette syntaxe, BINARY et CSV sont traités comme des mots-clés indépendants, pas comme des arguments à l'option FORMAT.

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

COPY [ BINARY ] nom_table
    FROM { 'nom_fichier' | STDIN }
    [ [USING] DELIMITERS 'caractère_délimiteur' ]
    [ WITH NULL AS 'chaîne NULL' ]

COPY [ BINARY ] nom_table
    TO { 'nom_fichier' | STDOUT }
    [ [USING] DELIMITERS 'caractère_délimiteur' ]
    [ WITH NULL AS 'chaîne NULL' ]
   

Voir aussi