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 zu psql finden Sie unter psql mit einer Datenbank im PostgreSQL-Dialekt verbinden.

Meta-Befehle

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

  • Allgemein
  • Hilfe
  • Abfragepuffer
  • Eingabe/Ausgabe
  • 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 Anzeige von Informationen 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 über PGAdapter mit Spanner, wobei die Kern-Engine des Spanner-JDBC-Treibers verwendet wird. 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-Anweisung

psql und PGAdapter unterstützen SQL-Batches mit mehreren Anweisungen. Verwenden Sie die Option psql -c, um Batch-Anweisungen zu erstellen. 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 beliebige unterstützte Anweisungen enthalten und DDL-, DML- und DQL-Anweisungen können kombiniert werden.

Ein Batch mit mehreren Anweisungen wird innerhalb eines einzelnen impliziten Transaktionsblocks ausgeführt. Implizite Transaktionsblöcken werden am Ende des Batches automatisch geschlossen. Wenn innerhalb eines impliziten Transaktionsblocks Fehler auftreten, wird die gesamte Transaktion rückgängig gemacht.

Explizite BEGIN- und COMMIT-Transaktionssteuerungen werden unterstützt, ein expliziter Transaktionsblock darf jedoch keine DDL-Anweisungen enthalten.

Beispiele

DML

Das folgende Beispiel zeigt, wie Sie mehrere INSERT-Anzeigen gleichzeitig einreichen.

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');"

Im nächsten Beispiel wird gezeigt, 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 Datenbank im PostgreSQL-Dialekt zu importieren. Obwohl nur STDIN unterstützt wird, können Sie Dateien auch über COPY importieren, indem Sie sie an COPY weiterleiten.psql

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

  • Atomuhr COPY

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

  • Nicht atomar 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 der COPY ein Fehler auftritt und der Vorgang abgebrochen wird, wurden einige Zeilen möglicherweise bereits in der Datenbank gespeichert. Es kommt zu keinem Rollback. Die Transaktionen werden parallel ausgeführt. Daher werden Daten nach der Zeile in der Importdatei, die den Fehler verursacht hat, möglicherweise in die Datenbank importiert, bevor der COPY-Vorgang angehalten wird.

Nicht atomare COPY aktivieren

Wenn Sie nicht atomare COPY-Transaktionen aktivieren möchten, geben Sie den folgenden Befehl vor dem Ausführen des Kopiervorgangs ein.

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 ist das Tabulatorzeichen für das Textformat und ein Komma für das CSV-Format festgelegt.

NULL gibt den String an, der einen Nullwert darstellt. Standardmäßig ist das \N (Backslash + N) im Textformat und ein leerer String ohne Anführungszeichen im CSV-Format. In Fällen, in denen Sie Nullen nicht von leeren Strings unterscheiden möchten, können Sie auch einen leeren String im Textformat verwenden.

Mit QUOTE wird das Anführungszeichen angegeben, das verwendet werden soll, wenn ein Datenwert in Anführungszeichen gesetzt wird. Der Standardwert ist ein doppeltes Anführungszeichen. Dies muss ein einzelnes Ein-Byte-Zeichen sein. Diese Option ist nur beim CSV-Format zulässig.

Mit ESCAPE wird das Zeichen angegeben, das vor einem Datenzeichen stehen muss, das mit dem Wert QUOTE übereinstimmt. Der Standardwert ist derselbe wie der QUOTE-Wert. Das Anführungszeichen wird also verdoppelt, wenn es in den Daten vorkommt. Dies muss ein einzelnes Ein-Byte-Zeichen sein. Diese Option ist nur beim CSV-Format zulässig.

HEADER gibt an, ob der erste Datensatz der Eingabedatei ein Header ist (d. h. Spaltennamen enthält). Der Standardwert ist TRUE.

Beispiele

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

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

Im nächsten Beispiel ist mydata.csv im CSV-Format und die erste Zeile ist eine Kopfzeile 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 ein nicht atomarer COPY-Vorgang gestartet wird.

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 „null“) enthält. Eine mögliche Ursache ist eine fehlerhafte CSV-Datei oder eine Abweichung zwischen der angegebenen Trennzeichenoption (oder dem Standardtrennzeichen) und dem tatsächlichen Trennzeichen in der Datei.

Nächste Schritte