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 ステートメントまたはセッション管理ステートメントを、単一の実行リクエストとして渡すことができます。バッチには、サポートされている任意のステートメントを含めることができ、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

  ファイルに 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_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）が含まれていない場合に発生します。原因として、CSV ファイルの形式が正しくない、指定した区切り文字オプション（またはデフォルトの区切り文字）とファイル内の実際の区切り文字が一致していない、などが考えられます。

次のステップ

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