psql-Befehlszeilentool

psql ist das Befehlszeilen-Front-End für PostgreSQL. Auf dieser Seite werden die psql-Befehle beschrieben, die von der PostgreSQL-Oberfläche für Cloud Spanner unterstützt werden. Informationen zum Herstellen einer Verbindung mit psql finden Sie unter psql mit einer PostgreSQL-Datenbank verbinden.

Meta-Befehle

Die PostgreSQL-Oberfläche unterstützt die folgenden psql-Metabefehlskategorien:

Hinweis: Geben Sie den Befehl \? ein, um die Befehle unter jeder Kategorie aufzurufen.

• Allgemein
• Hilfe
• Abfragepuffer
• Ein-/Ausgang
• Bedingt
• Zur Information (nur einige \d-Befehle)
• Formatierung
• Betriebssystem
• Variablen

Die folgenden Kategorien werden nicht unterstützt:

• Verbindung
• Große Objekte

Die folgenden Befehle zur Information werden unterstützt:

Befehl	Beschreibung
\d	Tabellen auflisten (mit Ausnahme von Systemtabellen)
\d table	Tabellenspalten auflisten
\dt	Tabellen in allen Schemas auflisten (detailliert)
\dt table	Tabelle auflisten (detailliert)
\dn	Schemas auflisten

Anweisungen zur Sitzungsverwaltung

psql kommuniziert mit Cloud Spanner über PGAdapter, der die Kern-Engine des Spanner JDBC-Treibers verwendet. Der Treiber unterstützt die Anweisungen zur Sitzungsverwaltung, die unter Anweisungen zur Sitzungsverwaltung beschrieben sind. Daher können Sie diese Anweisungen mit psql verwenden.

Batchverarbeitung von SQL-Anweisungen

psql und PGAdapter unterstützen SQL-Batches mit mehreren Anweisungen. Für Batch-Anweisungen verwenden Sie die Option psql -c. Mit dieser Option können eine oder mehrere SQL- oder Sitzungsverwaltungsanweisungen, die durch Semikolons (;) getrennt sind, als einzelne Ausführungsanfrage übergeben werden. Ein Batch kann alle unterstützten Anweisungen enthalten und DDL, DML und DQL kombinieren.

Ein Batch mit mehreren Anweisungen wird innerhalb eines einzelnen impliziten Transaktionsblocks ausgeführt. Implizite Transaktionsblöcke werden am Ende des Batches automatisch geschlossen. Wenn innerhalb eines impliziten Transaktionsblocks Fehler auftreten, wird die gesamte Transaktion zurückgesetzt.

Es werden explizite BEGIN- und COMMIT-Transaktionssteuerelemente unterstützt, aber ein expliziter Transaktionsblock darf keine DDL-Anweisungen enthalten.

Beispiele

DML

Das folgende Beispiel zeigt, wie Sie einen Batch von INSERT-Anweisungen senden.

psql -h localhost -p 5432 -c "INSERT INTO users (id, age, firstname) VALUES (1, 25, 'Alex'); \
 INSERT INTO users (id, age, firstname) VALUES (2, 31, 'Dana'); \
 INSERT INTO users (id, age, firstname) VALUES (3, 54, 'Izumi');"

Das nächste Beispiel zeigt, wie die SQL-Anweisungen in der Datei insert_contacts.sql ausgeführt werden.

psql -h localhost -c "$(cat contacts_insert.sql)"

DDL

In diesem Beispiel werden mehrere ALTER TABLE-Anweisungen gesendet.

psql -h localhost -p 5432 test-db -c "ALTER TABLE users ADD col1 integer; \
 ALTER TABLE users ADD col2 text; ALTER TABLE users ADD col3 float8;"

COPY-Befehl zum Importieren von Daten

Verwenden Sie den Befehl COPY FROM STDIN, um Daten aus einer Text- oder CSV-Datei in eine PostgreSQL-Datenbank zu importieren. Obwohl nur STDIN unterstützt wird, können Sie Dateien mit COPY importieren, indem Sie Dateien an psql übergeben.

Es gibt zwei Möglichkeiten, den Befehl COPY auszuführen:

• Atomar COPY

  Die Daten werden in einer einzelnen Transaktion kopiert. Das ist die Standardeinstellung. Für die Transaktion gelten die standardmäßigen Transaktionslimits von Cloud Spanner. Das bedeutet,dass maximal 40.000 Mutationen oder 100 MB Daten in einem COPY-Vorgang enthalten sein können.

• Nicht atomar COPY

  COPY teilt die Daten automatisch auf mehrere Transaktionen auf,wenn die Datei mehr als 40.000 Mutationen oder mehr als 100 MB enthält.

  Wenn während des COPY ein Fehler auftritt und der Vorgang abgebrochen wird, sind einige Zeilen möglicherweise bereits in der Datenbank gespeichert. Es findet kein Rollback statt. Die Transaktionen werden parallel ausgeführt, sodass Daten nach der Zeile in der Importdatei, die den Fehler verursacht hat, möglicherweise in die Datenbank importiert werden, bevor der Vorgang COPY angehalten wird.

Nicht-atomares COPY aktivieren

Senden Sie den folgenden Befehl, bevor Sie den Kopiervorgang ausführen, um nicht atomares COPY zu aktivieren.

SET SPANNER.AUTOCOMMIT_DML_MODE='PARTITIONED_NON_ATOMIC'

Syntax

COPY table_name [ ( column_name [, ...] ) ]
    FROM STDIN
    [ [ WITH ] ( option [, ...] ) ]

where option is one of:

    FORMAT format_name
    DELIMITER 'delimiter_character'
    NULL 'null_string'
    QUOTE 'quote_character'
    ESCAPE 'escape_character'
    HEADER [boolean]

and format_name is:
    {text|csv}

and delimiter_character is:
    [!-~] except ' " \

and null_string is:
    {a—z|A—Z|0—9|_}+

and quote_character is:
    [!-~] except ' " \

and escape_character is:
    [!-~] except ' " \

and boolean is:
    {TRUE|ON|1|FALSE|OFF|0}

Die Tabelle muss bereits vorhanden sein. Wenn keine Spaltenliste angegeben ist, werden alle Spalten der Tabelle kopiert.

Der Standardwert für FORMAT ist text.

Trennzeichen_ muss ein Ein-Byte-Zeichen sein. Der Standardwert ist das Tabulatorzeichen für das Textformat und ein Komma für das CSV-Format.

NULL gibt den String an, der einen Nullwert darstellt. Die Standardeinstellung ist \N (umgekehrter Schrägstrich + N) im Textformat und ein leerer String ohne Anführungszeichen im CSV-Format. Wenn Sie Nullen nicht von leeren Strings unterscheiden möchten, ist es möglicherweise besser, im Textformat einen leeren String anzugeben.

QUOTE gibt das Anführungszeichen an, das verwendet werden soll, wenn ein Datenwert in Anführungszeichen gesetzt wird. Standardmäßig wird das doppelte Anführungszeichen verwendet. Er muss aus einem Ein-Byte-Zeichen bestehen. Diese Option ist nur bei Verwendung des CSV-Formats zulässig.

ESCAPE gibt das Zeichen an, das vor einem Datenzeichen angezeigt werden soll, das mit dem Wert QUOTE übereinstimmt. Der Standardwert ist mit dem Wert QUOTE identisch, sodass das Anführungszeichen in den Daten verdoppelt wird. Er muss aus einem Ein-Byte-Zeichen bestehen. Diese Option ist nur bei Verwendung des CSV-Formats zulässig.

HEADER gibt an, ob der erste Eintrag der Eingabedatei ein Header ist, der Spaltennamen enthält. Der Standardwert ist TRUE.

Beispiele

In diesem Beispiel werden Daten aus der Textdatei mydata.txt in die Tabelle mytable importiert. PGAdapter muss ausgeführt werden. Weitere Informationen finden Sie unter PG-Adapter starten.

cat mydata.txt | psql -h localhost -c "COPY mytable FROM STDIN;"

Im nächsten Beispiel hat mydata.csv das CSV-Format und die erste Zeile enthält einen Header mit kommagetrennten Spaltennamen.

cat mydata.csv | psql -h localhost \
  -c "COPY mytable FROM STDIN WITH (FORMAT csv, ESCAPE '~', HEADER TRUE);"

Im nächsten Beispiel wird gezeigt, wie Sie einen nicht atomaren COPY-Vorgang starten.

cat mydata.txt | psql -h localhost \
  -c "SET SPANNER.AUTOCOMMIT_DML_MODE='PARTITIONED_NON_ATOMIC'" -c "COPY mytable FROM STDIN;"

Fehlerbehebung

Im Folgenden sind einige häufige Fehler aufgeführt.

Ungültige Eingabesyntax

Folgender Fehler tritt auf:

Invalid input syntax for type <type>:"<table_name>"

Dieser Fehler kann auftreten, wenn die Eingabedatei eine Kopfzeile mit Spaltennamen hat und die Option HEADER nicht angegeben wurde.

Ungültige COPY-Daten

Folgender Fehler tritt auf:

Invalid COPY data: Row length mismatched. Expected <number> columns, but only found <number>

Dieser Fehler tritt auf, wenn eine Zeile in der Eingabedatei keinen Wert (oder null) für jede Spalte in der Tabelle enthält. Eine Ursache könnte eine fehlerhafte CSV-Datei oder eine Abweichung zwischen der angegebenen Option (oder dem Standardtrennzeichen) und dem tatsächlichen Trennzeichen in der Datei sein.

Nächste Schritte

• Weitere Informationen zum Herstellen einer Verbindung zu einer PostgreSQL-Datenbank mit psql
• Weitere Informationen zum PGAdapter