psql-Befehlszeilentool

psql ist das Befehlszeilen-Frontend für PostgreSQL. Auf dieser Seite werden die psql-Befehle beschrieben, die von der PostgreSQL-Schnittstelle für Spanner unterstützt werden. Informationen zum Herstellen einer Verbindung mit psql finden Sie unter psql mit einer PostgreSQL-Dialekt-Datenbank verbinden.

Meta-Befehle

Die PostgreSQL-Schnittstelle unterstützt die folgenden psql-Metabefehlskategorien:

  • Allgemein
  • Hilfe
  • Abfragezwischenspeicher
  • 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 Spanner über den PGAdapter, der die Kern-Engine des Spanner-JDBC-Treibers verwendet. Der Treiber unterstützt die unter Anweisungen zur Sitzungsverwaltung beschriebenen Anweisungen zur Sitzungsverwaltung. Daher können Sie diese Anweisungen mit psql verwenden.

Batchverarbeitung von SQL-Anweisung

psql und PGAdapter unterstützen SQL-Batches mit mehreren Anweisungen. Für Batchanweisungen verwenden Sie die Option psql -c. Mit dieser Option können eine oder mehrere durch Semikolons (;) getrennte SQL-Anweisungen oder Anweisungen zur Sitzungsverwaltung als einzelne Ausführungsanfrage übergeben werden. Ein Batch kann beliebige unterstützte Anweisungen enthalten und DDL, DML und DQL mischen.

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.

Explizite BEGIN- und COMMIT-Transaktionskontrollen werden unterstützt, aber ein expliziter Transaktionsblock kann 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 wird ein Batch von 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-Dialekt-Datenbank zu importieren. Obwohl nur STDIN unterstützt wird, können Sie Daten mit COPY importieren, indem Sie Dateien an psql weiterleiten.

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

  • Atomare COPY

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

  • Nicht atomarer COPY

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

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

Nicht atomares COPY aktivieren

Senden Sie den folgenden Befehl, bevor Sie den Kopiervorgang ausführen, um den nicht atomaren 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.

delimiter_character muss ein Ein-Byte-Zeichen sein. Standardmäßig wird im Textformat das Tabulatorzeichen und im CSV-Format ein Komma verwendet.

NULL gibt den String an, der einen Nullwert darstellt. Der Standardwert ist \N (umgekehrter Schrägstrich + N) im Textformat und ein leerer String ohne Anführungszeichen im CSV-Format. Möglicherweise bevorzugen Sie einen leeren String auch im Textformat, wenn Sie Nullen nicht von leeren Strings unterscheiden möchten.

QUOTE gibt das Anführungszeichen an, das verwendet werden soll, wenn ein Datenwert in Anführungszeichen gesetzt wird. Standardmäßig werden doppelte Anführungszeichen verwendet. Dies muss ein einzelnes Ein-Byte-Zeichen sein. Diese Option ist nur zulässig, wenn das CSV-Format verwendet wird.

ESCAPE gibt das Zeichen an, das vor einem Datenzeichen angezeigt werden soll, das mit dem Wert QUOTE übereinstimmt. Der Standardwert entspricht dem Wert QUOTE, sodass das Anführungszeichen doppelt angezeigt wird, wenn es in den Daten vorkommt. Dies muss ein einzelnes Ein-Byte-Zeichen sein. Diese Option ist nur zulässig, wenn das CSV-Format verwendet wird.

HEADER gibt an, ob der erste Datensatz der Eingabedatei eine Überschrift ist (enthält Spaltennamen). Der Standardwert ist TRUE.

Beispiele

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

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

Im nächsten Beispiel liegt mydata.csv im CSV-Format vor und die erste Zeile ist ein Header mit durch Kommas getrennten Spaltennamen.

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

Das nächste Beispiel zeigt, 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 enthält 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 nicht für jede Spalte in der Tabelle einen Wert (oder Nullwert) enthält. Eine Ursache könnte eine fehlerhafte CSV-Datei oder eine Diskrepanz zwischen der angegebenen Trennzeichenoption (oder dem Standardtrennzeichen) und dem tatsächlichen Trennzeichen in der Datei sein.

Nächste Schritte