| PostgreSQL: Das Offizielle Handbuch | ||||
|---|---|---|---|---|
| Zurück | Schnell zurück | Schnell nach vorne | Nach vorne | |
COPY tabelle [ ( spalte [, ...] ) ]
FROM { 'dateiname' | STDIN }
[ [ WITH ]
[ BINARY ]
[ OIDS ]
[ DELIMITER [ AS ] 'trennzeichen' ]
[ NULL [ AS ] 'null_darstellung' ] ]
COPY tabelle [ ( spalte [, ...] ) ]
TO { 'dateiname' | STDOUT }
[ [ WITH ]
[ BINARY ]
[ OIDS ]
[ DELIMITER [ AS ] 'trennzeichen' ]
[ NULL [ AS ] 'null_darstellung' ] ]COPY kopiert Daten zwischen PostgreSQL-Tabellen und normalen Dateien im Dateisystem. COPY TO kopiert den Inhalt einer Tabelle in eine Datei, COPY FROM kopiert Daten aus einer Datei in eine Tabelle (wo die Daten angehängt werden, wenn schon Daten in der Tabelle sind).
Wenn eine Spaltenliste angegeben ist, dann kopiert COPY nur die Daten in den angegebenen Spalten in oder aus der Datei. Wenn es Spalten in der Tabelle gibt, die nicht in der Spaltenliste stehen, dann wird COPY FROM in diese Spalten die Vorgabewerte einfügen.
Bei COPY mit Dateiname liest oder schreibt der PostgreSQL-Server direkt in einer Datei. Diese Datei muss vom Servers aus zugänglich sein und der Dateiname muss vom Gesichtspunkt des Servers aus angegeben sein. Wenn STDIN oder STDOUT angegeben wurden, dann fließen die Daten über den Client an den Server.
Der Name einer bestehenden Tabelle (möglicherweise mit Schemaqualifikation).
Eine optionale Liste mit den zu kopierenden Spalten. Wenn keine Spaltenliste angegeben ist, dann werden alle Spalten verwendet.
Der absolute Dateiname der Eingabe- oder Ausgabedatei.
Gibt an, dass die Eingabe von der Clientanwendung kommt.
Gibt an, dass die Ausgabe an die Clientanwendung geht.
Schreibt bzw. liest alle Daten im binären Format anstatt im Textformat. Die Optionen DELIMITER und NULL können im binären Modus nicht verwendet werden.
Gibt an, dass die OID von jeder Zeile kopiert werden soll. (Es ist ein Fehler, OIDS zu verwenden, wenn die Tabelle keine OIDs hat.)
Das einzelne Zeichen, das die Spalten in einer Zeile trennt. Der Standardwert ist das Tab-Zeichen.
Die Zeichenkette, mit der ein NULL-Wert dargestellt werden soll. Die Standardwert ist \N (Backslash-N). Eine leere Zeichenkette wäre zum Beispiel auch eine sinnvolle Wahl.
Anmerkung: Bei COPY FROM werden alle Datenwerte, die mit dieser Zeichenkette übereinstimmen, als NULL-Wert abgespeichert. Sie sollten also darauf achten, dass Sie den selben Wert verwenden, den Sie bei COPY TO verwendet hatten.
COPY kann nur mit echten Tabellen und keinen Sichten verwendet werden.
Mit dem Schlüsselwort BINARY werden alle Daten im binären Format anstatt im Textformat gelesen bzw. geschrieben. Das ist etwas schneller als der normale Textmodus, aber Dateien im binären Format sind nicht über verschiedene Maschinenarchitekturen portierbar.
Für Tabellen, die von COPY TO gelesen werden, müssen Sie das Privileg SELECT haben; für Tabellen, in die von COPY FROM geschrieben wird, müssen Sie das Privileg INSERT haben.
Im COPY-Befehl genannte Dateien werden direkt vom Server gelesen bzw. geschrieben, nicht von der Client-Anwendung. Deshalb müssen Sie auf der Maschine des Datenbankservers, nicht der des Clients, liegen oder von ihr aus zugänglich sein. Außerdem müssen Sie vom PostgreSQL-Benutzerzugang (der Benutzer, unter dem der Server läuft) lesbar bzw. schreibbar sein. COPY mit einer Datei ist nur für Datenbank-Superuser erlaubt, da es das Lesen bzw. Schreiben aller Dateien, auf die der Server Zugriff hat, erlaubt.
Verwechseln Sie COPY nicht mit der psql-Anweisung \copy. \copy führt COPY FROM STDIN oder COPY TO STDOUT aus und liest bzw. schreibt die Daten dann in einer von psql zugänglichen Datei. Die verfügbaren Dateien und die Zugriffsrechte hängen also in diesem Fall vom Client und nicht vom Server ab.
Es wird empfohlen, dass der in COPY verwendete Dateiname immer ein absoluter Pfad ist. Bei COPY TO wird das vom Server auch durchgesetzt, aber bei COPY FROM können Sie auch einen relativen Pfad angeben. Der Pfad wird relativ zum Arbeitsverzeichnis des Serverprozesses interpretiert (irgendwo unter dem Datenverzeichnis), nicht relativ zum Arbeitsverzeichnis des Clients.
COPY FROM führt Trigger für die Zieltabelle aus und prüft Constraints. Regeln werden jedoch nicht angewendet.
COPY wird beim ersten Fehler abgebrochen. Das sollte bei COPY TO kein Problem sein, aber bei COPY FROM werden in der Zieltabelle schon einige Zeilen enthalten sein. Diese Zeilen sind nicht sichtbar und man kann auf sie auch nicht zugreifen, aber sie verbrauchen trotzdem Speicherplatz. Wenn der Fehler erst spät in einer großen Kopieroperation auftrat, dann kann dadurch eine ziemliche Menge Platz verschwendet werden. Dann können Sie VACUUM ausführen um den Platz wieder freizugeben.
Wenn COPY ohne die Option BINARY verwendet wird, dann werden die Daten als Textdatei mit einer Textzeile pro Datenbankzeile gelesen bzw. geschrieben. Die Spalten einer Zeile werden durch das Trennzeichen getrennt. Die Spaltenwerte selbst sind Zeichenketten, die von der Ausgabefunktion jedes Datentyps erzeugt worden sind bzw. die von der Eingabefunktion verarbeitet werden können. Die angegebene Zeichenkette zur NULL-Darstellung wird für Spaltenwerte die NULL sind verwendet. COPY FROM erzeugt einen Fehler, wenn irgendeine Zeile der Eingabedatei mehr oder weniger Zeilen als erwartet enthält. Wenn OIDS angegeben wurde, dann wird die OID als erste Spalte, vor den Benutzerdatenspalten, gelesen bzw. geschrieben.
Das Ende der Daten kann durch eine Zeile angezeigt werden, die nur Backslash-Punkt (\.) enthält. Die Endmarkierung wird beim Lesen aus einer Datei nicht benötigt, weil das Ende der Datei ebenso gut das Datenende anzeigt; aber eine Endmarkierung muss angegeben werden, wenn Daten vom oder zum Client kopiert werden.
Mit Backslash-Zeichen (\) können in den COPY-Daten Zeichen gesichert werden, die ansonsten als Spalten- oder Zeilentrennzeichen verstanden würden. Insbesondere muss vor die folgenden Zeichen ein Backslash gesetzt werden, wenn Sie in einem Spaltenwert auftreten: der Backslash selbst, Newline und das aktuelle Trennzeichen.
Die folgenden besonderen Backslash-Folgen werden von COPY FROM erkannt:
| Zeichenfolge | Stellt dar |
|---|---|
| \b | Backspace (ASCII 8) |
| \f | Form-Feed (ASCII 12) |
| \n | Newline (ASCII 10) |
| \r | Carriage-Return (ASCII 13) |
| \t | Tab (ASCII 9) |
| \v | Vertikaler Tab (ASCII 11) |
| \ziffern | Backslash gefolgt von drei oktalen Ziffern entspricht dem Zeichen mit jenem numerischen Code |
Schreiben Sie niemals einen Backslash vor das Datenzeichen N oder einen Punkt (.). Solche Paare werden als NULL-Darstellung (in der Standardeinstellung) bzw. als Datenendmarkierung missverstanden werden. Jedes andere Zeichen nach einem Backslash, das nicht in der obigen Tabelle erwähnt ist, steht für sich selbst.
Es ist sehr zu empfehlen, dass Anwendungen, die Daten für COPY erzeugen, Newline- und Carriage-Return-Zeichen in \n bzw. \r umwandeln. Gegenwärtig ist es möglich, das Carriage-Return-Zeichen ohne Fluchtfolge und das Newline-Zeichen als Backslash gefolgt von Newline darzustellen, aber diese Schreibweisen werden in der Zukunft nicht mehr akzeptiert werden.
Beachten Sie, dass das Ende einer Zeile im Unix-Stil markiert wird („\n“). COPY FROM kann zur Zeit noch keine Zeilenenden im DOS- oder Mac-Stil verarbeiten. Das wird wohl in einer zukünftigen Version geändert werden.
Das von COPY BINARY verwendete Format wurde in PostgreSQL 7.1 geändert. Das neue Format steht aus einem Dateikopf, null oder mehr Tupeln mit den Zeilendaten, und einem Dateiabschluss.
Der Dateikopf besteht aus 24 Bytes mit festen Feldern, gefolgt von einem Erweiterungsbereich mit variabler Länge. Die festen Felder sind:
12-Byte-Folge PGBCOPY\n\377\r\n\0. Beachten Sie, dass das Null-Byte unbedingt dazu gehört. (Diese Signatur wurde so entworfen, dass Dateien, die durch nicht 8-Bit-saubere Datenübertragung verändert worden sind, leicht erkannt werden können. Diese Signatur wird verändert durch Filter, die die Zeilenenden umschreiben, fallen gelassene Null-Bytes, verlorene hohe Bits und Paritätsänderungen.)
32-Bit-Konstante 0x01020304 in der Byte-Reihenfolge der Quelle. Ein Leseprozess könnte bei den folgenden Feldern die Byte-Reihenfolge umdrehen, wenn er hier die falsche Reihenfolge entdeckt.
32-Bit-Maske, die wichtige Aspekte des Dateiformats angibt. Bits sind von 0 (LSB) bis 31 (MSB) nummeriert. Beachten Sie, dass dieses Feld in der Byte-Reihenfolge der Quelle gespeichert ist, wie alle folgenden Integer-Felder auch. Bits 16-31 sind für wichtige Dateiformataspekte reserviert; ein Leseprozess sollte abbrechen, wenn er unerwartete Bits gesetzt vorfindet. Bits 0-15 sind für das Signalisieren von Rückwärtskompatibilitätsaspekten im Format reserviert; ein Leseprozess sollte unerwartet gesetzte Bits in diesem Bereich ignorieren. Gegenwärtig ist nur ein Optionsbit definiert, der Rest muss null sein:
wenn 1, dann sind OIDs in der Datei enthalten; wenn 0, dann nicht
32-Bit-Wert mit der Länge des restlichen Kopfs in Bytes, dieses Feld nicht mit eingeschlossen. Gegenwärtig ist dieses Feld null und das erste Tupel folgt unmittelbar. Durch zukünftige Änderungen im Format könnten weitere Daten im Dateikopf enthalten sein. Ein Leseprozess sollte Erweiterungsdaten, die er nicht verarbeiten kann, ignorieren.
Es ist angedacht, dass der Erweiterungsbereich eine Folge von sich selbst identifizierenden Stücken enthält. Das Optionsfeld soll den Lesern nicht mitteilen, was im Erweiterungsbereich ist. Das genaue Design der Kopferweiterungen wird einer späteren Version überlassen.
Dieses Design ermöglicht sowohl rückwärtskompatible Ergänzungen im Kopfformat (eine Kopferweiterung hinzufügen oder ein niedriges Optionsbit setzen) und nicht rückwärtskompatible Änderungen (ein höheres Optionsbit setzen, um die Änderung anzuzeigen, und eventuell unterstützende Daten im Erweiterungsbereich ablegen).
Jedes Tupel beginnt mit einer 16-Bit-Ganzzahl, die die Anzahl der Felder im Tupel zählt. (Gegenwärtig haben alle Tupel in einer Tabelle immer die gleiche Anzahl, aber das muss vielleicht nicht immer der Fall sein.) Dann folgt, wiederholt für jedes Feld im Tupel, eine 16-Bit-Ganzzahl typlen, eventuell gefolgt von den Felddaten. Das typlen-Feld wird folgendermaßen interpretiert:
Das Feld hat den NULL-Wert. Keine Daten folgen.
Das Feld hat einen Datentyp mit fester Länge. Genau so viele Bytes mit Daten wie angegeben folgen auf das typlen-Feld.
Das Feld hat einen Datentyp mit variabler Länge (varlena). Die nächsten vier Bytes sind der varlena-Kopf, welcher die Länge des Wertes, einschließlich der Längenangabe selbst, enthält.
Reserviert für zukünftige Verwendung.
Bei Feldern, die nicht den NULL-Wert haben, kann der Leseprozess prüfen, ob der typlen-Wert mit dem erwarteten typlen-Wert der Zielspalte übereinstimmt. Das ist eine einfache, aber sehr nützliche Methode um zu prüfen, ob die Daten wie erwartet aussehen.
Es gibt keine Ausrichtungslücken oder andere zusätzliche Daten zwischen den Feldern. Beachten Sie auch, dass das Format nicht zwischen Datentypen mit Wertübergabe und mit Referenzübergabe unterscheidet. Das ist beides beabsichtigt: Dadurch kann sich die Portierbarkeit der Datei verbessern (obwohl die Byte-Reihenfolge und Probleme beim Fließkommaformat trotzdem Probleme darstellen können, wenn man eine binäre Datei von einer Maschine auf eine andere überträgt).
Wenn OIDs in der Datei enthalten sind, dann folgt das OID-Feld unmittelbar nach dem Feld mit der Feldanzahl. Es ist ein normales Feld, außer dass es nicht in der Feldanzahl enthalten ist. Insbesondere hat es auch ein typlen-Feld: Dadurch kann man ohne zu viele Probleme mit 4 Byte und 8 Byte großen OIDs umgehen und OIDs könnten auch den NULL-Wert haben, wenn sich das einmal als wünschenswert herausstellen sollte.
Der Dateiabschluss besteht aus einem 16-Bit-Wort mit dem Wert -1. Das kann man einfach vom Feldanzahl-Wort eines Tupels unterscheiden.
Ein Leseprozess sollte einen Fehler auslösen, wenn ein Feldanzahl-Wort weder -1 noch die erwartete Anzahl von Spalten ist. Das bietet einen zusätzlichen Schutz, wenn man aus irgendwelchen Gründen die Synchronisation mit den Daten verliert.
Das folgende Beispiel kopiert eine Tabelle zum Client mit dem senkrechten Strich (|) als Feldtrennzeichen:
COPY land TO STDOUT WITH DELIMITER '|';
Dieses Beispiel kopiert Daten von einer Datei in die Tabelle land:
COPY land FROM '/usr1/proj/bray/sql/länderdaten';
Hier ist ein Beispiel für passend formatierte Daten, die von STDIN in eine Tabelle kopiert werden können (sie müssen bei STDIN die Abschlussmarkierung auf der letzten Zeile haben):
AF AFGHANISTAN AL ALBANIEN DZ ALGERIEN ZM SAMBIA ZW SIMBABWE \.
Beachten Sie, dass die Leerzeichen in jeder Zeile eigentlich ein Tab-Zeichen sein müssen.
Folgendes sind die selben Daten im binären Format, erzeugt auf einer Linux/i586-Maschine. Die gezeigten Daten wurden durch das Unix-Hilfsprogramm od -c gefiltert. Die Tabelle hat drei Spalten: Die erste ist vom Typ char(2), die zweite ist vom Typ text und die dritte ist vom Typ integer. Alle Zeilen haben einen NULL-Wert in der dritten Spalte.
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 \f \0 \0 \0 A L B A N I E N \0 \0 003 0000120 \0 377 377 006 \0 \0 \0 D Z 377 377 \f \0 \0 \0 A 0000140 L G E R I E N \0 \0 003 \0 377 377 006 \0 \0 0000160 \0 Z M 377 377 \n \0 \0 \0 S A M B I A \0 0000200 \0 003 \0 377 377 006 \0 \0 \0 Z W 377 377 \f \0 \0 0000220 \0 S I M B A B W E \0 \0 377 377
Der Befehl COPY ist eine PostgreSQL-Erweiterung.
Die folgende Syntax wurde in PostgreSQL vor Version 7.3 verwendet und wird weiterhin unterstützt:
COPY [ BINARY ] tabelle [ WITH OIDS ]
FROM { 'dateiname' | STDIN }
[ [USING] DELIMITERS 'trennzeichen' ]
[ WITH NULL AS 'null_darstellung' ]
COPY [ BINARY ] tabelle [ WITH OIDS ]
TO { 'dateiname' | STDOUT }
[ [USING] DELIMITERS 'trennzeichen' ]
[ WITH NULL AS 'null_darstellung' ]
| Zurück | Zum Anfang | Nach vorne |
| COMMIT | Nach oben | CREATE AGGREGATE |