psql 命令行工具

psql 是 PostgreSQL 的命令行前端。本页介绍了psql Spanner 接口支持的命令。要了解如何 联系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,但您可以使用 COPY 导入 通过 pip 命令文件导入 psql

您可以通过以下两种方式执行 COPY 命令:

  • 原子 COPY

    数据在单个事务中复制。这是默认设置。 Spanner 的标准事务限制适用于该事务。这意味着最多 一个 COPY 操作可以包含 80,000 项变更或 100 MB 数据。

  • 非原子 COPY

    COPY 会自动将数据拆分到多个 如果文件包含的变更数量超过 80,000 项,则事务处理 超过 100MB。

    如果在 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 文件格式有误,或者指定的分隔符选项(或默认分隔符)与文件中的实际分隔符不匹配。

后续步骤