此页面由 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 通信，PGAdapter 使用 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-dialect 数据库。虽然仅支持 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必须是单字节字符。对于文本格式，默认值是制表符；对于 CSV 格式，默认值是英文逗号。

NULL 指定表示 null 值的字符串。默认值为 \N（反斜杠 + N），如果是 CSV 格式，则为空字符串。如果您不希望将 null 与空字符串区分开来，即使是文本格式，也可能更喜欢使用空字符串。

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 数据无效