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