psql 命令行工具

psql 是 PostgreSQL 的命令行前端。本页面介绍了适用于 Spanner 的 PostgreSQL 接口支持的 psql 命令。如需了解如何使用 psql 进行连接，请参阅将 psql 连接到 PostgreSQL 方言数据库。

元命令

PostgreSQL 接口支持以下 psql 元命令类别：

注意：输入 \? 命令可查看每个类别下的命令。

• 常规
• 帮助
• 查询缓冲区
• 输入/输出
• 有条件
• 参考信息（仅限某些 \d 命令）
• 格式设置
• 操作系统
• 变量

不支持以下类别：

• 连接
• 大型对象

支持以下信息性命令：

命令	说明
\d	列出表（不包括系统表）
\d table	列出表列
\dt	列出所有架构中的表（详细）
\dt table	列出表（详细）
\dn	列出架构

会话管理语句

psql 通过 PGAdapter（使用 Spanner JDBC 驱动程序的核心引擎）与 Spanner 通信。该驱动程序支持会话管理语句中所述的会话管理语句。因此，您可以将这些语句与 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 必须为单字节字符。默认值对于文本格式为制表符，对于 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 数据无效

发生以下错误：

Invalid COPY data: Row length mismatched. Expected <number> columns, but only found <number>

当输入文件中的某一行并非对于表中的每个列都包含值（或为 null）时，会发生此错误。一种可能的原因是 CSV 文件格式错误，或者指定的定界符选项（或默认定界符）与文件中的实际定界符不匹配。

后续步骤

• 了解如何使用 psql 连接到 PostgreSQL 方言数据库。
• 了解 PGAdapter。