此页面由 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 操作中最多可以包含 8 万次更改或 100MB 的数据。
非原子 COPY

如果文件包含的更改次数超过 8 万次或大小超过 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 数据无效