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
  • 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 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 Fahrer die in diesem Dokument 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 Batch-Anweisungen verwenden Sie die Option psql -c. Diese Option ermöglicht eine oder mehrere SQL- oder Sitzungsverwaltung Anweisungen, getrennt durch Semikolons (;), die als einzelne Ausführungsanfrage übergeben werden sollen. 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 ein Batch von INSERT-Anweisungen gesendet wird.

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-Dialekt-Datenbank. Obwohl nur STDIN unterstützt wird, können Sie Dateien über COPY importieren, indem Sie sie an COPY weiterleiten.

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

  • Atomar: COPY

    Die Daten werden in einer einzigen Transaktion kopiert. Das ist die Standardeinstellung. Standardmäßige Transaktionslimits von Spanner auf die Transaktion angewendet wird. Das bedeutet, dass höchstens In einem COPY-Vorgang können 80.000 Mutationen oder 100 MB Daten enthalten sein.

  • 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 des COPY ein Fehler auftritt und der Vorgang abgebrochen wird, sind 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 atomaren COPY aktivieren

Wenn Sie die nicht atomare COPY-Funktion 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.

QUOTE gibt das Anführungszeichen an, das bei Anführungszeichen eines Datenwerts verwendet werden soll. Der Standardwert ist ein doppeltes Anführungszeichen. Dies muss ein einzelnes Ein-Byte-Zeichen sein. Diese Option ist nur im CSV-Format zulässig.

Mit ESCAPE wird das Zeichen angegeben, das vor einem Datenzeichen stehen muss, das mit dem Wert QUOTE übereinstimmt. Der Standardwert entspricht dem Wert QUOTE, d. h., das Anführungszeichen wird verdoppelt, wenn es in den Daten enthalten ist. Dies muss ein einzelnes 1-Byte-Zeichen sein. Diese Option ist nur im 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 für jede Spalte in der Tabelle keinen Wert (oder „null“) enthält. Eine Ursache könnte eine fehlerhafte CSV-Datei oder eine Abweichung sein zwischen der angegebenen Trennzeichenoption (oder dem Standardtrennzeichen) und dem tatsächlichen Trennzeichen in der Datei.

Nächste Schritte