COPY — Copier des données depuis/vers un fichier vers/depuis une table
COPYnom_table
[ (nom_colonne
[, ...] ) ] FROM { 'nom_fichier
' | PROGRAM 'commande
' | STDIN } [ [ WITH ] (option
[, ...] ) ] [ WHEREcondition
] COPY {nom_table
[ (nom_colonne
[, ...] ) ] | (requête
) } TO { 'nom_fichier
' | PROGRAM 'commande
' | STDOUT } [ [ WITH ] (option
[, ...] ) ] oùoption
fait partie de : FORMATnom_format
FREEZE [booléen
] DELIMITER 'caractère_délimiteur
' NULL 'chaîne_null
' DEFAULT 'chaîne_par_défaut
' HEADER [boolean
| MATCH ] QUOTE 'caractère_guillemet
' ESCAPE 'caractère_échappement
' FORCE_QUOTE { (nom_colonne
[, ...] ) | * } FORCE_NOT_NULL (nom_colonne
[, ...] ) FORCE_NULL (nom_colonne
[, ...] ) ENCODING 'nom_encodage
'
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 28.4.3 pour les détails.
nom_table
Le nom de la table (éventuellement qualifié du nom du schéma).
nom_colonne
Une liste optionnelle de colonnes à copier. Sans précision, toutes les colonnes de la table seront copiées.
requête
Une commande SELECT
,
VALUES
,
INSERT
,
UPDATE
, ou
DELETE
dont les
résultats sont à copier.
Notez que des parenthèses sont requises autour de la requête.
Pour les requêtes INSERT
, UPDATE
et
DELETE
, une clause RETURNING
doit
être fournie, et
la relation cible ne doit avoir ni règle conditionnelle, ni règle
ALSO
, ni règle INSTEAD
qui
ajoute plusieurs requêtes.
nom_fichier
Le chemin vers le fichier en entrée ou en sortie. Un nom de fichier en
entrée peut avoir un chemin absolu ou relatif mais un nom de fichier en
sortie doit absolument avoir un chemin absolu. Les utilisateurs Windows
peuvent avoir besoin d'utiliser la syntaxe E''
et de
doubler tous les antislashs utilisés dans le nom du chemin.
PROGRAM
Une commande à exécuter. Avec COPY FROM
, l'entrée est
lue de la sortie standard de la commande alors qu'avec COPY
TO
, la sortie est écrite dans l'entrée standard de la commande.
Notez que la commande est appelée par le shell. Si vous avez besoin de passer des arguments qui viennent d'une source sans confiance, vous devez faire particulièrement attention à supprimer ou échapper tous les caractères spéciaux qui pourraient avoir une signification particulière pour le shell. Pour des raisons de sécurité, il est préférable d'utiliser une chaîne de commande fixe ou, tout du moins, d'éviter d'inclure une entrée utilisateur.
STDIN
Les données en entrée proviennent de l'application cliente.
STDOUT
Les données en sortie vont sur l'application cliente.
boolean
Spécifie si l'option sélectionnée doit être activée ou non. Vous pouvez
écrire TRUE
, ON
ou
1
pour activer l'option, et FALSE
,
OFF
ou 0
pour la désactiver. La
valeur boolean
peut aussi
être omise, auquel cas la valeur TRUE
est prise en
compte.
FORMAT
Sélectionne le format des données pour la lecture ou l'écriture :
text
,
csv
(valeurs séparées par des virgules),
ou binary
.
la valeur par défaut est text
.
FREEZE
Demande la copie des données dans des lignes déjà gelées (donc dans le même
état qu'après un VACUUM FREEZE
). Ceci est une option de
performance pour un chargement initial des données. Les lignes seront
gelées seulement si la table en cours de chargement a été créée ou
tronquée dans la même sous-transaction, qu'il n'y a pas de curseurs ouverts
ou d'anciennes images de la base de données détenus par cette transaction.
Il n'est actuellement pas possible de réaliser un COPY FREEZE
sur une table partitionnée.
Notez que toutes les autres sessions seront immédiatement capables de voir les données une fois qu'elles auront été chargées. Ceci viole les règles habituelles de la visibilité d'après MVCC. Les utilisateurs intéressées par cette option doivent être conscients des problèmes potentiels que cela peut poser.
DELIMITER
Spécifie le caractère qui sépare les colonnes sur chaque ligne du
fichier. La valeur par défaut est une tabulation dans le format texte et
une virgule dans le format CSV
. Il doit être un
seul caractère sur un seul octet. Cette option n'est pas autorisée lors
de l'utilisation du format binary
.
NULL
Spécifie la chaîne qui représente une valeur NULL. La valeur par défaut
est \N
(antislash-N) dans le format texte et une
chaîne vide sans guillemets dans le format CSV
. Vous
pouvez préférer une chaîne vide même dans le format texte pour les cas
où vous ne voulez pas distinguer les valeurs NULL des chaînes vides.
Cette option n'est pas autorisée lors de l'utilisation du format
binary
.
Lors de l'utilisation de COPY FROM
, tout élément de données
qui correspond à cette chaîne est stocké comme valeur NULL. Il est donc utile
de s'assurer que c'est la même chaîne que celle précisée pour le
COPY TO
qui est utilisée.
DEFAULT
Indique la chaîne représentant une valeur par défaut. Chaque fois que la
chaîne est trouvée dans le fichier en entrée, la valeur par défaut de la
colonne correspondante sera utilisée. Cette option est seulement autorisée
dans COPY FROM
et uniquement quand le format
binary
n'est pas utilisé.
HEADER
Le fichier contient une ligne d'en-tête avec les noms de chaque colonne.
En sortie, la première ligne contient les noms de colonne de la table. En
entrée, la première ligne est ignorée quand cette option vaut
true
(ou une valeur booléenne équivalente). Si cette
option vaut MATCH
, le nombre et les noms des colonnes
de la ligne d'en-tête doivent correspondre aux noms des colonnes de la
table, dans l'ordre. Dans le cas contre, une erreur est renvoyée. Cette
option n'est pas autorisée avec le format binary
.
L'option MATCH
est uniquement valide pour les commandes
COPY FROM
.
QUOTE
Spécifie le caractère guillemet à utiliser lorsqu'une valeur doit être
entre guillemets. Par défaut, il s'agit du guillemet double. Cela doit
de toute façon être un seul caractère sur un seul octet. Cette option
n'est autorisée que lors de l'utilisation du format
CSV
.
ESCAPE
Spécifie le caractère qui doit apparaître avant un caractère de données
qui correspond à la valeur QUOTE
. La valeur par
défaut est la même que la valeur QUOTE
(du coup,
le caractère guillemet est doublé s'il apparaît dans les données). Cela
doit être un seul caractère codé en un seul octet. Cette option n'est
autorisée que lors de l'utilisation du format CSV
.
FORCE_QUOTE
Force l'utilisation des guillemets pour toutes les valeurs non
NULL
dans chaque colonne spécifiée. La sortie
NULL
n'est jamais entre guillemets. Si
*
est indiqué, les valeurs non NULL
seront entre guillemets pour toutes les colonnes. Cette option est
seulement autorisée avec COPY TO
et seulement quand
le format CSV
est utilisé.
FORCE_NOT_NULL
Ne fait pas correspondre les valeurs des colonnes spécifiées avec la
chaîne nulle. Dans le cas par défaut où la chaîne nulle est vide, cela
signifie que les valeurs vides seront lues comme des chaînes de longueur
nulle plutôt que comme des NULL, même si elles ne sont pas entre
guillemets. Cette option est seulement autorisée avec COPY
FROM
et seulement quand le format CSV
est
utilisé.
FORCE_NULL
Essaie d'établir une correspondance entre les valeurs des colonnes
spécifiées avec la chaîne NULL, même si elle est entre guillemets.
Si une correspondance est trouvée, configure la valeur à
NULL
. Dans le cas par défaut où la chaîne NULL est
vide, cela convertit une chaîne vide entre guillemets en valeur
NULL. Cette option est uniquement autorisée avec COPY
FROM
, et seulement avec le format CSV
.
ENCODING
Spécifie que le fichier est dans l'encodage nom_encodage
. Si cette option est omise,
l'encodage client par défaut est utilisé. Voir la partie Notes ci-dessous
pour plus de détails.
WHERE
La clause optionnelle WHERE
a la forme générale
WHERE condition
La condition
where est
une expression qui, évaluée ramènera un résultat de type booléen
.
Toutes les lignes qui ne valident pas la condition ne seront
pas insérées dans la table.
On considère qu'une ligne qui valide la condition est une ligne qui renvoie
true lorsque la valeur réelle dans la table est comparée avec la condition.
Pour le moment, les sous requêtes ne sont pas autorisées dans
l'expression du WHERE
, et l'évaluation ne verra
pas les changements réalisés par la commande COPY
elle même.
(Cela a son importance lorsque l'expression utilisée contient des appels à
des fonctions VOLATILE
)
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.
psql affichera cette balise de commande seulement
si la commande n'est pas COPY ... TO STDOUT
ou son équivalent
sous psql (la méta-commande
\copy ... to stdout
). Ceci a pour but d'empêcher toute
confusion entre la balise de commande et les données affichées.
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
copie les mêmes lignes
que table
TOSELECT * FROM ONLY
. La syntaxe table
COPY
(SELECT * FROM
peut être utilisé pour sauvegarder toutes les lignes dans une
hiérarchie d'héritage, dans une table partitionnée, ou une vue.
table
) TO
...
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
. Actuellement, table
TOCOPY 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.
COPY
stoppe l'opération à la première erreur. Si cela ne
porte pas à conséquence dans le cas d'un COPY TO
, il en va
différemment dans le cas d'un COPY FROM
. Dans ce cas, la table cible
a déjà reçu les lignes précédentes. Ces lignes ne sont ni visibles, ni accessibles,
mais occupent de l'espace disque. Il peut en résulter une perte importante
d'espace disque si l'échec se produit lors d'une copie volumineuse.
L'espace perdu peut alors être récupéré avec la commande VACUUM
.
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.
Quand le format text
est utilisé, les données sont lues
ou écrites dans un
fichier texte, chaque ligne correspondant à une ligne de la table. Les colonnes
sont séparées, dans une ligne, par le caractère de délimitation. Les valeurs
des colonnes sont des chaînes, engendrées par la fonction de sortie ou utilisables
par celle d'entrée, correspondant au type de données des attributs. La chaîne
de spécification des valeurs NULL est utilisée en lieu et place des valeurs nulles.
COPY FROM
lève une erreur si une ligne du fichier ne contient
pas le nombre de colonnes attendues.
La fin des données peut être représentée par une ligne ne contenant
qu'un antislash et un point (\.
). Ce marqueur de fin de
données n'est pas nécessaire lors de la lecture d'un fichier, la fin du
fichier tenant ce rôle. Il n'est réellement nécessaire que lors d'une copie de
données vers ou depuis une application cliente qui utilise un protocole
client antérieur au 3.0.
Les caractères antislash (\
) peuvent être utilisés dans les
données de COPY
pour échapper les caractères qui,
sans cela, seraient considérés comme des délimiteurs de ligne ou de
colonne. Les caractères suivants, en particulier, doivent être
précédés d'un antislash s'ils apparaissent dans la
valeur d'une colonne : l'antislash lui-même, le saut de ligne, le retour
chariot et le délimiteur courant.
La chaîne NULL spécifiée est envoyée par COPY TO
sans
ajout d'antislash ; au contraire, COPY FROM
teste l'entrée au regard de la chaîne NULL avant la suppression des antislash.
Ainsi, une chaîne NULL telle que \N
ne peut pas être
confondue avec la valeur de donnée réelle \N
(représentée dans ce cas par \\N
).
Les séquences spéciales suivantes sont reconnues par COPY FROM
:
Séquence | Représente |
---|---|
\b | Retour arrière (backspace) (ASCII 8) |
\f | Retour chariot (ASCII 12) |
\n | Nouvelle ligne (ASCII 10) |
\r | Retour chariot (ASCII 13) |
\t | Tabulation (ASCII 9) |
\v | Tabulation verticale (ASCII 11) |
\ chiffres | Antislash suivi d'un à trois chiffres en octal représente l'octet qui possède ce code numérique |
\x digits | Antislash x suivi d'un ou deux chiffres hexadécimaux
représente l'octet qui possède ce code numérique |
Actuellement, COPY TO
n'émet pas de séquence
octale ou hexadécimale mais utilise les autres séquences listées
ci-dessus pour les caractères de contrôle.
Tout autre caractère précédé d'un antislash se représente lui-même.
Cependant, il faut faire attention à ne pas ajouter d'antislash
qui ne soit pas absolument nécessaire afin d'éviter le risque
d'obtenir accidentellement une correspondance avec
le marqueur de fin de données (\.
) ou la chaîne NULL
(\N
par défaut) ; ces chaînes sont reconnues avant tout
traitement des antislashs.
Il est fortement recommandé que les applications qui engendrent des
données COPY
convertissent les données de nouvelle ligne
et de retour chariot par les séquences respectives \n
et \r
.
A l'heure actuelle, il est possible de représenter un retour chariot par
un antislash et un retour chariot, et une nouvelle ligne par un antislash
et une nouvelle ligne. Cependant, il n'est pas certain que ces représentations
soient encore acceptées dans les prochaines versions. Celles-ci sont, de plus,
extrêmement sensibles à la corruption si le fichier de COPY
est transféré sur d'autres plateformes (d'un Unix vers un Windows ou inversement, par exemple).
Toutes les séquences avec antislash sont interprétées après la conversion d'encodage. Les octets indiquées avec des séquences octales ou hexadécimales doivent former des caractères valides dans l'encodage de la base.
COPY TO
termine chaque ligne par une
nouvelle ligne de style Unix (« \n
»). Les serveurs
fonctionnant sous Microsoft Windows engendrent un retour chariot/nouvelle ligne
(« \r\n
»), mais uniquement lorsque
les données engendrées par COPY
sont envoyées dans un
fichier sur le serveur.
Pour des raisons de cohérence entre les
plateformes, COPY TO STDOUT
envoie toujours
« \n
» quelque soit la plateforme du serveur.
COPY FROM
sait gérer les lignes terminant par une nouvelle
ligne, un retour chariot ou un retour chariot suivi d'une nouvelle ligne.
Afin de réduire les risques d'erreurs engendrées par des nouvelles lignes
ou des retours chariot non précédés d'antislash, considéré de fait comme
des données, COPY FROM
émet un avertissement si les
fins de lignes ne sont pas toutes identiques.
Ce format est utilisé pour importer et exporter des données au format
de fichier CSV
(acronyme de
Comma Separated Value, littéralement
valeurs séparées par des virgules). Ce format est utilisé par un grand nombre de
programmes, tels les tableurs. À la place des règles d'échappement utilisées par le format
texte standard de PostgreSQL, il produit et
reconnaît le mécanisme d'échappement habituel de CSV
.
Les valeurs de chaque enregistrement sont séparées par le caractère
DELIMITER
. Si la valeur contient ce caractère, le caractère
QUOTE
, la chaîne NULL
, un retour chariot
ou un saut de ligne, la valeur complète est préfixée et suffixée
par le caractère QUOTE
. De plus, toute occurrence du caractère
QUOTE
ou du caractère ESCAPE
est précédée du
caractère d'échappement. FORCE QUOTE
peut également être utilisé
pour forcer les guillemets lors de l'affichage de valeur non-NULL dans
des colonnes spécifiques.
Le format CSV
n'a pas de façon standard de distinguer
une valeur NULL
d'une chaîne vide. La commande COPY
de PostgreSQL gère cela avec les guillemets. Un
NULL
est affiché suivant le paramètre NULL
et n'est pas entre guillemets, alors qu'une valeur non NULL
correspondant au paramètre NULL
est entre guillemets. Par
exemple, avec la configuration par défaut, un NULL
est
écrit avec la chaîne vide sans guillemets alors qu'une chaîne vide est écrit
avec des guillemets doubles (""
). La lecture des valeurs
suit des règles similaires. Vous pouvez utiliser FORCE NOT
NULL
pour empêcher les comparaisons d'entrée NULL
pour des colonnes spécifiques. Vous pouvez aussi utiliser
FORCE_NULL
pour convertir des valeurs de chaînes NULL
entre guillemets en NULL
.
L'antislash n'est pas un caractère spécial dans le format CSV
.
De ce fait, le marqueur de fin de données, \.
, peut apparaître
dans les donnée. Afin d'éviter toute mauvaise interprétation, une valeur \.
qui apparaît seule sur une ligne est automatiquement placée
entre guillemets en sortie. En entrée, si elle est entre guillemets, elle
n'est pas interprétée comme un marqueur de fin de données.
Lors du chargement d'un fichier qui ne contient qu'une colonne, dont les valeurs ne sont pas placées entre
guillemets, créé par une autre application, qui contient une valeur
\.
, il est nécessaire de placer cette valeur entre guillemets.
Dans le format CSV
, tous les caractères sont significatifs.
Une valeur entre guillemets entourée d'espaces ou de tout
autre caractère différent de DELIMITER
inclut ces caractères.
Cela peut être source d'erreurs en cas d'import de données à partir d'un système
qui complète les lignes CSV
avec des espaces fines pour
atteindre une longueur fixée. Dans ce cas, il est nécessaire de pré-traiter
le fichier CSV
afin de supprimer les espaces de complètement
avant d'insérer les données dans PostgreSQL.
Le format CSV
sait reconnaître et produire des fichiers
CSV
dont les valeurs entre
guillemets contiennent des retours chariot et des sauts de ligne. De ce fait,
les fichiers ne contiennent pas strictement une ligne par ligne de table comme
les fichiers du format texte.
Beaucoup de programmes produisent des fichiers CSV
étranges et parfois pervers ;
le format de fichier est donc plus une convention qu'un standard.
Il est alors possible de rencontrer des fichiers que ce mécanisme ne sait
pas importer. De plus, COPY
peut produire des fichiers
inutilisables par d'autres programmes.
Le format binary
fait que toutes les données sont
stockées/lues au format binaire plutôt que texte. Il est un peu plus
rapide que les formats texte et CSV
mais un fichier au
format binaire est moins portable suivant les architectures des machines
et les versions de PostgreSQL. De plus, le
format binaire est très spécifique au type des données ; par exemple,
un export de données binaires d'une colonne smallint
ne
pourra pas être importé dans une colonne integer
, même si
cela aurait fonctionné dans le format texte.
Le format de fichier binary
consiste en un en-tête de
fichier, zéro ou plusieurs lignes contenant les données de la ligne et
un bas-de-page du fichier. Les en-têtes et les données sont dans l'ordre
réseau des octets.
Les versions de PostgreSQL antérieures à la 7.4 utilisaient un format de fichier binaire différent.
L'en-tête du fichier est constitutée de 15 octets de champs fixes, suivis par une aire d'extension de l'en-tête de longueur variable. Les champs fixes sont :
séquence de 11 octets PGCOPY\n\377\r\n\0
--
l'octet zéro est une partie obligatoire de la signature. La signature est
conçue pour permettre une identification aisée des fichiers qui ont été
détériorés par un transfert non respectueux des huit bits. Cette
signature est modifiée par les filtres de traduction de fin de ligne,
la suppression des octets zéro, la suppression des bits de poids forts ou
la modification de la parité.
masque entier de 32 bits décrivant les aspects importants du format de fichier. Les bits sont numérotés de 0 (LSB, ou Least Significant Bit, bit de poids faible) à 31 (MSB, ou Most Significant Bit, bit de poids fort). Ce champ est stocké dans l'ordre réseau des octets (l'octet le plus significatif en premier), comme le sont tous les champs entier utilisés dans le format de fichier. Les bits 16 à 31 sont réservés aux problèmes critiques de format de fichier ; tout lecteur devrait annuler l'opération s'il trouve un bit inattendu dans cet ensemble. Les bits 0 à 15 sont réservés pour signaler les problèmes de compatibilité de formats ; un lecteur devrait simplement ignorer les bits inattendus dans cet ensemble. Actuellement, seul un bit est défini, le reste doit être à zéro :
si 1, les OID sont inclus dans la donnée ; si 0, non. Les colonnes système OID ne sont plus supportées dans PostgreSQL mais le format contient toujours l'indicateur.
entier sur 32 bits, longueur en octets du reste de l'en-tête, octets de stockage de la longueur non-compris. À l'heure actuelle ce champ vaut zéro. La première ligne suit immédiatement. De futures modifications du format pourraient permettre la présence de données supplémentaires dans l'en-tête. Tout lecteur devrait ignorer silencieusement toute donnée de l'extension de l'en-tête qu'il ne saurait pas traiter.
L'aire d'extension de l'en-tête est prévue pour contenir une séquence de morceaux s'auto-identifiant. Le champ de commutateurs n'a pas pour but d'indiquer aux lecteurs ce qui se trouve dans l'aire d'extension. La conception spécifique du contenu de l'extension de l'en-tête est pour une prochaine version.
Cette conception permet l'ajout d'en-têtes compatible (ajout de morceaux d'extension d'en-tête, ou initialisation des octets commutateurs de poids faible) et les modifications non compatibles (initialisation des octets commutateurs de poids fort pour signaler de telles modifications, et ajout des données de support dans l'aire d'extension si nécessaire).
Chaque tuple débute par un compteur, entier codé sur 16 bits, représentant le nombre de champs du tuple. (Actuellement, tous les tuples d'une table ont le même compteur, mais il est probable que cela ne soit pas toujours le cas.) On trouve ensuite, répété pour chaque champ du tuple, un mot de 32 bits annonçant le nombre d'octets de stockage de la donnée qui suivent. (Ce mot n'inclut pas sa longueur propre et peut donc être nul.) -1, cas spécial, indique une valeur de champ NULL. Dans ce cas, aucun octet de valeur ne suit.
Il n'y a ni complètement d'alignement ni toute autre donnée supplémentaire entre les champs.
Actuellement, toutes les valeurs d'un fichier d'un format binaire sont supposées être dans un format binaire (code de format). Il est probable qu'une extension future ajoute un champ d'en-tête autorisant la spécification de codes de format par colonne.
La consultation du code source de PostgreSQL, et en
particulier les fonctions *send
et *recv
associées à chaque type de données de la colonne,
permet de déterminer le format binaire approprié à la donnée réelle.
Ces fonctions se situent dans le répertoire src/backend/utils/adt/
des
sources.
Lorsque les OID sont inclus dans le fichier, le champ OID suit immédiatement le compteur de champ. C'est un champ normal, à ceci près qu'il n'est pas inclus dans le compteur. Notez que les colonnes système OID ne sont pas supportées dans la version courante de PostgreSQL.
La fin du fichier consiste en un entier sur 16 bits contenant -1. Cela permet de le distinguer aisément du compteur de champs d'un tuple.
Il est souhaitable que le lecteur rapporte une erreur si le mot compteur de champ ne vaut ni -1 ni le nombre attendu de colonnes. Cela assure une vérification supplémentaire d'une éventuelle désynchronisation d'avec les données.
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
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 :
COPYnomtable
[ (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 NULLcolonne
[, ...] ] ] ] 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 QUOTEcolonne
[, ...] | * } ] ] ]
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
' ]