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 指令的方法有兩種:
Atomic
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」),或使用 Spanner PG 連接器 (spgc) 執行 psql:
cat mydata.txt | psql -h localhost -c "COPY mytable FROM STDIN;"
如要使用 spgc 執行相同的匯入作業,請執行下列指令:
cat mydata.txt | spgc psql -d DATABASE_ID -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>
如果輸入檔案中的資料列未包含資料表中每個資料欄的值 (或空值),就會發生這項錯誤。可能的原因包括 CSV 檔案格式不正確,或指定的定界符選項 (或預設定界符) 與檔案中的實際定界符不符。
後續步驟
- 瞭解如何使用
psql連線至 PostgreSQL 方言資料庫。 - 瞭解 PGAdapter。