psql コマンドライン ツール

psql は、PostgreSQL のコマンドラインのフロントエンドです。このページでは、Spanner の PostgreSQL Interface でサポートされる psql コマンドについて説明します。psql を使用して接続する方法については、psql の PostgreSQL 言語データベースへの接続をご覧ください。

メタコマンド

PostgreSQL Interface は、次の psql メタコマンド カテゴリをサポートしています。

  • 全般
  • ヘルプ
  • クエリ バッファ
  • 入力 / 出力
  • 条件次第
  • 情報(一部の \d コマンドのみ)
  • 書式設定
  • OS
  • 変数

次のカテゴリはサポートされていません。

  • 接続
  • サイズの大きなオブジェクト

次の情報コマンドがサポートされています。

コマンド 説明
\d テーブルを一覧表示する(システム テーブルを除く)
\d table テーブル列を一覧表示する
\dt すべてのスキーマのテーブルを一覧表示する(詳細)
\dt table テーブルを一覧表示する(詳細)
\dn スキーマのリスト表示

セッション管理ステートメント

psql は、Spanner JDBC ドライバのコアエンジンを使用する PGAdapter を介して Spanner と通信します。ドライバは、セッション管理ステートメントで説明されているセッション管理ステートメントをサポートしています。したがって、これらのステートメントは psql で使用できます。

SQL ステートメントのバッチ処理

psql と PGAdapter は、マルチステートメントの SQL バッチをサポートしています。ステートメントをバッチ処理するには、psql -c オプションを使用します。このオプションを使用すると、セミコロン(;)で区切られた 1 つ以上の SQL またはセッション管理ステートメントを単一の実行リクエストとして渡すことができます。バッチにはサポートされているすべてのステートメントを含めることができ、DDL、DML、DQL を混在させることができます。

マルチステートメント バッチは、1 つの暗黙的なトランザクション ブロック内で実行されます。暗黙的なトランザクション ブロックは、バッチの最後で自動的に閉じられます。暗黙的なトランザクション ブロック内でエラーが発生した場合、トランザクション全体がロールバックされます。

明示的な BEGIN および COMMIT トランザクション コントロールがサポートされていますが、明示的なトランザクション ブロックに DDL ステートメントを含めることはできません。

Examples

DML

次の例は、INSERT ステートメントのバッチを送信する方法を示しています。

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

次の例は、ファイル insert_contacts.sql で SQL ステートメントを実行する方法を示しています。

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

DDL

この例では、ALTER TABLE ステートメントのバッチを送信します。

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 コマンド

テキスト ファイルまたは CSV ファイルから PostgreSQL 言語データベースにデータをインポートするには、COPY FROM STDIN コマンドを使用します。STDIN のみがサポートされていますが、ファイルを psql にパイプすることによって COPY を使用してファイルをインポートできます。

COPY コマンドの実行には、次の 2 つの方法があります。

  • アトミック COPY

    データは 1 回のトランザクションでコピーされます。グローバル ウィンドウはデフォルト。 トランザクションには、Spanner の標準のトランザクション制限が適用されます。つまり、1 回の COPY オペレーションには最大 80,000 個のミューテーションまたは 100 MB のデータを含めることができます。

  • アトミックでない COPY

    ファイルが 80,000 個を超えるミューテーションまたは 100 MB を超える場合、COPY は自動的にデータを複数のトランザクションに分割します。

    COPY でエラーが発生し、オペレーションが中止された場合、一部の行がすでにデータベースに保持されている可能性があります。ロールバックは行われません。トランザクションは並行して実行されるため、エラーの原因となったインポート ファイルの行以降のデータが、COPY オペレーションが停止される前にデータベースにインポートされた可能性があります。

アトミックでない COPY を有効にする

アトミックでない COPY を有効にするには、コピー オペレーションを実行する前に次のコマンドを実行します。

SET SPANNER.AUTOCOMMIT_DML_MODE='PARTITIONED_NON_ATOMIC'

構文

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}

テーブルはすでに存在している必要があります。列リストが指定されていない場合、テーブルのすべての列がコピーされます。

FORMAT のデフォルトは text です。

delimiter_letter は 1 バイト文字にする必要があります。デフォルトは、テキスト形式のタブ文字と CSV 形式のカンマです。

NULL は、null 値を表す文字列を指定します。デフォルトは、テキスト形式の \N(バックスラッシュ + N)と、CSV 形式の引用符で囲まれていない空の文字列です。null と空の文字列を区別しない場合は、テキスト形式でも空の文字列を使用できます。

QUOTE は、データ値が引用符で囲まれた際に使用する引用符を指定します。デフォルトは、二重引用符です。これは 1 バイト文字にする必要があります。このオプションは、CSV 形式を使用している場合にのみ指定できます。

ESCAPE は、QUOTE 値と一致するデータ文字の前に表示する文字を指定します。デフォルトは QUOTE の値と同じです(引用符がデータに表示されると、引用符が二重になります)。これは 1 バイト文字にする必要があります。このオプションは、CSV 形式を使用している場合にのみ指定できます。

HEADER は、入力ファイルの最初のレコードがヘッダー(列名を含む)かどうかを示します。デフォルトは TRUE です。

Examples

この例では、mydata.txt という名前のテキスト形式のファイルからテーブル mytable にデータをインポートします。PGAdapter が実行されている必要があります。詳細については、PGAdapter の起動をご覧ください。

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

次の例では、mydata.csv が CSV 形式で、最初の行がカンマ区切りの列名を含むヘッダーになります。

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

次の例は、アトミックでない COPY オペレーションを開始する方法を示しています。

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

トラブルシューティング

一般的なエラーとしては、次のようなものがあります。

無効な入力構文

次のエラーが発生します。

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

このエラーは、入力ファイルに列名を含むヘッダー行があり、HEADER オプションが指定されていない場合に発生します。

無効な COPY データ

次のエラーが発生します。

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

このエラーは、入力ファイルの行にテーブル内のすべての列の値(または null)が含まれていない場合に発生します。原因の 1 つは、CSV ファイルの形式が正しくないか、指定された区切り文字オプション(またはデフォルトの区切り文字)とファイル内の実際の区切り文字が一致しないことです。

次のステップ