本頁面由 Cloud Translation API 翻譯而成。

psql 指令列工具

psql 是 PostgreSQL 的指令列前端。本頁面說明 Spanner 適用的 PostgreSQL 介面支援的 psql 指令。如要瞭解如何使用 psql 連線，請參閱「將 psql 連線至 PostgreSQL 方言資料庫」。

中繼指令

PostgreSQL 介面支援下列 psql 中繼指令類別：

一般
說明
查詢緩衝區
輸入/輸出
條件式
資訊 (僅限部分 \d 指令)
格式設定
作業系統
變數

系統不支援下列類別：

連線
大型物件

系統支援下列資訊指令：

指令	說明
\d	列出資料表 (不含系統資料表)
\d `table`	列出資料表欄
\dt	列出所有結構定義中的資料表 (詳細)
\dt `table`	清單表格 (詳細)
\dn	列出結構定義

工作階段管理陳述式

psql 會透過 PGAdapter 與 Spanner 通訊，後者則使用 Spanner JDBC 驅動程式的核心引擎。驅動程式支援「工作階段管理陳述式」一文所述的工作階段管理陳述式。因此，您可以搭配 psql 使用這些陳述式。

SQL 陳述式批次處理

psql 和 PGAdapter 支援多陳述式 SQL 批次。如要批次處理陳述式，請使用 psql -c 選項。這個選項可讓您以半形分號 (;) 分隔一或多個 SQL 或工作階段管理陳述式，並以單一執行要求傳遞。批次可以包含任何支援的陳述式，並可混合使用 DDL、DML 和 DQL。

多個陳述式批次會在單一隱含交易區塊中執行。系統會在批次作業結束時，自動關閉隱含交易區塊。如果隱含交易區塊內發生任何錯誤，系統會將整個交易回溯。

系統支援明確的 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 指令的方法有兩種：

原子鐘 COPY

資料會在單一交易中複製。這是預設值。交易適用 Spanner 的標準交易限制。也就是說，一項 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 必須是單一位元組字元。文字格式預設為 Tab 字元，CSV 格式則為逗號。

NULL 會指定代表空值的字串。文字格式的預設值為 \N (反斜線 + N)，CSV 格式的預設值則為不含引號的空字串。如果您不想區分空值和空字串，即使是文字格式，您可能也偏好空字串。

QUOTE 則指定在引用資料值時使用的引號字元。預設為雙引號。這必須是單一單一位元組字元。只有在使用 CSV 格式時，才能使用這個選項。

ESCAPE 會指定出現在符合 QUOTE 值的資料字元之前的字元。預設值與 QUOTE 值相同 (因此如果資料中出現引號字元，系統會將其加倍)。這必須是單一單一位元組字元。只有在使用 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 資料無效