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

  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 について学習する。