psql コマンドライン ツール

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

メタコマンド

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

注: \? コマンドを入力すると、各カテゴリのコマンドが表示されます。

• 全般
• ヘルプ
• クエリ バッファ
• 入力 / 出力
• 条件
• 情報（一部の \d コマンドのみ）
• 書式設定
• オペレーティング システム
• 変数

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

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

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

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

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

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

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

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

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

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

例

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

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

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

• アトミック COPY

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

• 非アトミック COPY

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

  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_character は 1 バイト文字である必要があります。デフォルトは、テキスト形式の場合はタブ文字、CSV 形式の場合はカンマです。

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

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

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

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

例

この例では、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 ファイルの形式が正しくないか、指定された区切り文字オプション（またはデフォルトの区切り文字）とファイル内の実際の区切り文字が一致しないことが考えられます。

次のステップ

• psql を使用して PostgreSQL 言語データベースに接続する方法を学習する。
• PGAdapter について学習する。