客户端应用

createdb

createdb — 创建一个新的 AntDB 数据库

大纲

createdb [connection-option...] [option...] [dbname [description]]

描述

createdb 创建一个新的 AntDB 数据库。

通常，执行这个命令的数据库用户将成为新数据库的所有者。但是，如果执行用户具有合适的权限，可以通过-O选项指定一个不同的所有者。

createdb 是 SQL 命令 CREATE DATABASE 的一个包装器。在通过这个工具和其他方法访问服务器来创建数据库之间没有实质性的区别。

选项

createdb 接受下列命令行参数：

• dbname

  指定要被创建的数据库名。该名称必须在这个集簇中所有 AntDB 数据库中唯一。默认是创建一个与当前系统用户同名的数据库。

• description

  指定与新创建的数据库相关联的一段注释。

• -D *tablespace* --tablespace=*tablespace*

  指定该数据库的默认表空间（这个名称被当做一个双引号引用的标识符处理）。

• -e --echo

  回显 createdb 生成并发送到服务器的命令。

• -E *encoding* --encoding=*encoding*

  指定要在这个数据库中使用的字符编码模式。

• -l *locale* --locale=*locale*

  指定要在这个数据库中使用的区域。这等效于同时指定 --lc-collate 和 --lc-ctype。

• --lc-collate=*locale*

  指定要在这个数据库中使用的 LC_COLLATE 设置。

• --lc-ctype=*locale*

  指定要在这个数据库中使用的 LC_CTYPE 设置。

• -O *owner* --owner=*owner*

  指定拥有这个新数据库的数据库用户（这个名称被当做一个双引号引用的标识符处理）。

• -T *template* --template=*template*

  指定用于创建这个数据库的模板数据库（这个名称被当做一个双引号引用的标识符处理）。

• -V --version

  打印 createdb 版本并退出。

• -? --help

  显示关于 createdb 命令行参数的帮助并退出。

选项-D、-l、-E、 -O和 -T对应于底层 SQL 命令 CREATE DATABASE 的选项，关于这些选项的信息可见该命令的内容。

createdb也接受下列命令行参数用于连接参数：

• -h *host* --host=*host*

  指定运行服务器的机器的主机名。如果该值以一个斜线开始，它被用作 Unix 域套接字的目录。如果是这样， 连接时字符串参数将覆盖所有冲突的命令行选项。

• -p *port* --port=*port*

  指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。

• -U *username* --username=*username*

  要作为哪个用户连接。

• -w --no-password

  从不发出一个口令提示。如果服务器要求口令认证并且没有其他方式提供口令（例如一个 .pgpass 文件），那么连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入口令。

• -W --password

  强制 createdb 在连接到一个数据库之前提示要求一个口令。这个选项不是必不可少的，因为如果服务器要求口令认证，createdb 将自动提示要求一个口令。但是，createdb 将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下值得用 -W 来避免额外的连接尝试。

• --maintenance-db=*dbname*

  指定要连接到来发现哪些其他数据库应该被聚簇的数据库名。如果没有指定，将使用antdb数据库。而如果它也不存在（或者如果它就是要创建新数据库的名称），将使用 template1。

环境

• PGDATABASE

  如果被设置，就是要创建的数据库名，除非在命令行中覆盖。

• PGHOST PGPORT PGUSER

  默认连接参数。如果没有在命令行或PGDATABASE指定要创建的数据库名，PGUSER 也决定要创建的数据库名。

• PG_COLOR

  规定在诊断消息中是否使用颜色。 可能的值为 always，auto 和 never。

例子

要使用默认数据库服务器创建数据库demo：

$ createdb demo

要在主机 eden、端口 5000 上使用 template0 模板数据库创建数据库 demo，这里是命令行命令和底层 SQL 命令：

$ createdb -p 5000 -h eden -T template0 -e demo
CREATE DATABASE demo TEMPLATE template0;

createuser

createuser — 定义一个新的 AntDB 用户账户

大纲

createuser [connection-option...] [option...] [username]

描述

createuser 创建一个新的 AntDB 用户（或者更准确些，是一个角色）。只有超级用户和具有 CREATEROLE 权限的用户才能创建新用户，因此 createuser 必须被以上两种用户调用。

如果你希望创建一个新的超级用户，你必须作为一个超级用户连接，而不仅仅是具有 CREATEROLE 权限。作为一个超级用户意味着绕过数据库中所有访问权限检查的能力，因此超级用户地位不能轻易被授予。

createuser 是 SQL 命令 CREATE ROLE 的一个包装器。在通过这个工具和其他方法访问服务器来创建用户之间没有实质性的区别。

选项

createuser 接受下列命令行参数：

• username

  指定要被创建的 AntDB 用户的名称。这个名称必须与这个 AntDB 安装中所有现存角色不同。

• -c *number* --connection-limit=*number*

  为该新用户设置一个最大连接数。默认值为不设任何限制。

• -d --createdb

  新用户将被允许创建数据库。

• -D --no-createdb

  新用户将不被允许创建数据库。这是默认值。

• -e --echo

  回显 createuser 生成并发送给服务器的命令。

• -E --encrypted

  此选项已过时，但为了实现向后兼容仍然接受。

• -g *role* --role=*role*

  指定一个角色，这个角色将立即加入其中成为其成员。 如果要把这个角色加入到多个角色中作为成员， 可以写多个 -g 开关。

• -i --inherit

  新角色将自动继承把它作为成员的角色的权限。这是默认值。

• -I --no-inherit

  新角色将不会自动继承把它作为成员的角色的权限。

• --interactive

  如果在命令行没有指定用户名，提示要求用户名，并且在命令行没有指定选项 -d/-D、 -r/-R、 -s/-S时也提示。

• -l --login

  新用户将被允许登入（即，该用户名能被用作初始会话用户标识符）。这是默认值。

• -L --no-login

  新用户将不被允许登入（一个没有登录权限的角色仍然可以作为管理数据库权限的方式而存在）。

• -P --pwprompt

  如果给定，createuser 将发出一个提示要求新用户的口令。如果你没有计划使用口令认证，这就不是必须的。

• -r --createrole

  新用户将被允许创建新的角色（即，这个用户将具有 CREATEROLE 权限）。

• -R --no-createrole

  新用户将不被允许创建新角色。这是默认值。

• -s --superuser

  新用户将成为一个超级用户。

• -S --no-superuser

  新用户将不会成为一个超级用户。这是默认值。

• -V --version

  打印createuser版本并退出。

• --replication

  新用户将具有 REPLICATION 权限。

• --no-replication

  新用户将不具有 REPLICATION 权限。

• -? --help

  显示有关 createuser 命令行参数的帮助并退出。

createuser 也接受下列命令行参数作为连接参数：

• -h *host* --host=*host*

  指定运行服务器的机器的主机名。如果该值以一个斜线开始，它被用作 Unix 域套接字的目录。

• -p *port* --port=*port*

  指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。

• -U *username* --username=*username*

  要作为哪个用户连接（不是要创建的用户名）。

• -w --no-password

  从不发出一个口令提示。如果服务器要求口令认证并且没有其他方式提供口令（例如一个 .pgpass 文件），那么连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入口令。

• -W --password

  强制 createuser 在连接到一个数据库之前提示要求一个口令（用来连接到服务器，而不是新用户的口令）。这个选项不是必不可少的，因为如果服务器要求口令认证，createuser 将自动提示要求一个口令。但是，createuser 将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下值得用 -W 来避免额外的连接尝试。

环境

• PGHOST PGPORT PGUSER

  默认连接参数

• PG_COLOR

  规定在诊断消息中是否使用颜色。可能的值为 always， auto 和 never。

例子

要在默认数据库服务器上创建一个用户 joe：

$ createuser joe

要在默认数据库服务器上创建一个用户 joe 并提示要求一些额外属性：

$ createuser --interactive joe
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) n
Shall the new role be allowed to create more new roles? (y/n) n

要使用在主机 eden、端口 5000 上的服务器创建同一个用户 joe，并带有显式指定的属性，看看下面的命令：

$ createuser -h eden -p 5000 -S -D -R -e joe
CREATE ROLE joe NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN;

要创建用户 joe 为一个超级用户并且立刻分配一个口令：

$ createuser -P -s -e joe
Enter password for new role: xyzzy
Enter it again: xyzzy
CREATE ROLE joe PASSWORD 'md5b5f5ba1a423792b526f799ae4eb3d59e' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;

在上面的例子中，在录入新口令时新口令并没有真正地被回显，但是为了清晰，我们特意把它列了出来。如你所见，该口令在被发送给客户端之前会被加密。

dropdb

dropdb — 移除一个 AntDB 数据库

大纲

dropdb [connection-option...] [option...] dbname

描述

dropdb 毁掉一个现有的 AntDB 数据库。执行这个命令的用户必须是一个数据库超级用户或该数据库的拥有者。

dropdb 是 SQL 命令 DROP DATABASE 的一个包装器。在通过这个工具和其他方法访问服务器来删除数据库之间没有实质性的区别。

选项

dropdb 接受下列命令行参数：

• dbname

  指定要被移除的数据库的名字。

• -e --echo

  回显 dropdb 生成并发送给服务器的命令。

• -f --force

  在删除目标数据库之前，尝试终止与该数据库的所有现有连接。有关此选项的详细信息。

• -i --interactive

  在做任何破坏性的工作之前发出一个验证提示。

• -V --version

  打印 dropdb 版本并退出。

• --if-exists

  如果数据库不存在也不抛出一个错误。在这种情况下会发出一个提醒。

• -? --help

  显示有关 dropdb 命令行参数的帮助并退出。

dropdb 也接受下列命令行参数作为连接参数：

• -h *host* --host=*host*

  指定运行服务器的机器的主机名。如果该值以一个斜线开始，它被用作 Unix 域套接字的目录。

• -p *port* --port=*port*

  指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。

• -U *username* --username=*username*

  要作为哪个用户连接。

• -w --no-password

  从不发出一个口令提示。如果服务器要求口令认证并且没有其他方式提供口令（例如一个 .pgpass 文件），那么连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入口令。

• -W --password

  强制 dropdb 在连接到一个数据库之前提示要求一个口令。这个选项不是必不可少的，因为如果服务器要求口令认证，dropdb 将自动提示要求一个口令。但是，dropdb 将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下值得用 -W 来避免额外的连接尝试。

• --maintenance-db=*dbname*

  指定要连接到来发现哪些其他数据库应该被删除的数据库名。如果没有指定，将使用 antdb 数据库。而如果它也不存在，将使用 template1。 这可以是连接字符串。 如果是这样，连接字符串参数将覆盖任何冲突的命令行选项。

环境

• PGHOST PGPORT PGUSER

  默认连接参数

• PG_COLOR

  规定在诊断消息中是否使用颜色。可能的值为 always、 auto、never。

例子

要在默认数据库服务器上毁掉数据库 demo：

$ dropdb demo

要使用在主机 eden、端口 5000 上的服务器中毁掉数据库 demo，并带有验证和回显，看看下面的命令：

$ dropdb -p 5000 -h eden -i -e demo
Database "demo" will be permanently deleted.
Are you sure? (y/n) y
DROP DATABASE demo;

dropuser

dropuser — 移除一个 AntDB 用户账户

大纲

dropuser [connection-option...] [option...] [username]

描述

dropuser 移除一个已有的 AntDB 用户。只有超级用户以及具有 CREATEROLE 权限的用户能够移除 AntDB 用户（要移除一个超级用户，你必须自己是一个超级用户）。

dropuser 是 SQL 命令DROP ROLE 的一个包装器。在通过这个工具和其他方法访问服务器来删除用户之间没有实质性的区别。

选项

dropuser 接受下列命令行参数：

• username

  指定要移除的 AntDB 用户的名字。如果没有在命令行指定并且使用了 -i/--interactive 选项，你将被提醒要求一个用户名。

• -e --echo

  回显 dropuser 生成并发送给服务器的命令。

• -i --interactive

  在实际移除该用户之前提示要求确认，并且在没有在命令行指定用户名提示要求一个用户名。

• -V --version

  打印 dropuser 版本并退出。

• --if-exists

  如果用户不存在时不要抛出一个错误。在这种情况下将发出一个提示。

• -? --help

  显示有关 dropuser 命令行参数的帮助并退出。

dropuser 也接受下列命令行参数作为连接参数：

• -h *host* --host=*host*

  指定运行服务器的机器的主机名。如果该值以一个斜线开始，它被用作 Unix 域套接字的目录。

• -p *port* --port=*port*

  指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。

• -U *username* --username=*username*

  要作为哪个用户连接（不是要移除的用户名）。

• -w --no-password

  从不发出一个口令提示。如果服务器要求口令认证并且没有其他方式提供口令（例如一个 .pgpass 文件），那么连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入口令。

• -W --password

  强制 dropuser 在连接到一个数据库之前提示要求一个口令。这个选项不是必不可少的，因为如果服务器要求口令认证，dropuser 将自动提示要求一个口令。但是，dropuser 将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下值得用-W来避免额外的连接尝试。

环境

• PGHOST PGPORT PGUSER

  默认连接参数

• PG_COLOR

  规定在诊断消息中是否使用颜色。可能的值为 always、 auto、never。

例子

要从默认数据库服务器移除用户 joe：

$ dropuser joe

要使用在主机 eden、端口 5000 上的服务器移除用户 joe，并带有验证和回显，可使用下面的命令：

$ dropuser -p 5000 -h eden -i -e joe
Role "joe" will be permanently removed.
Are you sure? (y/n) y
DROP ROLE joe;

ecpg

ecpg — 嵌入式 SQL C 预处理器

大纲

ecpg [option...] file...

描述

ecpg 是用于 C 程序的嵌入式 SQL 预处理器。它通过将 SQL 调用替换为特殊函数调用把带有嵌入式 SQL 语句的 C 程序转换为普通 C 代码。输出文件可以被任何 C 编译器工具链处理。

ecpg 将把命令行中给出的每一个输入文件转换为相应的 C 输出文件。 如果输入文件名没有任何扩展名，则假定为 .pgc。文件扩展名将由 .c 替换以构造输出文件名。 但是输出文件名可以使用 -o 选项覆盖。

如果输入文件名只是-，ecpg 从标准输入 读取程序（并写入标准输出，除非用 -o 重写）。

选项

ecpg 接受下列命令行参数：

• -c

  自动从 SQL 代码生成确定的 C 代码。当前，这对 EXEC SQL TYPE 起效。

• -C *mode*

  设置一个兼容性模式。mode 可以是 INFORMIX，INFORMIX_SE 或 ORACLE。

• -D *symbol*

  定义一个 C 预处理器符号。

• -h

  处理头文件。指定此选项后，输出文件扩展名变为 .h 而不是 .c，默认输入文件扩展名为 .pgh 而不是 .pgc。此外，将强制启用 -c 选项。

• -i

  分析系统也包括文件。

• -I *directory*

  指定一个额外的包括路径，用来寻找通过 EXEC SQL INCLUDE 包括的文件。默认值是.（当前目录）、/usr/local/include、在编译时定义的 AntDB 包括目录（默认：/usr/local/pgsql/include）以及/usr/include。

• -o *filename*

  指定 ecpg 应该将它的所有输出写到给定的 filename。 写 -o- 将所有输出发送到标准输出。

• -r *option*

  选择运行时行为。option 可以是下列之一：no_indicator 不使用指示器而使用特殊值来表示空值。历史上曾有数据库使用这种方法。prepare 在使用所有语句之前准备它们。libecpg 将保持一个预备语句的缓冲并当语句再被执行时重用该语句。如果缓冲满了，libecpg 将释放最少使用的语句。questionmarks 为兼容性原因允许使用问号作为占位符。在很久以前这被用作默认值。

• -t

  打开事务的自动提交。在这种模式下，每一个 SQL 命令会被自动提交，除非它位于一个显式事务块中。在默认模式中，命令只有当EXEC SQL COMMIT 被发出时才被提交。

• -v

  打印额外信息，包括版本和“包括”路径。

• --version

  打印 ecpg 版本并退出。

• -? --help

  显示关于 ecpg 命令行参数的帮助并退出。

注解

在编译预处理好的 C 代码文件时，编译器需要能够找到 AntDB 包括目录中的 ECPG 头文件。因此，在调用编译器时，你可能必须使用 -I 选项（例如，-I/usr/local/pgsql/include）。

使用带有嵌入式 SQL 的 C 代码的程序必须被链接到libecpg库，例如使用链接器选项-L/usr/local/pgsql/lib -lecpg。

适合于安装的这些目录的值可以使用 adb_config 找到。

例子

如果你有一个名为 prog1.pgc 的嵌入式 SQL C 源文件，你可以使用下列命令序列创建一个可执行程序：

ecpg prog1.pgc
cc -I/usr/local/pgsql/include -c prog1.c
cc -o prog1 prog1.o -L/usr/local/pgsql/lib -lecpg

adb_basebackup

adb_basebackup — 获得一个 AntDB 集簇的一个基础备份

大纲

adb_basebackup [option...]

描述

adb_basebackup 被用于获得一个正在运行的 AntDB 数据库集簇的基础备份。获得这些备份不会影响数据库的其他客户端，并且可以被用于时间点恢复以及用作一个日志传送或流复制后备服务器的开始点。

adb_basebackup 对数据库群集的文件进行精确复制，同时确保服务器自动进入和退出备份模式。备份总是从整个数据库集簇获得，不可能备份单个数据库或数据库对象。

备份通过一个使用复制协议常规 AntDB 连接制作。该连接必须由一个具有 REPLICATION 权限或者具有超级用户权限的用户 ID 建立，并且 pg_hba.conf 必须允许该复制连接。该服务器还必须被配置，使 max_wal_senders 设置得足够高以提供至少一个 walsender 用于备份以及一个用于WAL流（如果使用流）。

在同一时间可以有多个 adb_basebackup 运行，但是从性能的角度来说，只进行一次备份并且复制结果通常更好。

adb_basebackup 不仅能从主控机也能从后备机创建一个基础备份。要从后备机获得一个备份，设置后备机让它能接受复制连接（也就是，设置 max_wal_senders 和 hot_standby，并且适当配置其 pg_hba.conf）。你将也需要在主控机上启用 full_page_writes。

注意在来自后备机的备份中有一些限制：

• 不会在被备份的数据库集簇中创建备份历史文件。
• 如果正在使用 -X none，不保证备份所需的所有 WAL 文件在备份结束时被归档。
• 如果在备份期间后备机被提升为主控机，备份会失败。
• 备份所需的所有 WAL 记录必须包含足够的全页写，这要求你在主控机上启用 full_page_writes 并且不使用一个类似 pg_compresslog 的工具以 archive_command 从 WAL 文件中移除全页写。

每当 adb_basebackup 进行基本备份时，服务器的 pg_stat_progress_basebackup 视图将报告备份的进度。

选项

下列命令行选项控制输出的位置和格式：

• -D *directory* --pgdata=*directory*

  设置目标目录以将输出写入。如果该目录不存在，adb_basebackup将创建该目录（以及所有丢失的父目录）。如果已经存在，则必须为空。当备份处于 tar 模式中，目标目录可以被指定为-（破折号），从而将 tar 文件写入 stdout。这个选项是必需的。

• -F *format* --format=*format*

  为输出选择格式。format 可以是下列之一：p plain 把输出写成平面文件，使用和源服务器数据目录和表空间相同的布局。当集簇没有额外表空间时，整个数据库将被放在目标目录中。如果集簇包含额外的表空间，主数据目录将被放置在目标目录中，但是所有其他表空间将被放在它们位于源服务器上的相同的绝对路径中。这是默认格式。t tar 将输出作为 tar 文件写入目标目录中。 主数据目录的内容将被写入名为 base.tar 的文件，而其他表空间将被写入以该表空间的 OID 命名的单独的 tar 文件。如果将目标目录指定为-（破折号），则 tar 内容将被写入标准输出，该标准输出适用于管道传输至 gzip（例如）。 只有当集簇没有额外表空间并且没有使用 WAL 流时才允许这样做。

• -R --write-recovery-conf

  创建一个 standby.signal 文件，并将连接设置附加到目标目录（或使用 tar 格式的基本存档文件中）的 postgresql.auto.conf 文件中。 这样可以简化使用备份结果设置备用服务器的过程。postgresql.auto.conf 文件将记录连接设置（如果有）以及adb_basebackup 所使用的复制槽，这样流复制后面就会使用相同的设置。

• -T *olddir*=*newdir* --tablespace-mapping=*olddir*=*newdir*

  在备份期间将目录 olddir 中的表空间重定位到 newdir 中。为使之有效，olddir 必须与源服务器上定义的表空间的路径规范完全匹配。（但如果备份中没有包含 olddir 中的表空间也不是错误）。同时，newdir 是接收主机文件系统中的目录。与主目标目录一样，newdir 不必已经存在，但是如果确实存在，则必须为空。olddir 和 newdir 必须是绝对路径。如果一个路径凑巧包含了一个=符号，可用反斜线对它转义。对于多个表空间可以多次使用这个选项。如果以这种方法重定位一个表空间，主数据目录中的符号链接会被更新成指向新位置。因此新数据目录已经可以被一个所有表空间位于更新后位置的新服务器实例使用。

• --waldir=*waldir*

  指定用于预写式日志目录的位置。waldir 必须是绝对路径。只有当备份是平面文件模式时才能指定事务日志目录。 设置要写入 WAL（预写日志）文件的目录。 默认情况下，WAL文件将放置在目标目录的 pg_wal 子目录中，但是此选项可用于将它们放置在其他位置。waldir 必须是绝对路径。与主目标目录一样，waldir 不必已经存在，但是如果确实存在，则必须为空。只有当备份是平面文件模式时才可以指定此选项。

• -X *method* --wal-method=*method*

  在备份中包括所需的 WAL（预写式日志）文件。这包括所有在备份期间产生的预写式日志。除非指定了方法 none，可以在目标目录中启动 postmaster 而无需参考日志归档，从而使输出成为完全独立的备份。支持下列收集预写式日志的*方法*：n none 不要在备份中包括预写式日志。f fetch 在备份末尾收集预写式日志文件。因此，有必要把源服务器的 wal_keep_size 参数设置得足够高，这样在备份末尾之前需要的日志数据不会被移除。如果所需的日志数据在传输之前已被回收，则备份将失败并且无法使用。如果使用 tar 格式，预写式日志文件将被包含在 base.tar 文件。s stream 在进行备份时，流式传输预写式日志数据。将开启一个到服务器的第二连接并且在运行备份时并行开始流传输预写式日志。因此，它将需要两个复制连接，而不仅仅是一个。 只要客户端可以跟上预写式日志数据，使用此方法就不需要在源服务器上保存额外的预写式日志。如果使用tar格式，预写式日志文件被写入到一个单独的名为 pg_wal.tar 的文件（如果服务器的版本超过 10，该文件将被命名为 pg_xlog.tar）。这个值是默认值。

• -z --gzip

  启用对 tar 文件输出的 gzip 压缩，使用默认的压缩级别。只有使用 tar 格式时压缩才可用，并且会在所有tar文件名后面自动加上后缀 .gz。

• -Z *level* --compress=*level*

  启用对 tar 文件输出的 gzip 压缩，并且制定压缩机别（0 到 9，0 是不压缩，9 是最佳压缩）。只有使用 tar 格式时压缩才可用，并且会在所有 tar 文件名后面自动加上后缀 .gz。

下列命令行选项控制备份的生成和程序的调用：

• -c *fast|spread* --checkpoint=*fast|spread*

  将检查点模式设置为 fast（立刻）或 spread（默认）

• -C --create-slot

  指定在启动备份之前应创建由 --slot 选项命名的复制插槽。如果插槽已存在，则会引发错误。

• -l *label* --label=*label*

  为备份设置标签。如果没有指定，将使用一个默认值“adb_basebackup base backup”。

• -n --no-clean

  默认情况下，当 adb_basebackup 因为一个错误而中止时，它会把它意识到无法完成该工作之前已经创建的目录（例如目标目录和预写式日志目录）都移除。这个选项可以禁止这种清洗，因此可以用于调试。注意不管哪一种方式都不会清除表空间目录。

• -N --no-sync

  默认情况下，adb_basebackup 将等待所有文件被安全地写到磁盘上。这个选项导致 adb_basebackup 不做这种等待就返回，这样会更快一些，但是也意味着后续发生的操作系统崩溃可能会使得这个基础备份损坏。通常这个选项对测试比较有用，在创建生产安装时不应该使用。

• -P --progress

  启用进度报告。启用这个选项将在备份期间发表一个大致的进度报告。由于数据库可能在备份期间改变，这仅仅是一种近似并且可能不会刚好在 100% 结束。特别地，当 WAL 日志被包括在备份中时，总数据量无法预先估计，并且在这种情况中估计的目标尺寸会在它经过不带 WAL 的总估计后增加。

• -r *rate* --max-rate=*rate*

  设置从源服务器收集数据的最大传输速率。这有助于限制 adb_basebackup 对服务器的影响。值以每秒千字节为单位。使用后缀 M 表示每秒兆字节数。后缀 k 也可以接受，没有任何影响。有效值介于每秒32千字节和每秒1024兆字节之间。此选项始终影响数据目录的传输。只有收集方法为 fetch 时，才会影响 WAL 文件的传输。

• -S *slotname* --slot=*slotname*

  这个选项仅能与 -X stream 一起使用。它导致 WAL 流使用指定的复制槽。如果该基础备份的目的是被用作一台使用复制槽的流复制后备，则它应该使用与 primary_slot_name 中相同的复制槽名称。这可以确保主服务器不会移除位于该基础备份结束与新备用数据库上流复制开始之间产生的任何所需的 WAL 数据。指定的复制槽必须已经存在，除非同时使用了选项 -C。如果这个选项没有被指定并且服务器支持临时复制槽（版本 10 以后），则会自动使用一个临时复制槽来进行 WAL 流。

• -v --verbose

  启用冗长模式。将在启动和关闭期间输出一些额外步骤，并且如果进度报告也被启用，还会显示当前正在被处理的确切文件名。

• --manifest-checksums=*algorithm*

  指定应应用于备份清单中包含的每个文件的校验和算法。目前，可用的算法有 NONE、CRC32C、SHA224、SHA256、 SHA384 和 SHA512。默认值为 CRC32C。如果选择了 NONE，备份清单将不包含任何校验和。否则，它将包含备份中使用指定算法的每个文件的校验和。此外，清单将始终包含自身内容的 SHA256 校验和。SHA 算法比 CRC32C 算法占用大量 CPU，因此选择其中一种算法可能会增加完成备份所需的时间。使用 SHA 散列函数可为希望验证备份是否遭到篡改的用户提供每个文件的加密安全摘要，而 CRC32C 算法提供的校验和计算速度更快。它擅长捕获由于意外更改引起的错误，但不能抵抗恶意修改。 请注意，为了对有权访问备份的对手有用，备份清单必须安全地存储在其他位置，否则必须经过验证以确保自从进行备份以来未进行任何修改。adb_verifybackup 可用于根据备份清单检查备份的完整性。

• --manifest-force-encode

  强制备份清单中的所有文件名采用十六进制编码。如果未指定此选项，则仅对非 UTF8 文件名进行十六进制编码。此选项主要用于测试读取备份清单文件的工具是否正确处理此情况。

• --no-estimate-size

  阻止服务器估计将要流式传输的备份数据总量，从而导致 pg_stat_progress_basebackup 视图中的 backup_total 列始终为 NULL。如果没有此选项，则备份将从枚举整个数据库的大小开始，然后返回并发送实际内容。这可能会使备份花费的时间稍长一些，特别是在发送第一个数据之前，备份将花费更长的时间。 如果估计时间过长，此选项将有助于避免此类估计时间。使用 --progress 时不允许使用此选项。

• --no-manifest

  禁用备份清单的生成。如果未指定此选项，则服务器将生成并发送备份清单，可以使用 adb_verifybackup 进行验证。清单是备份中存在的每个文件的列表，可能包含的所有 WAL 文件除外。它还存储大小、上次修改时间和每个文件的可选校验和。

• --no-slot

  防止为备份创建临时复制插槽。默认情况下，如果选择了日志流，但没有用选项 -S 指定槽名称，则会创建一个临时复制插槽（如果源服务器支持）。这个选项的主要目的是允许在服务器没有空闲复制槽可用时制作基础备份。使用复制槽几乎总是最好的方式，因为它能防止备份期间所需的 WAL 被删除。

• --no-verify-checksums

  如果在取基础备份的服务器上启用了校验码验证，则禁用校验码验证。默认情况下，校验码会被验证并且校验码失败将会导致一种非零的退出状态。不过，基础备份在这种情况下将不会被移除，就好像使用了 --no-clean 选项一样。校验和验证失败也将报告在 pg_stat_database` 视图中。

以下命令行选项控制到源服务器的连接：

• -d *connstr* --dbname=*connstr*

  指定用于连接到服务器的参数，比如连接字符串；这些将覆盖所有冲突的命令行选项。为了和其他客户端应用一致，该选项被称为 --dbname。但是因为 adb_basebackup 并不连接到集簇中的任何特定数据库，连接字符串中的任何数据库名将被忽略。

• -h *host* --host=*host*

  指定运行服务器的机器的主机名。如果该值以一个斜线开始，它被用作 Unix 域套接字的目录。默认值取自 PGHOST 环境变量（如果设置），否则会尝试一个 Unix 域套接字连接。

• -p *port* --port=*port*

  指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。默认用 PGPORT 环境变量中的值（如果设置），或者一个编译在程序中的默认值。

• -s *interval* --status-interval=*interval*

  指定发送回源服务器的状态包之间的秒数。较小的值可以更准确地监视服务器的备份进度。一个零值完全禁用这种周期性的状态更新，不过当服务器需要时还是会有一个更新会被发送来避免超时导致的断开连接。默认值是 10 秒。

• -U *username* --username=*username*

  指定连接的用户名。

• -w --no-password

  防止发出口令提示。如果服务器要求口令认证并且没有其他方式提供口令（例如一个 .pgpass 文件），那么连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入口令。

• -W --password

  强制 adb_basebackup 在连接到源服务器之前提示要求一个口令。这个选项不是必不可少的，因为如果服务器要求口令认证， adb_basebackup 将自动提示要求一个口令。但是，adb_basebackup 将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下值得用 -W 来避免额外的连接尝试。

其他选项也可用：

• -V --version

  打印 adb_basebackup 版本并退出。

• -? --help

  显示有关 adb_basebackup 命令行参数的帮助并退出。

环境

和大部分其他 AntDB 工具相似，这个工具也使用 libpq 支持的环境变量。

环境变量 PG_COLOR 规定在诊断消息中是否使用颜色。可能的值为 always、auto、never。

注解

在备份的开始时，需要在源服务器上执行检查点。这可能需要一点时间（尤其在没有使用选项 --checkpoint=fast 时），在此期间 adb_basebackup 看起来处于闲置状态。

备份将包括数据目录和表空间中的所有文件，包括配置文件以及由第三方放在该目录中的任何额外文件，不过由 AntDB 管理的特定临时文件除外。但只有常规文件和目录会被拷贝，但用于表空间的符号链接会被保留。指向 AntDB 已知的特定目录的符号链接被拷贝为空目录。其他符号链接和特殊设备文件会被跳过。

在普通格式中，表空间将备份到源服务器上的相同路径，除非使用了 --tablespace-mapping 选项。如果没有这个选项并且表空间正在使用，在同一台服务器上进行普通格式的基础备份将无法工作，因为备份必须要写入到与原始表空间相同的目录位置。

在使用 tar 格式时，用户应负责在启动使用数据的 AntDB 服务器前解压每一个 tar 文件。如果有额外的表空间，用于它们的 tar 文件需要被解压到正确的位置。在这种情况下，服务器将根据包含在 base.tar 文件中的 tablespace_map 文件的内容为那些表空间创建符号链接。

如果在源集簇上启用了组权限，adb_basebackup 将保留数据文件的组权限。

例子

要创建服务器 mydbserver 的一个基础备份并将它存储在本地目录 /usr/local/pgsql/data 中：

$ adb_basebackup -h mydbserver -D /usr/local/pgsql/data

要创建本地服务器的一个备份，为其中每一个表空间产生一个压缩过的 tar 文件，并且将它存储在目录 backup 中，在运行期间显示一个进度报告：

$ adb_basebackup -D backup -Ft -z -P

要创建一个单一表空间本地数据库的备份并且使用 bzip2 压缩它：

$ adb_basebackup -D - -Ft -X fetch | bzip2 > backup.tar.bz2

（如果在该数据库中有多个表空间，这个命令将失败）。

要创建一个本地数据库的备份，其中 /opt/ts 中的表空间被重定位到./backup/ts：

$ adb_basebackup -D backup/data -T /opt/ts=$(pwd)/backup/ts

adb_config

adb_config — 获取已安装的 AntDB 的信息

大纲

adb_config [option...]

描述

adb_config 工具打印当前安装版本的 AntDB 的配置参数。它的设计目的之一是便于想与 AntDB 交互的软件包能够找到所需的头文件和库。

选项

要使用 adb_config，提供一个或多个下列选项：

• --bindir

  打印用户可执行文件的位置。例如使用这个选项来寻找 adb 程序。这通常也是 adb_config 程序所在的位置。

• --docdir

  打印文档文件的位置。

• --htmldir

  打印 HTML 文档文件的位置。

• --includedir

  打印客户端接口的 C 头文件的位置。

• --pkgincludedir

  打印其它 C 头文件的位置。

• --includedir-server

  打印用于服务器编程的 C 头文件的位置。

• --libdir

  打印对象代码库的位置。

• --pkglibdir

  打印动态可载入模块的位置，或者服务器可能搜索它们的位置（其它架构独立数据文件可能也被安装在这个目录）。

• --localedir

  打印区域支持文件的位置（如果在 AntDB 被编译时没有配置区域支持，这将是一个空字符串）。

• --mandir

  打印手册页的位置。

• --sharedir

  打印架构独立支持文件的位置。

• --sysconfdir

  打印系统范围配置文件的位置。

• --pgxs

  打印扩展 makefile 的位置。

• --configure

  打印当 AntDB 被配置编译时给予 configure 脚本的选项。这可以被用来重新得到相同的配置，或者找出是哪个选项编译了一个二进制包（不过注意二进制包通常包含厂商相关的自定补丁）。

• --cc

  打印用来编译 AntDB 的 CC 变量值。这显示被使用的 C 编译器。

• --cppflags

  打印用来编译 AntDB 的 CPPFLAGS 变量值。这显示在预处理时需要的 C 编译器开关（典型的是 -I 开关）。

• --cflags

  打印用来编译 AntDB 的 CFLAGS 变量值。这显示被使用的 C 编译器开关。

• --cflags_sl

  打印用来编译AntDB的CFLAGS_SL 变量值。这显示被用来编译共享库的额外 C 编译器开关。

• --ldflags

  打印用来编译 AntDB 的 LDFLAGS变量值。这显示链接器开关。

• --ldflags_ex

  打印用来编译 AntDB 的 LDFLAGS_EX 变量值。这只显示被用来编译可执行程序的链接器开关。

• --ldflags_sl

  打印用来编译 AntDB 的 LDFLAGS_SL 变量值。这只显示被用来编译共享库的链接器开关。

• --libs

  打印用来编译 AntDB 的 LIBS 变量值。这通常包含用于链接到 AntDB 中的外部库的 -l 开关。

• --version

  打印 AntDB 的版本。

• -? --help

  显示有关 adb_config 命令行参数的帮助并退出。

如果给定多于一个选项，将按照相同的顺序打印信息，每行一项。如果没有给定选项，将打印所有可用信息，并带有标签。

例子

要重建当前 AntDB 安装的编译配置，可运行下列命令：

eval ./configure `adb_config --configure`

adb_config --configure的输出包含 shell 引号，这样带空格的参数可以被正确地表示。因此，为了得到正确的结果需要使用 eval。

adb_dump

adb_dump — 把 AntDB 数据库抽取为一个脚本文件或其他归档文件

大纲

adb_dump [connection-option...] [option...] [dbname]

描述

adb_dump 是用于备份一种 AntDB 数据库的工具。即使数据库正在被并发使用，它也能创建一致的备份。adb_dump 不阻塞其他用户访问数据库（读取或写入）。

adb_dump 只转储单个数据库。要备份一个集簇或者集簇中对于所有数据库公共的全局对象（例如角色和表空间），应使用 pg_dumpall。

转储可以被输出到脚本或归档文件格式。脚本转储是包含 SQL 命令的纯文本文件，它们可以用来重构数据库到它被转储时的状态。要从这样一个脚本恢复，将它喂给 adb。脚本文件甚至可以被用来在其他机器和其他架构上重构数据库。在经过一些修改后，甚至可以在其他 SQL 数据库产品上重构数据库。

另一种可选的归档文件格式必须与adb_restore配合使用来重建数据库。它们允许 adb_restore 能选择恢复什么，或者甚至在恢复之前对条目重排序。归档文件格式被设计为在架构之间可移植。

当使用归档文件格式之一并与 adb_restore 组合时，adb_dump 提供了一种灵活的归档和传输机制。adb_dump 可以被用来备份整个数据库，然后 adb_restore 可以被用来检查归档并/或选择数据库的哪些部分要被恢复。最灵活的输出文件格式是“自定义”格式（-Fc）和“目录”格式（-Fd）。它们允许选择和重排序所有已归档项、支持并行恢复并且默认是压缩的。“目录”格式是唯一一种支持并行转储的格式。

当运行 adb_dump 时，我们应该检查输出中有没有任何警告（打印在标准错误上），特别是考虑到下面列出的限制。

选项

下列命令选项控制输出的内容和格式。

• dbname

  指定要被转储的数据库名。如果没有指定，将使用环境变量 PGDATABASE。如果环境变量也没有设置，则使用指定给该连接的用户名。

• -a --data-only

  只转储数据，而不转储模式（数据定义）。表数据、大对象和序列值都会被转储。这个选项类似于指定 --section=data，但是由于历史原因又不完全相同。

• -b --blobs

  在转储中包括大对象。这是当 --schema、--table 或 --schema-only 被指定时的默认行为。因此，只有在请求转储一个特定方案或者表的情况中，-b 开关才对向转储中加入大对象有用。注意 blobs 是被考虑的数据，因此在使用 --data-only 时将被包括在内，但在使用 --schema-only 时则不会包括。

• -B --no-blobs

  在转储中排除大对象。当同时给定 -b 和 -B时，行为是在数据被转储时输出大对象，请参考 -b 文档。

• -c --clean

  在输出创建数据库对象的命令之前输出清除（删除）它们的命令 （除非也指定了 --if-exists，如果任何对象不存在于 目的数据库中，恢复可能会产生一些伤害性的错误消息）。这个选项只对纯文本格式有意义。对于归档格式，你可以在调用 adb_restore 时指定该选项。

• -C --create

  使得在输出的开始是一个创建数据库本身并且重新连接到被创建的数据库的命令（通过这种形式的一个脚本，在运行脚本之前你连接的是目标安装中的哪个数据库都没有关系）。如果也指定了 --clean，脚本会在重新连接到目标数据库之前先删除它然后再重建。通过 --create，输出还会包括数据库的注释（如果有）以及与这个数据库相关的任何配置变量设置，也就是任何提到了这个数据库的 ALTER DATABASE ... SET ... 命令和 ALTER ROLE ... IN DATABASE ... SET ... 命令。该数据库本身的访问权限也会被转储，除非指定有 --no-acl。这个选项只对纯文本格式有意义。对于归档格式，你可以在你调用 adb_restore 时指定这个选项。

• -E *encoding* --encoding=*encoding*

  以指定的字符集编码创建转储。在默认情况下，该转储会以该数据库的编码创建（另一种得到相同结果的方式是将PGCLIENTENCODING 环境变量设置成想要的转储编码）。

• -f *file* --file=*file*

  将输出发送到指定文件。对于基于输出格式的文件这个参数可以被忽略，在那种情况下将使用标准输出。不过对于目录输出格式必须给定这个参数，在目录输出格式中指定的是一个目录而不是一个文件。在这种情况中，该目录会由 adb_dump 创建并且不需要以前就存在。

• -F *format* --format=*format*

  选择输出的格式。format 可以是下列之一：p plain 输出一个纯文本形式的 SQL 脚本文件（默认值）。c custom输出一个适合于作为 adb_restore 输入的自定义格式归档。和目录输出格式一起，这是最灵活的输出格式，它允许在恢复时手动选择和排序已归档的项。这种格式在默认情况还会被压缩。d directory 输出一个适合作为 adb_restore 输入的目录格式归档。这将创建一个目录，其中每个被转储的表和大对象都有一个文件，外加一个所谓的目录文件，该文件以一种 adb_restore 能读取的机器可读格式描述被转储的对象。一个目录格式归档能用标准 Unix 工具操纵，例如一个未压缩归档中的文件可以使用 gzip 工具压缩。这种格式默认情况下是被压缩的并且也支持并行转储。t tar 输出一个适合于输入到 adb_restore 中的 tar-格式归档。tar 格式可以兼容目录格式，抽取一个 tar 格式的归档会产生一个合法的目录格式归档。不过，tar 格式不支持压缩。还有，在使用 tar 格式时，表数据项的相对顺序不能在恢复过程中被更改。

• -j *njobs* --jobs=*njobs*

  通过同时归档 njobs 个表来运行并行转储。这个选项可能会减少执行转储所需的时间，但也会增加数据库服务器上的负载。你只能和目录输出格式一起使用这个选项，因为这是唯一一种让多个进程能在同一时间写其数据的输出格式。adb_dump 将打开 njobs + 1 个到该数据库的连接，因此确保你的 max_connections 设置足够高以容纳所有的连接。在运行一次并行转储时请求数据库对象上的排他锁可能导致转储失败。其原因是，adb_dump 主控进程会在工作者进程将要稍后转储的对象上请求共享锁，以便确保在转储运行时不会有人删除它们并让它们出错。如果另一个客户端接着请求一个表上的排他锁，那个锁将不会被授予但是会被排入队列等待主控进程的共享锁被释放。因此，任何其他对该表的访问将不会被授予或者将排在排他锁请求之后。这包括尝试转储该表的工作者进程。如果没有任何防范措施，这可能会是一种经典的死锁情况。要检测这种冲突，adb_dump 工作者进程使用 NOWAIT 选项请求另一个共享锁。 如果该工作者进程没有被授予这个共享锁，其他某人必定已经在同时请求了一个排他锁并且没有办法继续转储，因此adb_dump 除了中止转储之外别无选择。对于一个一致的备份，数据库服务器需要支持同步的快照，在 AntDB 9.2 的主服务器和 10 的后备服务器中引入了一种特性。有了这种特性，即便数据库客户端使用不同的连接，也可以保证他们看到相同的数据集。adb_dump -j 使用多个数据库连接，它用主控进程连接到数据一次，并且为每一个工作者任务再一次连接数据库。如果没有同步快照特征，在每一个连接中不同的工作者任务将不能被保证看到相同的数据，这可能导致一个不一致的备份。如果你希望运行一个 9.2 之前服务器的并行转储，你需要确保数据库内容从主控进程连接到数据库一直到最后一个工作者任务连接到数据库之间不会改变。做这些最简单的方法是在开始备份之前停止任何访问数据库的数据修改进程（DDL 以及 DML）。当对一个 9.2 之前的 AntDB 服务器运行 adb_dump -j 时，你还需要指定 --no-synchronized-snapshots 参数。

• -n *pattern* --schema=*pattern*

  只转储匹配 pattern 的模式，这会选择模式本身以及它所包含的所有对象。当没有指定这个选项时，目标数据库中所有非系统模式都将被转储。多个模式可以通过书写多个 -n 开关来选择。另外，pattern 参数可以被解释为一种根据 adb's \d 命令所用的相同规则编写的模式，这样多个模式也可以通过在该模式中书写通配字符来选择。在使用通配符时，如果需要阻止 shell 展开通配符需要小心引用该模式。注意当 -n 被指定时，adb_dump 不会尝试转储所选模式可能依赖的任何其他数据库对象。因此，无法保证一次指定模式转储的结果能够仅凭其本身被成功地恢复到一个干净的数据库中。注意当 -n 被指定时，非模式对象（如二进制大对象）不会被转储。你可以使用 --blobs 开关将二进制大对象加回到该转储中。

• -N *pattern* --exclude-schema=*pattern*

  不转储匹配 pattern 模式的任何模式。该模式被根据 -n所用的相同规则被解释。-N 可以被给定多次来排除匹配几个模式中任意一个的模式。当 -n 和 -N 都被给定时，该行为是只转储匹配至少一个 -n 开关但是不匹配 -N 开关的模式。如果只有 -N 而没有 -n，那么匹配 -N 的模式会被从一个正常转储中排除。

• -O --no-owner

  不输出设置对象拥有关系来匹配原始数据库的命令。默认情况下，adb_dump 会发出 ALTER OWNER 或 SET SESSION AUTHORIZATION 语句来设置被创建的数据库对象的拥有关系。除非该脚本被一个超级用户（或是拥有脚本中所有对象的同一个用户）启动，这些语句都将会失败。要使一个脚本能够被任意用户恢复，但把所有对象的拥有关系都给这个用户，可指定 -O。这个选项只对纯文本格式有意义。对于归档格式，你可以在调用 adb_restore 时指定该选项。

• -R --no-reconnect

  这个选项已经废弃，但是为了向后兼容仍然能被接受。

• -s --schema-only

  只转储对象定义（模式），而非数据。这个选项是 --data-only 的逆选项。它和指定 --section=pre-data --section=post-data 相似，但是由于历史原因又不完全相同。（不要把这个选项和 --schema 选项混淆，后者在“schema”的使用上有不同的含义）。要为数据库中表的一个子集排除表数据，见 --exclude-table-data。

• -S *username* --superuser=*username*

  指定要在禁用触发器时使用的超级用户的用户名。只有使用 --disable-triggers 时，这个选项才相关（通常，最好省去这个选项，而作为超级用户来启动结果脚本来取而代之）。

• -t *pattern* --table=*pattern*

  只转储名字匹配 pattern 的表。通过写多个 -t 开关可以选择多个表。另外，pattern 参数可以被解释为一种根据 adb's \d 命令所用的相同规则编写的模式，这样多个表也可以通过在该模式中书写通配字符来选择。在使用通配符时，如果需要阻止 shell 展开通配符需要小心引用该模式。当 -t 被使用时，-n 和 -N 开关不会有效果，因为被 -t 选择的表将被转储而无视那些开关，并且非表对象将不会被转储。注意当 -t 被指定时，adb_dump 不会尝试转储所选表可能依赖的任何其他数据库对象。因此，无法保证一次指定表转储的结果能够仅凭其本身被成功地恢复到一个干净的数据库中。注意 -t 开关的行为不完全向前兼容 8.2 之前的 AntDB 版本。以前，写 -t tab 将转储所有命名为 tab 的表，但现在它仅仅转储在你默认搜索路径中可见的那一个。要得到旧的行为，你可以写成 -t '*.tab'。还有，你必须写类似 -t sch.tab 的东西来选择一个特定模式中的一个表，而不是用老的惯用语 -n sch -t tab。

• -T *pattern* --exclude-table=*pattern*

  不转储匹配 pattern 模式的任何表。该模式被根据 -t 所用的相同规则被解释。-T 可以被给定多次来排除匹配几个模式中任意一个的模式。当 -t 和 -T 都被给定时，该行为是只转储匹配至少一个 -t 开关但是不匹配 -T 开关的表。如果只有 -T 而没有 -t，那么匹配 -T 的表会被从一个正常转储中排除。

• -v --verbose

  指定冗长模式。这将导致 adb_dump 向标准错误输出详细的对象注释以及转储文件的开始/停止时间，还有进度消息。

• -V --version

  adb_dump 版本并退出。

• -x --no-privileges --no-acl

  防止转储访问权限（授予/收回命令）。

• -Z *0..9* --compress=*0..9*

  指定要使用的压缩级别。零意味着不压缩。对于自定义归档格式，这会指定个体表数据段的压缩，并且默认是进行中等级别的压缩。对于纯文本输出，设置一个非零压缩级别会导致整个输出文件被压缩，就好像它被 gzip 处理过一样，但是默认是不压缩。tar 归档格式当前完全不支持压缩。

• --binary-upgrade

  这个选项用于就地升级功能。我们不推荐也不支持把它用于其他目的。这个选项在未来的发行中可能被改变而不做通知。

• --column-inserts --attribute-inserts

  将数据转储为带有显式列名的 INSERT 命令（INSERT INTO *table* (*column*, ...) VALUES ...）。这将使得恢复过程非常慢，这主要用于使转储能够被载入到非 AntDB 数据库中。重新加载期间的任何错误都将导致有问题的 INSERT 相关的行将丢失，而不是整个表内容。

• --disable-dollar-quoting

  这个选项禁止在函数体中使用美元符号引用，并且强制它们使用 SQL 标准字符串语法被引用。

• --disable-triggers

  只有在创建一个只转储数据的转储时，这个选项才相关。它指示 adb_dump 包括在数据被重新载入时能够临时禁用目标表上的触发器的命令。如果你在表上有引用完整性检查或其他触发器，并且你在数据重新载入期间不想调用它们，请使用这个选项。当前，为 --disable-triggers 发出的命令必须作为超级用户来执行。因此，你还应当使用 -S 指定一个超级用户名，或者宁可作为一个超级用户启动结果脚本。这个选项只对纯文本格式有意义。对于归档格式，你可以在调用 adb_restore 时指定这个选项。

• --enable-row-security

  只有在转储具有行安全性的表的内容时，这个选项才相关。默认情况下， adb_dump 将把 row_security 设置为 off 来确保从该表中转储 出所有的数据。如果用户不具有足够能绕过行安全性的权限，那么会抛出 一个错误这个参数指示 adb_dump 将 row_security 设置为 on，允许用户只转储该表中 它们能够访问到的部分内容。注意如果当前你使用了这个选项，你可能还想得到 INSERT 格式的转储，因为恢复期间的 COPY FROM 不支持行安全性。

• --exclude-table-data=*pattern*

  不转储匹配 pattern 模式的任何表中的数据。该模式根据 -t 的相同规则被解释。--exclude-table-data 可以被给定多次来排除匹配多个模式的表。当你需要一个特定表的定义但不想要其中的数据时，这个选项就有用了。要排除数据库中所有表的数据，见 --schema-only。

• --extra-float-digits=*ndigits*

  在转储浮点数据时使用规定的 extra_float_digits 值，而不是最大可用精度。以备份目的生成的常规转储不使用此选项。

• --if-exists

  时间条件性命令（即增加一个 IF EXISTS 子句）来清除数据库和其他对象。 只有同时指定了 --clean 时，这个选项才可用。

• --include-foreign-data=*foreignserver*

  使用与 foreignserver 模式匹配的外部服务器转储任何外部表的数据。可以通过编写 多个 --include-foreign-data 开关来选择多个外部服务器。 同样，根据 adb's \d 命令使用的相同规则， 将 foreignserver 参数解释为模式。 因此也可以通过在模式中写入通配符来选择多个外部服务器。使用通配符时， 如果需要，请小心引用该模式，以防止 Shell 扩展通配符。 唯一的例外是不允许使用空模式。注意指定 --include-foreign-data 时，adb_dump 不会检查外部表是否可写。因此，不能保证可以成功还原外部表转储的结果。

• --inserts

  将数据转储为 INSERT 命令（而不是 COPY）。这将使得恢复非常慢，这主要用于使转储能够被载入到非 AntDB 数据库中。重新加载期间的任何错误都将导致有问题的 INSERT 相关的行将丢失，而不是整个表内容。注意如果你已经重新安排了列序，该恢复可能会一起失败。--column-inserts 选项对于列序改变是安全的，但是会更慢。

• --load-via-partition-root

  在为一个分区表转储数据时，让 COPY 语句或者 INSERT 语句把包含它的分区层次的根而不是分区自身作为目标。这导致在数据被装载时，会为每一个行重新确定合适的分区。如果在一台服务器上重新装载数据时会出现行并不是总是落入到和原始服务器上相同的分区中的情况，这个选项就很有用。例如，如果分区列是文本类型并且两个系统中用于排序分区列的排序规则有着不同的定义，就会发生这种情况。在从用这个选项制作的归档恢复时，最好不要使用并行，因为 adb_restore 将不能准确地知道一个给定的归档数据项将把数据装载到哪个分区中。这会导致效率不高，因为在并行任务见会有锁冲突，或者甚至可能由于在所有的相关数据被装载前建立了外键约束而导致重新装载失败。

• --lock-wait-timeout=*timeout*

  在转储的开始从不等待共享表锁的获得。而是在指定的 timeout 内不能锁定一个表时失败。超时时长可以用 SET statement_timeout 接受的任何格式指定。

• --no-comments

  不转储注释。

• --no-publications

  不转储 publication。

• --no-security-labels

  不转储安全标签。

• --no-subscriptions

  不转储订阅。

• --no-sync

  默认情况下，adb_dump 将等待所有文件被安全地写入磁盘。这个选项会让 adb_dump 不等待直接返回，这样会更快，但是也意味着后续的一次操作系统崩溃会让该转储损坏。通常这个选项对测试有用，但是不应该在从生产安装中转储数据时使用。

• --no-synchronized-snapshots

  这个选项允许对 9.2 以前的服务器运行 adb_dump -j，详见 -j 参数的文档。

• --no-tablespaces

  不要输出选择表空间的命令。通过这个选项，在恢复期间所有的对象都会被创建在任何作为默认的表空间中。这个选项只对纯文本格式有意义。对于归档格式，你可以在调用 adb_restore 时指定该选项。

• --no-unlogged-table-data

  不转储非日志记录表的内容。这个选项对于表定义（模式）是否被转储没有影响，它只会限制转储表数据。当从一个后备服务器转储时，在非日志记录表中的数据总是会被排除。

• --on-conflict-do-nothing

  增加 ON CONFLICT DO NOTHING 到 INSERT commands。 除非规定了 --inserts,--column-inserts 或 --rows-per-insert ，否则此选项是无效的。

• --quote-all-identifiers

  强制引用所有标识符。当从 AntDB 主版本与 adb_dump 不同的服务器上转储一个数据库时或者当输出准备载入到一个具有不同主版本的服务器时，推荐使用这个选项。默认情况下，adb_dump 只对在其主版本中是被保留词的标识符加上引号。在转储其他版本服务器时，这种默认行为有时会导致兼容性问题，因为那些版本可能具有些许不同的被保留词集合。使用 --quote-all-identifiers能阻止这种问题，但代价是转储脚本更难阅读。

• --rows-per-insert=*nrows*

  数据转储为 INSERT 命令（而不是 COPY）。 控制每个 INSERT 命令的最大行数。 指定的值必须大于零。重新加载期间的任何错误都将导致有问题的 INSERT 相关的行将丢失，而不是整个表内容。

• --section=*sectionname*

  只转储命名节。节的名称可以是 pre-data、data 或 post-data。这个选项可以被指定多次来选择多个节。默认是转储所有节。数据节包含真正的表数据、大对象内容和序列值。数据后项包括索引、触发器、规则和除了已验证检查约束之外的约束的定义。数据前项包括所有其他数据定义项。

• --serializable-deferrable

  为转储使用一个可序列化事务，以保证所使用的快照与后来的数据库状态是一致的。但是这样做是在事务流中等待一个点，在该点上不能存在异常，这样就不会有转储失败或者导致其他事务带着 serialization_failure 回滚的风险。对于一个只为灾难恢复存在的转储，这个选项没什么益处。如果一个转储被用来在原始数据库持续被更新期间载入一份用于报表或其他只读负载的数据库拷贝时，这个选项就有所帮助。如果没有这个选项，转储可能会反映一个与最终提交事务的任何执行序列都不一致的状态。例如，如果使用了批处理技术，一个批处理在转储中可以显示为关闭，而其中的所有项都不出现。如果 adb_dump 被启动时没有读写事务在活动，则这个选项没有什么不同。如果有读写事务在活动，该转储的启动可能会被延迟一段不确定的时间。一旦开始运行，有没有这个开关的表现是相同的。

• --snapshot=*snapshotname*

  在做一个数据库的转储时指定一个同步的快照。在需要把转储和一个逻辑复制槽 或者一个并发会话同步时可以用上这个选项。在并行转储的情况下，将使用这个选项指定的快照名而不是取一个新快照。

• --strict-names

  要求每一个模式（-n/--schema）和表（-t/--table）限定符匹配要转储的数据库中至少一个模式/表。注意，如果没有找到有这样的模式/表限定符匹配，即便没有 --strict-names，adb_dump 也将生成一个错误。这个选项对 -N/--exclude-schema、-T/--exclude-table 或者 --exclude-table-data 没有效果。无法匹配任何对象的排除模式不会被当作错误。

• --use-set-session-authorization

  输出 SQL 标准的 SET SESSION AUTHORIZATION 命令取代 ALTER OWNER 命令来确定对象的所有关系。这让该转储更加兼容标准，但是取决于该转储中对象的历史，该转储可能无法正常恢复。而且，一个使用 SET SESSION AUTHORIZATION 的转储将一定会要求超级用户权限来正确地恢复，而 ALTER OWNER 要求更少的权限。

• -? --help

  显示有关 adb_dump 命令行参数的帮助并退出。

下列命令行选项控制数据库连接参数。

• -d *dbname* --dbname=*dbname*

  指定要连接的数据库的名称。 这等效于在命令行上将 dbname 指定为 第一个非选项参数。dbname 可以是连接字符串。 如果是这样，连接字符串参数将覆盖所有冲突的命令行选项。

• -h *host* --host=*host*

  指定服务器正在运行的机器的主机名。如果该值开始于一个斜线，它被用作一个 Unix 域套接字的目录。默认是从 PGHOST 环境变量中取得（如果被设置），否则将尝试一次 Unix 域套接字连接。

• -p *port* --port=*port*

  指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展名。默认是放在 PGPORT 环境变量中（如果被设置），否则使用编译在程序中的默认值。

• -U *username* --username=*username*

  要作为哪个用户连接。

• -w --no-password

  从不发出一个口令提示。如果服务器要求口令认证并且没有其他方式提供口令（例如一个 .pgpass 文件），那么连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入口令。

• -W --password

  强制 adb_dump 在连接到一个数据库之前提示要求一个口令。这个选项从来不是必须的，因为如果服务器要求口令认证， adb_dump 将自动提示要求一个口令。但是，adb_dump 将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下，值得键入-W来避免额外的连接尝试。

• --role=*rolename*

  指定一个用来创建该转储的角色名。这个选项导致 adb_dump 在连接到数据库后发出一个 SET ROLE rolename 命令。当已认证用户（由 -U 指定）缺少 adb_dump 所需的权限但是能够切换到一个具有所需权利的角色时，这个选项很有用。一些安装有针对直接作为超级用户登录的策略，使用这个选项可以让转储在不违反该策略的前提下完成。

环境

• PGDATABASE PGHOST PGOPTIONS PGPORT PGUSER

  默认连接参数

• PG_COLOR

  规定在诊断消息中是否使用颜色。可能的值为 always、 auto、never。.

和大部分其他 AntDB 工具相似，这个工具也使用 libpq 支持的环境变量。

实例

要把一个数据库 mydb 转储到一个 SQL 脚本文件：

$ adb_dump mydb > db.sql

要把这样一个脚本重新载入到一个（新创建的）名为 newdb 的数据库中：

$ adb -d newdb -f db.sql

要转储一个数据库到一个自定义格式归档文件：

$ adb_dump -Fc mydb > db.dump

要转储一个数据库到一个目录格式的归档：

$ adb_dump -Fd mydb -f dumpdir

要用 5 个并行的工作者任务转储一个数据库到一个目录格式的归档：

$ adb_dump -Fd mydb -j 5 -f dumpdir

要把一个归档文件重新载入到一个（新创建的）名为 newdb 的数据库：

$ adb_restore -d newdb db.dump

把一个归档文件重新装载到同一个数据库（该归档正是从这个数据库中转储得来）中，丢掉那个数据库中的当前内容：

$ adb_restore -d antdb --clean --create db.dump

要转储一个名为 mytab 的表：

$ adb_dump -t mytab mydb > db.sql

要转储 detroit 模式中名称以 emp 开始的所有表，排除名为 employee_log 的表：

$ adb_dump -t 'detroit.emp*' -T detroit.employee_log mydb > db.sql

要转储名称以 east 或者 west 开始并且以 gsm 结束的所有模式，排除名称包含词 test 的任何模式：

$ adb_dump -n 'east*gsm' -n 'west*gsm' -N '*test*' mydb > db.sql

同样，用正则表达式记号法来合并开关：

$ adb_dump -n '(east|west)*gsm' -N '*test*' mydb > db.sql

要转储除了名称以 ts_ 开头的表之外的所有数据库对象：

$ adb_dump -T 'ts_*' mydb > db.sql

要在 -t 和相关开关中指定一个大写形式或混合大小写形式的名称，你需要双引用该名称，否则它会被折叠到小写形式 。但是双引号对于 shell 是特殊的，所以反过来它们必须被引用。因此， 要转储一个有混合大小写名称的表，你需要类似这样的东西：

$ adb_dump -t "\"MixedCaseName\"" mydb > mytab.sql

pg_dumpall

pg_dumpall — 将一个 AntDB 数据库集簇抽取到一个脚本文件中

大纲

pg_dumpall [connection-option...] [option...]

描述

pg_dumpall 工具可以一个集簇中所有的 AntDB 数据库写出到（“转储”）一个脚本文件。该脚本文件包含可以用作 adb 的输入 SQL 命令来恢复数据库。它会对集簇中的每个数据库调用 adb_dump 来完成该工作。pg_dumpall 还转储对所有数据库公用的全局对象 adb_dump 不保存这些对象），也就是说数据库角色和表空间都会被转储。 目前这包括适数据库用户和组、表空间以及适合所有数据库的访问权限等属性。

因为 pg_dumpall 从所有数据库中读取表，所以你很可能需要以一个数据库超级用户的身份连接以便生成完整的转储。同样，你也需要超级用户权限执行保存下来的脚本，这样才能增加角色和组以及创建数据库。

SQL 脚本将被写出到标准输出。使用 -f/--file 选项或者 shell 操作符可以把它重定向到一个文件。

pg_dumpall 需要多次连接到 AntDB 服务器（每个数据库一次）。如果你使用口令认证，可能每次都会要求口令。这种情况下使用一个~/.pgpass 会比较方便。

选项

下列命令行选项用于控制输出的内容和格式。

• -a --data-only

  只转储数据，不转储模式（数据定义）。

• -c --clean

  包括在重建数据库之前清除（移除）它们的 SQL 命令。角色和表空间的 DROP 命令也会被加入进来。

• -E *encoding* --encoding=*encoding*

  用指定的字符集编码创建转储。默认情况下，转储使用数据库的编码创建（另一种得到相同结果的方法是设置 PGCLIENTENCODING 环境变量为想要的转储编码）。

• -f *filename* --file=*filename*

  将输出发送到指定的文件中。如果省略，将使用标准输出。

• -g --globals-only

  只转储全局对象（角色和表空间），而不转储数据库。

• -O --no-owner

  不输出用于设置对象所有权以符合原始数据库的命令。默认情况下，pg_dumpal 发出 ALTER OWNER 或 SET SESSION AUTHORIZATION 语句来设置被创建的模式元素的所有权。除非脚本是由一个超级用户（或者是拥有脚本中所有对象的同一个用户）所运行，这些语句在脚本运行时会失败。要使得一个脚本能被任意用户恢复，但又不想给予该用户所有对象的所有权，可以指定 -O。

• -r --roles-only

  只转储角色，不转储数据库和表空间。

• -s --schema-only

  只转储对象定义（模式），不转储数据。

• -S *username* --superuser=*username*

  指定要在禁用触发器时使用的超级用户的用户名。只有使用 --disable-triggers 时，这个选项才相关（通常，最好省去这个选项，而作为超级用户来启动结果脚本来取而代之）。

• -t --tablespaces-only

  只转储表空间，不转储数据库和角色。

• -v --verbose

  指定细节模式。这将导致 pg_dumpall 向标准错误输出详细的对象注释以及转储文件的开始/停止时间，还有进度消息。它也会启用adb_dump中的细节输出。

• -V --version

  打印 pg_dumpall 版本并退出。

• -x --no-privileges --no-acl

  防止转储访问权限（授予/收回命令）。

• --binary-upgrade

  这个选项用于就地升级功能。我们不推荐也不支持把它用于其他目的。这个选项在未来的发行中可能被改变而不做通知。

• --column-inserts --attribute-inserts

  将数据转储为带有显式列名的 INSERT 命令（INSERT INTO *table*(*column*, ...) VALUES ...）。这将使得恢复过程非常慢，这主要用于使转储能够被载入到非 AntDB 数据库中。

• --disable-dollar-quoting

  这个选项禁止在函数体中使用美元符号引用，并且强制它们使用 SQL 标准字符串语法被引用。

• --disable-triggers

  只有在创建一个只转储数据的转储时，这个选项才相关。它指示 pg_dumpall 包括在数据被重新载入时能够临时禁用目标表上的触发器的命令。如果你在表上有引用完整性检查或其他触发器，并且你在数据重新载入期间不想调用它们，请使用这个选项。当前，为 --disable-triggers 发出的命令必须作为超级用户来执行。因此，你还应当使用 -S 指定一个超级用户名，或者宁可作为一个超级用户启动结果脚本。

• --exclude-database=*pattern*

  不要转储名字与 pattern 匹配的数据库。可以通过编写多个 --exclude-database 开关来排除多个模式。 pattern 参数被解释为模式，根据 adb 的 \d 命令使用的相同规则 ，因此，通过在模式中编写通配符也可以排除多个数据库。 使用通配符时，请谨慎的引用模式，如果需要防止 shell 通配符扩展。

• --extra-float-digits=*ndigits*

  在转储浮点数据时使用 extra_float_digits 规定的值，而不是最大可用精度。备份目的进行的常规转储不使用此选项。

• --if-exists

  时间条件性命令（即增加一个 IF EXISTS 子句）来清除数据库和其他对象。 只有同时指定了 --clean 时，这个选项才可用。

• --inserts

  将数据转储为 INSERT 命令（而不是 COPY）。这将使得恢复非常慢，这主要用于使转储能够被载入到非 AntDB 数据库中。注意如果你已经重新安排了列序，该恢复可能会一起失败。--column-inserts 选项对于列序改变是安全的，但是会更慢。

• --load-via-partition-root

  在为一个分区表转储数据时，让 COPY 语句或者 INSERT 语句把包含它的分区层次的根而不是分区自身作为目标。这导致在数据被装载时，会为每一个行重新确定合适的分区。如果在一台服务器上重新装载数据时会出现行并不是总是落入到和原始服务器上相同的分区中的情况，这个选项就很有用。例如，如果分区列是文本类型并且两个系统中用于排序分区列的排序规则有着不同的定义，就会发生这种情况。

• --lock-wait-timeout=*timeout*

  在转储的开始从不等待共享表锁的获得。而是在指定的 timeout 内不能锁定一个表时失败。超时时长可以用 SET statement_timeout 接受的任何格式指定。

• --no-comments

  不转储注释。

• --no-publications

  不转储publication。

• --no-role-passwords

  不为角色转储口令。在恢复完后，角色的口令将是空口令，并且在设置口令之前口令认证都不会成功。由于指定这个选项时并不需要口令值，角色信息将从目录视图 pg_roles 而不是 pg_authid 中读出。因此，如果对 pg_authid 的访问被某条安全性策略所限制，那么这个选项也会有所帮助。

• --no-security-labels

  不转储安全标签。

• --no-subscriptions

  不转储 subscription。

• --no-sync

  默认情况下，pg_dumpall 将等待所有文件被安全地写入到磁盘。这个选项会让 pg_dumpall 不做这种等待而返回，这样会更快，但是意味着后续的操作系统崩溃可能留下被损坏的转储。通常来说，这个选项对测试有用，但不应该在从生产安装中转储数据时使用。

• --no-tablespaces

  不要输出选择表空间的命令。通过这个选项，在恢复期间所有的对象都会被创建在任何作为默认的表空间中。

• --no-unlogged-table-data

  不转储非日志记录表的内容。这个选项对于表定义（模式）是否被转储没有影响，它只会限制转储表数据。

• --on-conflict-do-nothing

  添加 ON CONFLICT DO NOTHING 到 INSERT 命令。 除非 --inserts 或 --column-inserts 也被规定，否则此选项不生效。

• --quote-all-identifiers

  强制引用所有标识符。在从一个与 pg_dumpall 主版本不同的 AntDB 服务器转储数据库时或者要将输出载入到一个不同主版本的服务器时，推荐使用这个选项。默认情况下，pg_dumpall 只会对为其主版本中保留词的标识符加上引号。在与其他版本的具有不同保留词集合的服务器交互时，这有时会导致兼容性问题。使用 --quote-all-identifiers 可以阻止这类问题，但是代价是转储脚本会更加难读。

• --rows-per-insert=*nrows*

  将数据转储为 INSERT 命令（而不是 COPY）。控制每个 INSERT 命令的最大行数。 指定的值必须是大于零的数。重新加载期间的任何错误都将导致仅丢失有问题的 INSERT 的行，而不是整个表内容。

• --use-set-session-authorization

  输出 SQL-标准的 SET SESSION AUTHORIZATION 命令取代 ALTER OWNER 命令来确定对象的所有关系。这让该转储更加兼容标准，但是取决于该转储中对象的历史，该转储可能无法正常恢复。

• -? --help

  显示有关 pg_dumpall 命令行参数的帮助并退出。

下列命令行选项控制数据库连接参数。

• -d *connstr* --dbname=*connstr*

  指定用于连接到服务器的参数，比如连接字符串；这些将覆盖所有冲突的命令行选项。这个选项被称为 --dbname 是为了和其他客户端应用一致，但是因为 pg_dumpall 需要连接多个数据库，连接字符串中的数据库名将被忽略。使用 -l 选项指定一个数据库，该数据库被用于初始连接，这将转储全局对象并且发现需要转储哪些其他数据库。

• -h *host* --host=*host*

  指定服务器正在运行的机器的主机名。如果该值开始于一个斜线，它被用作一个 Unix 域套接字的目录。默认是从 PGHOST 环境变量中取得（如果被设置），否则将尝试一次 Unix 域套接字连接。

• -l *dbname* --database=*dbname*

  指定要连接到哪个数据库转储全局对象以及发现要转储哪些其他数据库。如果没有指定，将会使用 antdb 数据库，如果 antdb 不存在，就使用 template1。

• -p *port* --port=*port*

  指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展名。默认是放在 PGPORT 环境变量中（如果被设置），否则使用编译在程序中的默认值。

• -U *username* --username=*username*

  要作为哪个用户连接。

• -w --no-password

  从不发出一个口令提示。如果服务器要求口令认证并且没有其他方式提供口令（例如一个 .pgpass 文件），那么连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入口令。

• -W --password

  强制 pg_dumpall 在连接到一个数据库之前提示要求一个口令。这个选项从来不是必须的，因为如果服务器要求口令认证，pg_dumpall 将自动提示要求一个口令。但是，pg_dumpall 将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下，值得键入 -W 来避免额外的连接尝试。注意对每个要被转储的数据库，口令提示都会再次出现。通常，最好设置一个 ~/.pgpass 文件来减少手工口令输入。

• --role=*rolename*

  指定一个用来创建该转储的角色名。这个选项导致 adb_dump 在连接到数据库后发出一个 SET ROLE rolename 命令。当已认证用户（由 -U 指定）缺少 adb_dump 所需的权限但是能够切换到一个具有所需权利的角色时，这个选项很有用。一些安装有针对直接作为超级用户登录的策略，使用这个选项可以让转储在不违反该策略的前提下完成。

环境

• PGHOST PGOPTIONS PGPORT PGUSER

  默认连接参数

• PG_COLOR

  规定在诊断消息中是否使用颜色。可能的值为 always、 auto、never。

和大部分其他 AntDB 工具相似，这个工具也使用 libpq 支持的环境变量。

例子

要转储所有数据库：

$ pg_dumpall > db.out

要从这个文件重新载入数据库，你可以使用：

$ adb -f db.out antdb

这里你连接哪一个数据库并不重要，因为由 pg_dumpall 创建的脚本将包含合适的命令来创建和连接到被保存的数据库。一个例外是，如果指定了 --clean，则开始时必须连接到 antdb 数据库，该脚本将立即尝试删除其他数据库，并且这种动作对于已连接上的这个数据库将会失败。

adb_isready

adb_isready — 检查一个 AntDB 服务器的连接状态

大纲

adb_isready [connection-option...] [option...]

描述

adb_isready 是一个用来检查一个 AntDB 数据库服务器的连接状态的工具。其退出状态指定了连接检查的结果。

选项

• -d *dbname* --dbname=*dbname*

  指定要连接的数据库名。dbname 可以是连接字符串。如果是这样，连接字符串参数将覆盖任何冲突的命令行选项。

• -h *hostname* --host=*hostname*

  指定运行服务器的机器的主机名。如果该值以一个斜线开始，它被用作 Unix 域套接字的目录。

• -p *port* --port=*port*

  指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。默认值取自 PGPORT 环境变量。如果环境变量没有设置，则默认值使用编译时指定的端口（通常是 6655）。

• -q --quiet

  不显示状态消息。当脚本编程时有用。

• -t *seconds* --timeout=*seconds*

  尝试连接时，在返回服务器不响应之前等待的最大秒数。设置为 0 则禁用。默认值是 3 秒。

• -U *username* --username=*username*

  作为用户 username 连接数据库，而不是用默认用户。

• -V --version

  打印adb_isready版本并退出。

• -? --help

  显示有关 adb_isready 命令行参数的帮助并退出。

退出状态

如果服务器正常接受连接，adb_isready 返回 0 给 shell；如果服务器拒绝连接（例如处于启动阶段）则返回 1；如果连接尝试没有被相应则返回 2；如果没有尝试（例如由于非法参数）则返回 3。

环境

和大部分其他 AntDB 工具相似，adb_isready 也使用 libpq 支持的环境变量。

环境变量 PG_COLOR 规定在诊断消息中是否使用颜色。可能的值为 always、auto、never。

注解

要获得服务器状态，不一定需要提供正确的用户名、口令或数据库名。 不过，如果提供了不正确的值，服务器将会记录一次失败的连接尝试。

例子

标准用法：

$ adb_isready
/tmp:6655 - accepting connections
$ echo $?
0

使用连接参数运行连接到处于启动中的 AntDB 集簇：

$ adb_isready -h localhost -p 6655
localhost:5433 - rejecting connections
$ echo $?
1

使用连接参数运行连接到无响应的 AntDB 集簇：

$ adb_isready -h someremotehost
someremotehost:6655 - no response
$ echo $?
2

adb_receivewal

adb_receivewal — 以流的方式从一个 AntDB 服务器得到预写式日志

大纲

adb_receivewal [option...]

描述

adb_receivewal 被用来从一个运行着的 AntDB 集簇以流的方式得到预写式日志。预写式日志会被使用流复制协议以流的方式传送，并且被写入到文件的一个本地目录。这个目录可以被用作归档位置来做一次使用时间点恢复的恢复。

当预写式日志在服务器上被产生时，adb_receivewal 实时以流的方式传输预写式日志，并且不像 archive_command 那样等待段完成。由于这个原因，在使用 adb_receivewal 时不必设置 archive_timeout。

与 AntDB 后备服务器上的 WAL 接收进程不同，adb_receivewal 默认只在一个 WAL 文件被关闭时才刷入 WAL 数据。要实时刷入 WAL 数据，必须指定选项 --synchronous。 由于 adb_receivewal 不应用于 WAL，当 synchronous_commit 等于 remote_apply 时，你将不允许它成为同步备用。 如果发生这样的情况，它将成为一个永远不能拉起的备用数据库，并且会导致事务提交阻塞。 为了避免这种情况，你应该为 synchronous_standby_names 配置一个适当的值，或规定为 adb_receivewal 的 application_name 与它不匹配，或将synchronous_commit 的值更改为 remote_apply 以外的内容。

预写式日志在一个常规 AntDB 连接上被以流式传送，并且使用复制协议。连接必须由一个具有 REPLICATION 权限的用户或者一个超级用户建立，并且 pg_hba.conf 必须允许复制连接。服务器也必须被配置一个足够高的 max_wal_senders 来至少留出一个可用会话给流。

如果该连接丢失，或者它一开始就由于一个非致命错误而没有被建立，adb_receivewal 将无限期地重试连接并且尽可能重新建立流。为了避免这种行为，使用 -n 参数。

如果不出现致命错误，adb_receivewal 将一直运行直至被 SIGINT 信号（Control+C）终止。

选项

• -D *directory* --directory=*directory*

  要把输出写到哪个目录。这个参数是必需的。

• -E *lsn* --endpos=*lsn*

  当接收到达指定的 LSN 时，自动停止复制并且以正常退出状态 0 退出。如果有一个记录的 LSN 正好等于 lsn，则该记录将会被处理。

• --if-not-exists

  当指定 --create-slot 并且具有指定名称 的槽已经存在时不要抛出错误。

• -n --no-loop

  不要在连接错误上循环。相反，碰到一个错误时立刻退出。

• --no-sync

  这个选项导致 adb_receivewal 不强制 WAL 数据被刷回磁盘。这样会更快，但是也意味着接下来的操作系统崩溃会让 WAL 段损坏。通常，这个选项对于测试有用，但不应该在对生产部署进行 WAL 归档时使用。这个选项与 --synchronous 不兼容。

• -s *interval* --status-interval=*interval*

  指定发送回服务器的状态包之间的秒数。这允许我们更容易地监控服务器的进度。 一个零值完全禁用这种周期性的状态更新，不过当服务器需要时还是会有一个更新 会被发送来避免超时导致的断开连接。默认值是 10 秒。

• -S *slotname* --slot=*slotname*

  要求 adb_receivewal 使用一个已有的复制槽。在使用这个选项时， adb_receivewal 将会报告给服务器一个刷写位置，指示每一个 段是何时被同步到磁盘的，这样服务器可以在不需要该段时移除它。当 adb_receivewal 的复制客户端在服务器 上被配置为一个同步后备时，那么使用一个复制槽将会向服务器报告刷写 位置，但只在一个 WAL 文件被关闭时报告。因此，该配置将导致主服务 器上的事务等待很长的时间并且无法令人满意地工作。要让这种配置工作 正确，还必须制定选项 --synchronous（见下文）。

• --synchronous

  在 WAL 数据被收到后立即刷入到磁盘。还要在刷写后立即向服务器回送 一个状态包（不考虑 --status-interval）。如果adb_receivewal 的复制客户端在服务器 上被配置为一个同步后备，应该指定这个选项来确保向服务器发送及时的反馈。

• -v --verbose

  启用冗长模式。

• -Z *level* --compress=*level*

  启用预写式日志上的 gzip 压缩，并且指定压缩级别（0 到 9，0 是不压缩而 9 是最大压缩）。所有的文件名后都将被追加后缀 .gz。

下列命令行选项控制数据库连接参数。

• -d *connstr* --dbname=*connstr*

  指定用于连接到服务器的参数，作为连接字符串；这些将覆盖所有冲突的命令行选项。为了和其他客户端应用一致，该选项被称为 --dbname。但是因为 adb_receivewal 并不连接到集簇中的任何特定数据库，连接字符串中的数据库名将被忽略。

• -h *host* --host=*host*

  指定运行服务器的机器的主机名。如果该值以一个斜线开始，它被用作 Unix 域套接字的目录。默认值取自 PGHOST 环境变量（如果设置），否则会尝试一个 Unix 域套接字连接。

• -p *port* --port=*port*

  指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。默认用 PGPORT 环境变量中的值（如果设置），或者一个编译在程序中的默认值。

• -U *username* --username=*username*

  要作为哪个用户连接。

• -w --no-password

  从不发出一个口令提示。如果服务器要求口令认证并且没有其他方式提供口令（例如一个 .pgpass 文件），那么连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入口令。

• -W --password

  强制 adb_receivewal 在连接到一个数据库之前提示要求一个口令。这个选项不是必不可少的，因为如果服务器要求口令认证，adb_receivewal 将自动提示要求一个口令。但是，adb_receivewal 将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下值得用 -W 来避免额外的连接尝试。

为了控制物理复制槽，adb_receivewal 可以执行下列两种动作之一：

• --create-slot

  用 --slot 中指定的名称创建一个新的物理复制槽， 然后退出。

• --drop-slot

  删除 --slot 中指定的复制槽，然后退出。

其他选项也可用：

• -V --version

  打印 adb_receivewal 版本并退出。

• -? --help

  显示有关 adb_receivewal 命令行参数的帮助并退出。

退出状态

在被 SIGINT 信号终止（没有正常的方式结束它。因此这不是一种错误）时，adb_receivewal 将以状态 0 退出。 对于致命错误或者其他信号，退出状态将不是零。

环境

和大部分其他 AntDB 工具相似，这个工具也使用 libpq 支持的环境变量。

环境变量 PG_COLOR 规定在诊断消息中是否使用颜色。可能的值为 always、auto、never。

注解

在使用 adb_receivewal 替代 archive_command 作为主要的 WAL 备份方法时， 强烈建议使用复制槽。否则，服务器可能会在预写式日志文件被备份好之前重用 或者移除它们，因为没有任何信息（不管是来自 archive_command 或是复制槽）能够指示 WAL 流已经被归档到什么程度。不过要注意，如果接收者没有持续地取走 WAL 数据， 一个复制槽将会填满服务器的磁盘空间。

如果在源集簇上启用了组权限，adb_receivewal 将保留接收到的 WAL 文件上的组权限。

例子

要从位于 mydbserver 的服务器流式传送预写式日志并且将它存储在本地目录 /usr/local/pgsql/archive：

$ adb_receivewal -h mydbserver -D /usr/local/pgsql/archive

adb_recvlogical

adb_recvlogical — 控制 AntDB 逻辑解码流

大纲

adb_recvlogical [option...]

描述

adb_recvlogical控制逻辑解码复制槽以及来自这种复制槽的流数据。

它会创建一个复制模式的连接，因此它受到和 adb_receivewal 相同的约束，还有逻辑复制的约束。

adb_recvlogical 与逻辑解码 SQL 接口的 peek 和 get 模式没有等效性。它咋接收到数据以及干净地退出时，它会惰性地发送数据的确认。为了检查一个槽上还未消费的待处理数据，可以使用 pg_logical_slot_peek_changes。

选项

必须至少要指定下列选项之一来选择一个动作：

• --create-slot

  为 --dbname 指定的数据库用--slot 指定的名称创建一个新的逻辑复制槽，使用 --plugin指定的输出插件。

• --drop-slot

  删除名称由 --slot 指定的复制槽，然后退出。

• --start

  从 --slot 指定的逻辑复制槽开始进行流式传送更改，一直继续 到被一个信号终止。如果服务器端关机或者断开连接导致更改流结束，会进入一个 循环一直重试，通过指定 --no-loop 可以防止这种情况下进入 循环重试。流格式由槽创建时指定的输出插件决定。连接必须是连接到用于创建该槽的同一个数据库上。

--create-slot 和 --start 可以被一起指定。 --drop-slot 不能和另一个动作组合在一起。

下面的命令行选项控制输出的位置和格式以及其他复制行为：

• -E *lsn* --endpos=*lsn*

  在 --start 模式中，当接收过程到达指定的 LSN 时会自动地停止复制并且以正常的退出状态 0 退出。如果不处于 --start 模式时指定这个选项，则会发生错误。如果有一个记录的 LSN 正好等于 lsn，则该记录将被输出。--endpos 不会察觉到事务边界并且可能会在一个事务中间截断输出。任何部分输出的事务都将不会被消费，并且在下一次从该槽中读取时将会重放该事务。单个的消息不会被截断。

• -f *filename* --file=*filename*

  把接收到并且解码好的事务数据写入到一个文件。使用-可以写到 stdout。

• -F *interval_seconds* --fsync-interval=*interval_seconds*

  指定 adb_recvlogical 发出 fsync() 调用确保输出文件被安全地刷到磁盘的频度。服务器将会偶尔要求客户端执行一次刷写并且把刷写位置报告给服务器。 这个设置可以在此之外更加频繁地执行刷写。指定间隔为 0 会完全禁止发出 fsync() 调用，但是仍会报告进度给服务器。在这种情况下，发生崩溃会导致数据丢失。

• -I *lsn* --startpos=*lsn*

  在 --start 模式中，从给定的 LSN 开始复制。在其他模式中会忽略这个参数。

• --if-not-exists

  当指定 --create-slot 并且具有指定名称 的槽已经存在时不要抛出错误。

• -n --no-loop

  当服务器连接丢失时，不要在循环中重试，直接退出。

• -o *name*[=*value*] --option=*name*[=*value*]

  如果指定了输出插件，把选项值 value 传递给选项 name。存在哪些选项以及它们的效果 取决于使用的输出插件。

• -P *plugin* --plugin=*plugin*

  在创建一个槽时使用指定的逻辑解码输出插件。如果该槽已经存在，这个选项没有效果。

• -s *interval_seconds* --status-interval=*interval_seconds*

  这个选项和 adb_receivewal 中的同名选项具有 相同的效果。请参考那里的描述。

• -S *slot_name* --slot=*slot_name*

  在 --start 模式中，使用名为 slot_name 的已有逻辑复制槽。在--create-slot模式中，使用这个名称创建该槽。在 --drop-slot 模式中，删除这个名称指定的槽。

• -v --verbose

  开启详细输出模式。

下列命令行选项控制数据库连接参数。

• -d *database* --dbname=*database*

  要连接的数据库。这个选项的详细含义请见动作的描述。dbname 可以是连接字符串。 如果是这样，连接字符串参数将覆盖任何冲突的命令行选项。默认为用户名。

• -h *hostname-or-ip* --host=*hostname-or-ip*

  指定服务器正在运行的机器的主机名。如果该值开始于一个斜线， 它被用作一个 Unix 域套接字的目录。默认是从 PGHOST 环境变量中取得（如果被设置）， 否则将尝试一次 Unix 域套接字连接。

• -p *port* --port=*port*

  指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展名。 默认是放在 PGPORT 环境变量中（如果被设置）， 否则使用编译在程序中的默认值。

• -U *user* --username=*user*

  要作为哪个用户连接。默认是用当前操作系统用户名。

• -w --no-password

  从不发出一个口令提示。如果服务器要求口令认证并且没有 其他方式提供口令（例如一个 .pgpass 文件）， 那么连接尝试将失败。这个选项对于批处理任务和脚本有用， 因为在其中没有一个用户来输入口令。

• -W --password

  强制 adb_dump 在连接到一个数据库之前提示要求一个口令。这个选项不是必须的，因为如果服务器要求口令认证， adb_dump 将自动提示要求一个口令。 但是，adb_dump 将浪费一次连接尝试 来发现服务器想要一个口令。在某些情况下，值得键入 -W 来避免额外的连接尝试。

还有下列附加选项可用：

• -V --version

  打印 adb_recvlogical 的版本并且退出。

• -? --help

  显示关于 adb_recvlogical 命令行参数的帮助，并且退出。

环境

和大部分其他 AntDB 工具相似，这个工具也使用 libpq 支持的环境变量。

环境变量 PG_COLOR 规定在诊断消息中是否使用颜色。可能的值为 always、auto、never。

注解

如果在源服务器上启用了组权限，adb_recvlogical 将会在接收到的 WAL 文件上保留组权限。

adb_restore

adb_restore — 从一个由 adb_dump 创建的归档文件恢复一个 AntDB 数据库

大纲

adb_restore [connection-option...] [option...] [filename]

描述

adb_restore 是一个用来从 adb_dump 创建的非文本格式归档恢复 AntDB 数据库的工具。它将发出必要的命令把该数据库重建成它被保存时的状态。这些归档文件还允许 adb_restore 选择恢复哪些内容或者在恢复前对恢复项重排序。这些归档文件被设计为可以在不同的架构之间迁移。

adb_restore 可以在两种模式下操作。如果指定了一个数据库名称，adb_restore 会连接那个数据库并且把归档内容直接恢复到该数据库中。否则，会创建一个脚本，其中包含着重建该数据库所必要的 SQL 命令，它会被写入到一个文件或者标准输出。这个脚本输出等效于adb_dump 的纯文本输出格式。因此，一些控制输出的选项与 adb_dump 的选项类似。

显然，adb_restore 无法恢复不在归档文件中的信息。例如，如果归档使用“以 INSERT 命令转储数据”选项创建， adb_restore 将无法使用 COPY 语句装载数据。

选项

adb_restore 接受下列命令行参数。

• filename

  指定要被恢复的归档文件（对于一个目录格式的归档则是目录）的位置。如果没有指定，则使用标准输入。

• -a --data-only

  只恢复数据，不恢复模式（数据定义）。如果在归档中存在，表数据、大对象和序列值会被恢复。这个选项类似于指定 --section=data，但是由于历史原因两者不完全相同。

• -c --clean

  在重新创建数据库对象之前清除（丢弃）它们（除非使用了 --if-exists，如果有对象在目标数据库中不存在，这可能会生成一些无害的错误消息）。

• -C --create

  在恢复一个数据库之前县创建它。如果还指定了 --clean，在连接到目标数据库之前丢弃并且重建它。如果使用 --create， adb_restore 还会恢复数据库的注释（如果有）以及与其相关的配置变量设置，也就是任何提到过这个数据库的 ALTER DATABASE ... SET ...和 ALTER ROLE ... IN DATABASE ... SET ...命令。不管是否指定 --no-acl，数据库本身的访问权限都会被恢复。在使用这个选项时，-d 提到的数据库只被用于发出初始的 DROP DATABASE 和 CREATE DATABASE 命令。所有要恢复到该数据库名中的数据都出现在归档中。

• -d *dbname* --dbname=*dbname*

  连接到数据库*dbname* 并且直接恢复到该数据库中。dbname 可以是连接字符串。如果是这样，连接字符串参数将覆盖任何冲突的命令行选项。

• -e --exit-on-error

  在发送 SQL 命令到该数据库期间如果碰到一个错误就退出。默认行为是继续并且在恢复结束时显示一个错误计数。

• -f *filename* --file=*filename*

  为生成的脚本指定输出文件，或在与 -l 选项一起使用时为列表指定输出文件。为 stdout 用 -。

• -F *format* --format=*format*

  指定归档的格式。并不一定要指定该格式，因为 adb_restore 将会自动决定格式。如果指定，可以是下列之一：c custom 归档是 adb_dump 的自定义格式。d directory 归档是一个目录归档。t tar 归档是一个 tar 归档。

• -I *index* --index=*index*

  只恢复提及的索引的定义。可以通过写多个 -I 开关指定多个索引。

• -j *number-of-jobs* --jobs=*number-of-jobs*

  使用并发任务运行 adb_restore 中最耗时的步骤 — 载入数据、创建索引或者创建约束； 同时，最多使用 number-of-jobs 个并发会话。对于一个运行在多处理器机器上的服务器， 这个选项能够大幅度减少恢复一个大型数据库的时间。当发出脚本而不是直接连接到数据库服务器时，将忽略此选项。每一个任务是一个进程或者一个线程，这取决于操作系统，它们都使用一个独立的服务器连接。这个选项的最佳值取决于服务器、客户端以及网络的硬件设置。因素包括 CPU 的核心数和磁盘设置。一个好的建议是服务器上 CPU 的核心数，但是更大的值在很多情况下也能导致更快的恢复时间。当然，过高的值会由于超负荷反而导致性能降低。这个选项只支持自定义和目录归档格式。输入必须是一个常规文件或目录（例如，不能是一个管道或者标准输出）。还有，多任务不能和选项 --single-transaction 一起用。

• -l --list

  列出归档的内容的表格。这个操作的输出能被用作 -L 选项的输入。注意如果把 -n 或 -t 这样的过滤开关与 -l 一起使用，它们将会限制列出的项。

• -L *list-file* --use-list=*list-file*

  只恢复在 list-file 中列出的归档元素，并且按照它们出现在该文件中的顺序进行恢复。注意如果把 -n 或 -t 这样的过滤开关与 -L 一起使用，它们将会进一步限制要恢复的项。list-file 通常是编辑一个 -l 操作的输出来创建。行可以被移动或者移除，并且也可以通过在行首放一个（;）将其注释掉。例子见下文。

• -n *shcema* --schema=*schema*

  只恢复在被提及的模式中的对象。可以用多个 -n 开关来指定多个模式。这可以与 -t 选项组合在一起只恢复一个指定的表。

• -N *schema* --exclude-schema=*schema*

  不恢复所提及方案中的对象。可以用多个 -N 开关指定多个要被排除的方案。如果对同一个方案名称同时给出了 -n 和 -N，则 -N会胜出并且该方案会被排除。

• -O --no-owner

  不要输出将对象的所有权设置为与原始数据库匹配的命令。默认情况下，adb_restore 会发出 ALTER OWNER 或者 SET SESSION AUTHORIZATION 语句来设置已创建的模式对象的所有权。除非到该数据库的初始连接是一个超级用户（或者拥有脚本中所有对象的同一个用户）建立的，这些语句将会失败。通过 -O，任何用户名都可以被用于初始连接，并且这个用户将会拥有所有被创建的对象。

• -P *function-name(argtype [, ...])* --function=*function-name(argtype [, ...])*

  只恢复被提及的函数。要小心地拼写函数的名称和参数使它们正好就是出现在转储文件的内容表中的名称和参数。可以使用多个 -P开关指定多个函数。

• -R --no-reconnect

  这个选项已被废弃，但是出于向后兼容性的目的，系统仍然还接受它。

• -s --schema-only

  只恢复归档中的模式（数据定义）不恢复数据。这个选项是 --data-only 的逆选项。它与指定 --section=pre-data --section=post-data 相似，但是由于历史原因并不完全相同。（不要把这个选项和 --schema 选项弄混，后者把词“schema”用于一种不同的含义）。

• -S *username* --superuser=*username*

  指定在禁用触发器时要用的超级用户名。只有使用 --disable-triggers 时这个选项才相关。

• -t *table* --table=*table*

  只恢复所提及的表的定义和数据。出于这个目的，“table”包括视图、物化视图、序列和外部表。可以写上多个 -t 开关可以选择多个表。这个选项可以和 -n 选项结合在一起指定一个特定模式中的表。注意在指定 -t 时，adb_restore 不会尝试恢复所选表可能依赖的任何其他数据库对象。因此，无法确保能成功地把一个特定表恢复到一个干净的数据库中。注意这个标志的行为和 adb_dump 的 -t 标志不一样。在 adb_restore 中当前没有任何通配符匹配的规定，也不能在其 -t 选项中包括模式的名称。而且，虽然adb_dump 的 -t 标志也会转储选中表的附属对象（例如索引），但是 adb_restore 的 -t 标志不包括这些附属对象。注意在 9.6 版本之前的 AntDB 9.6 中，这个标志只匹配表，而并不匹配其他类型的关系。

• -T *trigger* --trigger=*trigger*

  只恢复所提及的触发器。可以用多个 -T 开关指定多个触发器。

• -v --verbose

  指定冗长模式。

• -V --version

  打印该 adb_restore 的版本并退出。

• -x --no-privileges --no-acl

  阻止恢复访问权限（授予/收回命令）。

• -1 --single-transaction

  将恢复作为单一事务执行（即把发出的命令包裹在 BEGIN/COMMIT 中）。这可以确保要么所有命令完全成功，要么任何改变都不被应用。这个选项隐含了 --exit-on-error。

• --disable-triggers

  只有在执行一个只恢复数据的恢复时，这个选项才相关。它指示 adb_restore 在装载数据时执行命令临时禁用目标表上的触发器。如果你在表上有参照完整性检查或者其他触发器并且你不希望在数据载入期间调用它们时，请使用这个选项。目前，为 --disable-triggers 发出的命令必须以超级用户身份完成。因此你还应该用 -S 指定一个超级用户名，或者更好的方法是以一个 AntDB 超级用户运行 adb_restore。

• --enable-row-security

  只有在恢复具有行安全性的表的内容时，这个选项才相关。默认情况下，adb_restore 将把 row_security 设置为 off 来确保所有数据都被恢复到表中。如果用户不拥有足够绕过行安全性的权限，那么会抛出一个错误。这个参数指示 adb_restore 把 row_security 设置为 on 允许用户尝试恢复启用了行安全性的表的内容。如果用户没有从转储向表中插入行的权限，这仍将失败。注意当前这个选项还要求转储处于 INSERT 格式，因为 COPY FROM 不支持行安全性。

• --if-exists

  使用条件命令（即增加一个 IF EXISTS 子句）删除数据库对象。只有指定了 --clean 时，这个选项才有效。

• --no-comments

  即便归档中包含注释也不输出恢复注释的命令。

• --no-data-for-failed-tables

  默认情况下，即便表的创建命令失败（例如因为表已经存在），表数据也会被恢复。通过这个选项，对这类表的数据会被跳过。如果目标数据库已经包含了想要的表内容，这种行为又很有有用。例如，AntDB 扩展（如 PostGIS）的辅助表可能已经被载入到目标数据库中，指定这个选项就能阻止把重复的或者废弃的数据载入到这些表中。只有当直接恢复到一个数据库中时这个选项才有效，在产生 SQL 脚本输出时这个选项不会产生效果。

• --no-publications

  即便归档中包含 publication 也不输出恢复 publication 的命令。

• --no-security-labels

  不要输出恢复安全标签的命令，即使归档中包含安全标签。

• --no-subscriptions

  即便归档中包含 subscription 也不输出恢复 subscription 的命令。

• --no-tablespaces

  不输出命令选择表空间。通过这个选项，所有的对象都会被创建在恢复时的默认表空间中。

• --section=*sectionname*

  只恢复提及的小节。小节的名称可以是 pre-data、data 或者 post-data。可以把这个选项指定多次来选择多个小节。默认值是恢复所有小节。数据小节包含实际的表数据以及大对象定义。Post-data 项由索引定义、触发器、规则和除已验证的检查约束之外的约束构成。Pre-data 项由所有其他数据定义项构成。

• --strict-names

  要求每一个模式（-n/--schema）以及表（-t/--table）限定词匹配备份文件中至少一个模式/表。

• --use-set-session-authorization

  输出 SQL 标准的 SET SESSION AUTHORIZATION 命令取代 ALTER OWNER命令来决定对象拥有权。这会让转储更加兼容标准，但是依赖于转储中对象的历史，可能无法正确恢复。

• -? --help

  显示有关 adb_restore 命令行参数的帮助，并且退出。

adb_restore也接受下列用于连接参数的命令行参数：

• -h *host* --host=*host*

  指定服务器正在运行的机器的主机名。如果该值开始于一个斜线，它被用作一个 Unix 域套接字的目录。默认是从 PGHOST 环境变量中取得（如果被设置），否则将尝试一次 Unix 域套接字连接。

• -p *port* --port=*port*

  指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展名。默认是放在 PGPORT 环境变量中（如果被设置），否则使用编译在程序中的默认值。

• -U *username* --username=*username*

  要作为哪个用户连接。

• -w --no-password

  不发出一个口令提示。如果服务器要求口令认证并且没有其他方式提供口令（例如一个 .pgpass 文件），那么连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入口令。

• -W --password

  强制 adb_restore 在连接到一个数据库之前提示要求一个口令。这个选项不是必须的，因为如果服务器要求口令认证，adb_restore 将自动提示要求一个口令。但是，adb_restore 将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下，值得键入 -W 来避免额外的连接尝试。

• --role=*rolename*

  指定一个用来创建该转储的角色名。这个选项导致 adb_restore 在连接到数据库后发出一个 SET ROLE rolename 命令。当已认证用户（由 -U 指定）缺少 adb_restore 所需的权限但是能够切换到一个具有所需权利的角色时，这个选项很有用。一些安装有针对直接作为超级用户登录的策略，使用这个选项可以让转储在不违反该策略的前提下完成。

环境

• PGHOST PGOPTIONS PGPORT PGUSER

  默认连接参数

• PG_COLOR

  规定在诊断消息中是否使用颜色。可能的值为 always、 auto、never。 never.

和大部分其他 AntDB 工具相似，这个工具也使用 libpq 支持的环境变量。

注解

如果你的数据库集簇对于 template1 数据库有任何本地添加，要注意将 adb_restore 的输出载入到一个真正的空数据库。否则你很可能由于以增加对象的重复定义而得到错误。要创建一个不带任何本地添加的空数据库，从 template0 而不是 template1 复制它，例如：

CREATE DATABASE foo WITH TEMPLATE template0;

下面将详细介绍 adb_restore 的局限性。

• 在恢复数据到一个已经存在的表中并且使用了选项 --disable-triggers 时，adb_restore 会在插入数据之前发出命令禁用用户表上的触发器，然后在完成数据插入后重新启用它们。如果恢复在中途停止，可能会让系统目录处于错误的状态。
• adb_restore 不能有选择地恢复大对象，例如只恢复特定表的大对象。如果一个归档包含大对象，那么所有的大对象都会被恢复，如果通过 -L、-t 或者其他选项进行了排除，它们一个也不会被恢复。

一旦完成恢复，应该在每一个被恢复的表上运行 ANALYZE，这样优化器能得到有用的统计信息。

示例

假设我们已经以自定义格式转储了一个叫做 mydb 的数据库：

$ adb_dump -Fc mydb > db.dump

要删除该数据库并且从转储中重新创建它：

$ dropdb mydb
$ adb_restore -C -d antdb db.dump

-d开关中提到的数据库可以是任何已经存在于集簇中的数据库，adb_restore 只会用它来为 mydb 发出 CREATE DATABASE 命令。通过 -C，数据总是会被恢复到出现在归档文件的数据库名中。

要把转储重新载入到一个名为 newdb 的新数据库中：

$ createdb -T template0 newdb
$ adb_restore -d newdb db.dump

注意我们不使用 -C，而是直接连接到要恢复到其中的数据库。还要注意我们是从 template0 而不是 template1 创建了该数据库，以保证它最初是空的。

要对数据库项重排序，首先需要转储归档的表内容：

$ adb_restore -l db.dump > db.list

列表文件由一个头部和一些行组成，这些行每一个都用于一个项，例如：

;
; Archive created at Mon Sep 14 13:55:39 2009
;     dbname: DBDEMOS
;     TOC Entries: 81
;     Compression: 9
;     Dump Version: 1.10-0
;     Format: CUSTOM
;     Integer: 4 bytes
;     Offset: 8 bytes
;     Dumped from database version: 8.3.5
;     Dumped by adb_dump version: 8.3.8
;
;
; Selected TOC Entries:
;
3; 2615 2200 SCHEMA - public pasha
1861; 0 0 COMMENT - SCHEMA public pasha
1862; 0 0 ACL - public pasha
317; 1247 17715 TYPE public composite pasha
319; 1247 25899 DOMAIN public domain0 pasha

分号表示开始一段注释，行首的数字表明了分配给每个项的内部归档 ID。

文件中的行可以被注释掉、删除以及重排序。例如：

10; 145433 TABLE map_resolutions antdb
;2; 145344 TABLE species antdb
;4; 145359 TABLE nt_header antdb
6; 145402 TABLE species_records antdb
;8; 145416 TABLE ss_old antdb

把这样一个文件作为 adb_restore 的输入将会只恢复项 10 和 6，并且先恢复 10 再恢复 6。

$ adb_restore -L db.list db.dump

adb_verifybackup

adb_verifybackup — 验证 AntDB 集群的基础备份的完整性

大纲

adb_verifybackup [option...]

简介

adb_verifybackup 用于根据备份时服务器生成的 backup_manifest 检查使用 adb_basebackup 进行的数据库群集备份的完整性。备份必须以“普通”格式存储；“tar”格式的备份可以在解压缩后进行检查。

需要注意的是，由 adb_verifybackup 执行的验证不包括也不可能包括运行中的服务器在尝试使用备份时执行的所有检查。 即使使用此工具，也应执行测试还原，并验证生成的数据库是否按预期工作，以及它们是否包含正确的数据。但是，adb_verifybackup 可以检测到由于存储问题或用户错误而经常出现的许多问题。

备份验证分四个阶段进行。首先，adb_verifybackup 读取 backup_manifest 文件。如果该文件不存在、无法读取、格式不正确或无法根据其内部校验和进行验证，adb_verifybackup 将以致命错误终止。

其次，adb_verifybackup 将尝试验证当前存储在磁盘上的数据文件是否与服务器打算发送的数据文件完全相同，下面将介绍一些例外情况。 除了少数例外，额外和丢失的文件将被检测到。此步骤将忽略 postgresql.auto.conf、standby.signal 和 recovery.signal 的存在与否或对其的任何修改，因为预计这些文件可能是在备份过程中创建或修改的。它也不会抱怨目标目录中的 backup_manifest 文件或 pg_wal 中的任何内容，即使这些文件不会列在备份清单中。只检查文件；不验证目录的存在与否，除非间接验证：如果目录丢失，则它应该包含的任何文件也必然会丢失。

接下来，adb_verifybackup 将对所有文件进行校验和计算，将校验和与清单中的值进行比较，并对计算出的校验和与清单中存储的校验和不匹配的任何文件发出错误。对于在上一步中产生错误的任何文件，不执行此步骤，因为已知这些文件存在问题。在上一步中被忽略的文件在此步骤中也被忽略。

最后，adb_verifybackup 将使用清单来验证恢复备份所需的预写式日志记录是否存在，并且它们可以被读取和解析。 backup_manifest 包含有关需要哪些预写式日志记录的信息，并且 adb_verifybackup 将使用该信息来调用 adb_waldump 来解析这些预写式日志记录。 --quiet 标志将被使用，因此 adb_waldump 只会报告错误，而不会产生任何其他输出。虽然这种级别的验证足以检测明显的问题，例如丢失的文件或内部校验和不匹配的问题，但它们还不足以检测尝试恢复时可能出现的所有问题。例如，此方法无法检测到产生具有正确校验和但指定无意义操作的预写式日志记录的服务器错误。

请注意，如果存在不需要恢复备份的额外 WAL 文件，则此工具不会检查它们，尽管可以为此使用单独的 adb_waldump 调用。 另请注意，WAL 验证是特定于版本的：您必须使用 adb_verifybackup 的版本，因此是 adb_waldump 的版本，它与正在检查的备份有关。 相比之下，数据文件完整性检查应适用于生成 backup_manifest 文件的任何版本的服务器。

选项

adb_verifybackup 接受以下命令行参数：

• -e --exit-on-error

  检测到备份问题后立即退出。 如果没有指定这个选项，adb_verifybackup 将在检测到问题后继续检查备份，并将检测到的所有问题报告为错误。

• -i *path* --ignore=*path*

  在将备份中实际存在的数据文件列表与 backup_manifest 文件中列出的数据文件列表进行比较时，忽略指定的文件或目录，该文件或目录应表示为相对路径名。如果指定了目录，则此选项会影响以该位置为根的整个子树。 如果相对路径名与指定的路径名匹配，有关额外文件、丢失文件、文件大小差异或校验和不匹配的投诉将被抑制。 可以多次指定此选项。

• -m *path* --manifest-path=*path*

  使用指定路径的清单文件，而不是位于备份目录根目录中的清单文件。

• -n --no-parse-wal

  不要试图解析从该备份恢复所需的预写式日志数据。

• -q --quiet

  成功验证备份后不要打印任何内容。

• -s --skip-checksums

  不要验证数据文件校验和。但仍检查是否存在文件以及这些文件的大小。这样将会快得多，因为文件本身不需要读取。

• -w *path* --wal-directory=*path*

  尝试解析存储在指定目录中的 WAL 文件，而不是 pg_wal。 如果备份存储在与WAL存档不同的位置，则这可能很有用。

其他选项也可用：

• -V --version

  打印 adb_verifybackup 版本并退出。

• -? --help

  显示有关 adb_verifybackup 命令行参数的帮助，然后退出。

示例

要在 mydbserver 上创建服务器的基本备份并验证备份的完整性：

$ adb_basebackup -h mydbserver -D /usr/local/pgsql/data
$ adb_verifybackup /usr/local/pgsql/data

要在 mydbserver 上创建服务器的基本备份，请将清单移动到备份目录之外的某个位置，并验证备份：

$ adb_basebackup -h mydbserver -D /usr/local/pgsql/backup1234
$ mv /usr/local/pgsql/backup1234/backup_manifest /my/secure/location/backup_manifest.1234
$ adb_verifybackup -m /my/secure/location/backup_manifest.1234 /usr/local/pgsql/backup1234

要在忽略手动添加到备份目录的文件的同时验证备份，并跳过校验和验证：

$ adb_basebackup -h mydbserver -D /usr/local/pgsql/data
$ edit /usr/local/pgsql/data/note.to.self
$ adb_verifybackup --ignore=note.to.self --skip-checksums /usr/local/pgsql/data

adb

adb — AntDB 的交互式终端

大纲

adb [option...] [dbname [username]]

描述

adb 是一个 AntDB 的基于终端的前端。它让你能交互式地键入查询，把它们发送给 AntDB，并且查看查询结果。或者，输入可以来自于一个文件或者命令行参数。此外，adb 还提供一些元命令和多种类似 shell 的特性来为编写脚本和自动化多种任务提供便利。

选项

• -a --echo-all

  把所有非空输入行按照它们被读入的形式打印到标准输出（不适用于交互式行读取）。这等效于把变量 ECHO 设置为 all。

• -A --no-align

  切换到非对齐输出模式（默认输出模式是对齐的）。这等效于 \pset format unaligned。

• -b --echo-errors

  把失败的 SQL 命令打印到标准错误输出。这等效于把变量 ECHO 设置为 errors。

• -c *command* --command=*command*

  指定 adb 执行一个给定的命令字符串 command。这个选项可以重复多次并且以任何顺序与 -f 选项组合在一起。当 -c 或者 -f 被指定时，adb 不会从标准输入读取命令，直到它处理完序列中所有的 -c 和 -f 选项之后终止。*command*必须是一个服务器完全可解析的命令字符串（即不包含 adb 相关的特性）或者单个反斜线命令。因此不能在一个 -c 选项中混合 SQL 和 adb 元命令。要那样做，可以使用多个 -c 选项或者把字符串用管道输送到 adb 中，例如：adb -c '\x' -c 'SELECT * FROM foo;'或者 echo '\x \\ SELECT * FROM foo;' | adb（\\是分隔符元命令）。每一个被传递给 -c 的 SQL 命令字符串会被当做一个单独的请求发送给服务器。因此，即便该字符串包括多个 SQL 命令，服务器也会把它当做一个事务来执行，除非在该字符串中有显式的 BEGIN/COMMIT 命令把它划分成多个事务。此外，adb 只会打印出该字符串中最后一个SQL命令的结果。这和从文件中读取同一字符串或者把同一字符串传给adb的标准输出时的行为不同，因为那两种情况下 adb 会独立地发送每一个 SQL 命令。由于这种行为，把多于一个 SQL 命令放在 -c 字符串中通常会得到意料之外的结果。最好使用多个 -c 命令或者把多个命令输送给 adb 的标准输入，按照上文所说的使用 echo 或者通过一个 shell，例如：adb <<EOF \x SELECT * FROM foo; EOF

• --csv

  切换到 CSV（逗号分隔值）输出模式。 这相当于 \pset format csv。

• -d *dbname* --dbname=*dbname*

  指定要连接的数据库的名称。这等效于指定 dbname 为命令行上的第一个非选项参数。dbname 可以是连接字符串。 如果是这样，连接字符串参数将覆盖任何冲突的命令行选项。

• -e --echo-queries

  也把发送到服务器的所有 SQL 命令复制到标准输出。这等效于把变量 ECHO 设置为 queries。

• -E --echo-hidden

  回显\d以及其他反斜线命令生成的实际查询。可以用它来学习 adb 的内部操作。这等效于把变量 ECHO_HIDDEN 设置为 on。

• -f *filename* --file=*filename*

  从文件 filename 而不是标准输入中读取命令。这个选项可以被重复多次，也可以以任意顺序与 -c 选项组合。当 -c 或者 -f 被指定时，adb 不会从标准输入读取命令，直到它处理完序列中所有的 -c和 -f 选项之后终止。除此以外，这个选项很大程度上等价于元命令 \i。如果 *filename*是-（连字符），那么会读取标准输入直到遇见一个 EOF 指示或者 \q 元命令。这种方式可以用把自多个文件的输入组合成一种交互式输入。不过注意在这种情况下不会使用 Readline（很像指定了-n的情况）。使用这个选项与 adb < *filename*有细微的不同。通常，两种形式都可以做到我们所期望的，但是使用 -f 启用了一些好的特性，例如带有行号的错误消息。使用这个选项还有一丝机会可以降低启动开销。在另一方面，使用 shell 输入重定向的变体（理论上）保证会得到与手工输入时相同的输出。

• -F *separator* --field-separator=*separator*

  使用 separator 作为非对齐输出的域分隔符。这等效于 \pset fieldsep 或者 \f。

• -h *hostname* --host=*hostname*

  指定运行服务器的机器的主机名。如果这个值由一个斜线开始，它会被用作 Unix 域套接字的目录。

• -H --html

  切换到 HTML 输出模式。这等效于 \pset format html 或者 \H 命令。

• -l --list

  列出所有可用的数据库，然后退出。其他非连接选项会被忽略。这与元命令 \list 类似。在使用这个选项时，adb 将连接到数据库 antdb，除非在命令行上提及一个不同的数据（选项 -d 或非选项参数，可能是通过一个服务项，但不能通过一个环境变量）。

• -L *filename* --log-file=*filename*

  除了把所有查询输出写到普通输出目标之外，还写到文件 filename 中。

• -n --no-readline

  不使用 Readline 做行编辑并且不使用命令历史。在剪切和粘贴时，关掉 Tab 展开会有所帮助。

• -o *filename* --output=*filename*

  把所有查询输出放到文件 filename 中。这等效于命令 \o。

• -p *port* --port=*port*

  指定服务器用于监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展。默认是 PGPORT 环境变量的值，如果没有设置，则默认为编译时指定的端口号（通常是 6655）。

• -P *assignment* --pset=*assignment*

  以 \pset 的形式指定打印选项。注意，这里你必须用一个等号而不是空格来分隔名称和值。例如，要设置输出格式为 LaTeX，应该写成 -P format=latex。

• -q --quiet

  指定 adb 应该安静地工作。默认情况下，它会打印出欢迎消息以及多种输出。如果使用了这个选项，以上那些就都不会输出。在使用 -c 选项时，配合这个选项很有用。这等效于设置变量 QUIET 为 on。

• -R *separator* --record-separator=*separator*

  把 separator 用作非对齐输出的记录分隔符。这等效于 \pset recordsep 命令。

• -s --single-step

  运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户一个可以取消执行的选项。使用这个选项可以调试脚本。

• -S --single-line

  运行在单行模式中，其中新行会终止一个 SQL 命令，就像分号的作用一样。注意这种模式被提供给那些坚持使用它的用户，但是并不一定要使用它。特别地，如果在一行中混合了 SQL 和元命令，那对于没有经的用户来说，它们的执行顺序可能不总是那么清晰。

• -t --tuples-only

  关闭打印列名和结果行计数页脚等。这等效于 \t 或者 \pset tuples_only 命令。

• -T *table_options* --table-attr=*table_options*

  指定要替换 HTML table 标签的选项。详见 \pset tableattr。

• -U *username* --username=*username*

  作为用户 username 而不是默认用户连接到数据库（当然，你必须具有这样做的权限）。

• -v *assignment* --set=*assignment* --variable=*assignment*

  执行一次变量赋值，和 \set 元命令相似。注意你必须在命令行上用等号分隔名字和值（如果有）。要重置一个变量，去掉等号就行。要把一个变量置为空值，使用等号但是去掉值。这些赋值在命令行处理期间被完成，因此反映连接状态的变量将在稍后被覆盖。

• -V --version

  打印 adb 版本并且退出。

• -w --no-password

  从不发出一个口令提示。如果服务器要求口令认证并且口令不能从其他来源（例如一个 .pgpass 文件）获得，那么连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入口令。注意这个选项将对整个会话保持设置，并且因此它会影响元命令 \connect 的使用，就像初始的连接尝试那样。

• -W --password

  强制 adb 在连接到一个数据库之前提示要求一个口令，即使口令不会被使用。如果服务器需要口令认证并且口令不能从其他来源获得，例如 .pgpass 文件，adb 在任何情况下都会提示输入口令。 然而，adb 将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下值得用 -W 来避免额外的连接尝试。注意这个选项将对整个会话保持设置，并且因此它会影响元命令 \connect 的使用，就像初始的连接尝试那样。

• -x --expanded

  打开扩展表格式模式。这等效于 \x 或者 \pset expanded 命令。

• -X, --no-psqlrc

  不读取启动文件（要么是系统范围的 psqlrc 文件，要么是用户的 ~/.psqlrc 文件）。

• -z --field-separator-zero

  设置非对齐输出的域分隔符为零字节。这等效于 \pset fieldsep_zero。

• -0 --record-separator-zero

  设置非对齐输出的记录分隔符为零字节。例如，这对与 xargs -0 配合有关。这等效于 \pset recordsep_zero。

• -1 --single-transaction

  这个选项只能被用于与一个或者多个 -c 以及/或者 -f 选项组合。它会让 adb 在第一个上述选项之前发出一条 BEGIN 命令并且在最后一个上述选项之后发出一条 COMMIT 命令，这样就把所有的命令都包裹在一个事务中。这个选项可以保证要么所有的命令都成功地完成，要么不应用任何更改。如果命令本身包含 BEGIN、COMMIT 或者 ROLLBACK，这个选项将不会得到想要的效果。还有，如果当个命令不能在一个事务块中执行，指定这个选项将导致整个事务失败。

• -? --help[=*topic*]

  显示有关 adb 的帮助并且退出。可选的 topic 参数（默认为 options）选择要解释哪一部分的 adb：commands 描述 adb 的反斜线命令；options 描述可以被传递给 adb 的命令行选项；而 variables 则显示有关 adb 配置变量的帮助。

退出状态

如果 adb 正常完成，它会向 shell 返回 0。如果它自身发生一个致命错误（例如内存用完、找不到文件），它会返回 1。如果到服务器的连接出问题并且事务不是交互式的，它会返回 2。如果在脚本中发生错误，它会返回 3 并且变量 ON_ERROR_STOP 会被设置。

用法

连接到数据库

adb 是一个常规 AntDB 客户端应用。为了连接到数据库，你需要知道你的目标数据库的名称、主机名和该服务器的端口号，还有要作为哪个用户名连接。可以通过命令行选项告知adb这些参数，分别是 -d、-h、-p 以及 -U。如果发现一个参数不属于任何选项，它将被解释为数据库名称（如果已经给出数据库名称，就解释为用户名）。并非所有这些选项都是必需的，它们都有可用的默认值。如果省略主机名，adb 将通过一个 Unix 域套接字连接到本地主机上的服务器，或者通过 TCP/IP 连接到没有 Unix 域套接字的主机上的 localhost。默认端口号则在编译时决定。由于数据库服务器使用相同的默认值，大多数情况下你将不必指定端口。默认的用户名是你的操作系统用户名，它也会是默认的数据库名。注意你不一定能连接到任意用户名下的任何数据库。你的数据库管理员应该已经告知过你有关你的访问权限。

当默认值不是很符合实际时，可以把环境变量 PGDATABASE、PGHOST、PGPORT 以及 PGUSER 设置为适当的值，这样也能节省一些敲打键盘的工作。用一个 ~/.pgpass文 件来避免定期输入密码也很方便。

另一种指定连接参数的方法是用一个 conninfo 字符串或者一个 URI，它可以被用来替代数据库名。这种机制可以让我们对连接具有很广的控制权。例如：

$ adb "service=myservice sslmode=require"
$ adb postgresql://dbmaster:5433/mydb?sslmode=require

如果由于任何原因（例如权限不足、服务器没有在目标主机上运行等）导致连接无法建立，adb 将返回一个错误并且终止。

如果标准输入和标准输出都是一个终端，那么 adb 会把客户端编码设置成“auto”，这会使 adb 从区域设置（Unix 系统上的 LC_CTYPE 环境变量）中检测合适的客户端编码。如果这样不起作用，可以使用环境变量 PGCLIENTENCODING 覆盖客户端编码。

输入 SQL 命令

在正常操作时，adb 会提供一个提示符，该提示符是 adb 当前连接到的数据库名称后面跟上字符串=>。例如：

$ adb testdb
adb (13.1)
Type "help" for help.

testdb=>

在提示符下，用户可以键入 SQL 命令。正常情况下，当碰到一个表示命令终结的分号时，输入的行会被发送给服务器。一行的结束并不表示命令的完结。因此，为了清晰，可以把命令散布在多个行上。如果命令被发送并且执行而不产生错误，该命令的结果将会显示在屏幕上。

如果不可信用户对还没有采用安全方案使用模式的一个而数据库拥有访问，通过从 search_path 移除公共可写的方案来开始你的会话。人们可以在连接字符串中加入 options=-csearch_path= 或者在其他SQL命令之前发出 SELECT pg_catalog.set_config('search_path', '', false)。这种考虑并非专门针对 adb，它适用于每一种执行任意 SQL 命令的接口。

只要执行命令，adb 还会测试 LISTEN 和 NOTIFY 产生的异步通知。

虽然 C 风格的注释块会被传给服务器处理并且移除，adb 会自己移除掉 SQL 标准的注释。

元命令

你输入到 adb 中的任何以未加引用的反斜线开始的东西都是一个 adb 元命令，它们由 adb 自行处理。这些命令让 adb 对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。

adb 命令的格式是用反斜线后面直接跟上一个命令动词，然后是一些参数。参数与命令动词和其他参数之间用任意多个空白字符分隔开。

要在一个参数中包括空白，可以将它加上单引号。要在一个参数中包括一个单引号，则需要在文本中写上两个单引号。任何包含在单引号中的东西都服从与 C 语言中\n（新行）、\t（制表符）、\b（退格）、\r（回车）、\f（换页）、\digits（10 进制）以及\xdigits（16 进制）类似的替换规则。单引号内文本中的其他任何字符（不管它是什么）前面的反斜线都没有实际意义（会被忽略）。

如果在一个参数中出现一个未加引号的冒号（:）后面跟着一个 adb 变量名，它会被该变量的值替换。在其中描述的形式:'*variable_name*'和:"*variable_name*"也有同样的效果。:{?*variable_name*}语法允许测试一个变量是否被定义。它会被TRUE 或 FALSE 替换。用一个反斜线转义该冒号可以防止它被替换。

在一个参数中，封闭在反引号（```）中的文本会被当做一个传递给shell的命令行。该命令的输出（移除任何拖尾的新行）会替换反引号文本。在封闭在反引号的文本中，不会有特别的引号或者其他处理发生，:*variable_name*的出现除外，其中*variable_name*是一个会被其值替换的adb变量名。此外，Also, appearances of :'*variable_name*'的出现会被替换为该变量的值，而值会被适当地加以引用以变成一个单一shell命令参数（后一种形式几乎总是优先，除非你非常确定变量中有什么）。因为回车和换行字符在所有的平台上都不能被安全地引用，:'*variable_name*'形式会打印一个错误消息并且在这类字符出现在值中时不替换该变量值。

有些命令把 SQL 标识符（例如一个表名）当作参数。这些参数遵循 SQL 的语法规则：无引号的字母被强制变为小写，而双引号（"）可以保护字母避免大小写转换并且允许在标识符中包含空白。 在双引号内，成对的双引号会被缩减为结果名称中的单个双引号。例如，FOO"BAR"BAZ 会被解释成 fooBARbaz，而"A weird"" name"会变成A weird" name。

对参数的解析会在行尾或者碰到另一个未加引号的反斜线时停止。一个未加引号的反斜线被当做新元命令的开始。特殊的序列\\（两个反斜线）表示参数结束并且应继续解析 SQL 命令（如果还有）。使用这种方法，SQL 命令和 adb 命令可以被自由地混合在一行中。但是无论在何种情况中，元命令的参数都无法跨越一行。

很多元命令作用在当前查询缓冲区上。这就是一个缓冲区而已，它保存任何已经被键入但是还没有发送到服务器执行的 SQL 命令文本。这将包括之前输入的行以及在该元命令同一行上出现在前面的任何文本。

可以使用下列元命令：

• \a

  如果当前的表输出格式是非对齐的，则切换成对齐格式。如果不是非对齐格式，则设置成非对齐格式。保留这个命令是为了向后兼容性。更一般的方案请见 \pset。

• \c or \connect [ -reuse-previous=*on|off* ] [ *dbname* [ *username* ] [ *host* ] [ *port* ] | *conninfo* ]

  与一台 AntDB 服务器建立一个新连接。可以使用位置语法（数据库名称、用户、主机和端口中的一个或多个）指定要使用的连接参数，或者使用第 33.1.1 节中详细介绍的 conninfo 连接串。如果没有给出参数，则使用与以前相同的参数建立新连接。把*dbname、username、host* 或者 port 中的任何一个指定为-等价于省略该参数。新连接可以重用之前连接的连接参数；不仅是数据库名称、用户、主机和端口，还有其他设置，例如 sslmode。默认情况下，参数会在位置语法中重复使用，但在给出 conninfo 字符串时不会。传递 -reuse-previous=on 或 -reuse-previous=off 的第一个参数会覆盖该默认值。如果重复使用参数，则任何未明确指定为位置参数或在 conninfo 字符串中的参数都将从现有连接的参数中获取。一个例外是，如果 host 设置使用位置语法从其先前的值更改，则现有连接参数中存在的任何 hostaddr 设置都将被删除。当命令既不指定也不重用特定参数时，将使用 libpq 默认值。如果新连接成功地被建立，之前的连接会被关闭。如果连接尝试失败（错误的用户名、访问被拒绝等），在 adb 处于交互模式的情况下会保留之前的连接。但是当执行一个非交互式脚本时出现连接尝试失败，处理将被立即停止，并且报出一个错误。这种区别一方面可以帮助用户发现打字错误，另一方面也可以作为一种安全机制防止脚本在错误的数据库上执行动作。例子：=> \c mydb myuser host.dom 6432 => \c service=foo => \c "host=localhost port=6655 dbname=mydb connect_timeout=10 sslmode=disable" => \c -reuse-previous=on sslmode=require -- changes only sslmode => \c postgresql://tom@localhost/mydb?application_name=myapp

• \C [ *title* ]

  设置查询结果的任何表的标题，或者重置这类标题。这个命令等效于 \pset title *title*（这个命令的名称来自于“caption”，因为它之前只被用来在 HTML 表格中设置标题）。

• \cd [ *directory* ]

  把当前工作目录改为 directory。如果不带参数，则切换到当前用户的主目录。提示要打印当前的工作目录，可以使用\! pwd。

• \conninfo

  输出有关当前数据库连接的信息。

• \copy { *table* [ ( *column_list* ) ] } from { *'filename'* | program *'command'* | stdin | pstdin } [ [ with ] ( *option* [, ...] ) ] [ where *condition* ] \copy { *table* [ ( *column_list* ) ] | ( *query* ) } to { *'filename'* | program *'command'* | stdout | pstdout } [ [ with ] ( *option* [, ...] ) ]

  执行一次前端拷贝。这个操作会运行一个 SQL COPY 命令，不过不是服务器读取或者写入指定的文件，而是由 adb 读写文件并且把数据从本地文件系统导向服务器。这意味着文件的可访问性和权限是本地用户的而非服务器上的，并且不需要 SQL 超级用户权限。当program 被指定时，command 被 adb 执行并且传给 command 的数据或者从 command 传出的数据会在服务器和客户端之间流动。同样地，执行权限是本地用户的而非服务器上的，并且不需要 SQL 超级用户权限。对于\copy ... from stdin，数据行从发出该命令的同一来源读取，一直到读到\.或者数据流到达 EOF。这个选项可以用来填充内嵌在一个 SQL 脚本文件中的表。对于\copy ... to stdout，输出被发送到与adb命令输出相同的位置，并且 COPY *count*命令的状态不会被打印（因为它会被一个数据行搞乱）。要读/写 adb 的标准输入或者输出而不管当前命令的来源或者 \o 选项，可以写 from pstdin 或者 to pstdout。这个命令的语法和 SQL COPY 命令类似。所有除开数据来源/目的地的选项都和 COPY 指定的一样。因此，\copy 元命令由特殊的解析规则。与大部分其他元命令不同，该行的所有剩余部分总是会被当做 \copy 的参数，并且在参数中不会执行变量篡改以及反引号展开。提示获得与 \copy ... to 相同结果的另一种方法是使用 SQL COPY ... TO STDOUT 命令并使用 \g *filename*或\ g | *program *终止它。 与 \copy 不同，此方法允许命令跨越多行; 此外，可以使用变量插值和反引号扩展。提示这些操作不如带有文件或程序数据源或目标的 SQL COPY命令有效， 因为所有数据都必须通过客户端/服务器连接。 对于大量数据，SQL 命令可能更可取。

• \copyright

  显示 AntDB 的版权以及发布条款。

• \crosstabview [ *colV* [ *colH* [ *colD* [ *sortcolH* ] ] ] ]

  执行当前的查询缓冲区（像 \g 那样）并且在一个交叉表格子中显示结果。该查询必须返回至少三列。由 colV 标识的输出列会成为垂直页眉并且 colH 所标识的输出列会成为水平页眉。colD 标识显示在格子中的输出列。sortcolH 标识用于水平页眉的可选的排序列。每一个列说明可以是一个列编号（从 1 开始）或者一个列名。常用的 SQL 大小写折叠和引用规则适用于列名。如果省略，colV被当做列 1 并且 colH 被当做列 2。colH 必须和 colV 不同。如果没有指定 colD，那么在查询结果中必须正好有三列，并且*colV* 和 colH 之外的那一列会被当做 colD。垂直页眉显示为最左边的列，它包含列 colV 中找到的值，值的顺序和查询结果中的顺序相同，但是重复值会被移除。水平页眉显示为第一行，它包含列 colH 中找到的值，其中的重复值被移除。默认情况下，这些值会以查询结果中相同的顺序出现。但是如果给出了可选的 sortcolH 参数，它标识一个值必须为整数编号的列，并且来自 colH 的值将会根据相应的 sortcolH 值排序后出现在水平页眉中。在交叉表格子中，对于 colH 的每一个可区分的值 x 以及 colV 的每一个可区分的值 y，位于交叉点(x,y)的单元包含 colH 值为 x 且 colV 值为 y 的查询结果行中 colD 列的值。如果没有这样的行，则该单元为空。如果有多个这样的行，则会报告一个错误。

• \d[S+] [ *pattern* ]

  对于每一个匹配 pattern 的关系（表、视图、物化视图、索引、序列或者外部表）或者组合类型，显示所有的列、它们的类型、表空间（如果非默认表空间）以及任何诸如 NOT NULL 或者默认值的特殊属性。相关的索引、约束、规则以及触发器也会被显示。对于外部表，还会显示相关的外部服务器（下文的 Patterns 中定义了“匹配模式”）。对于某些类型的关系，\d 会为每一列显示额外的信息：对于序列会显示列值，对于索引显示被索引的表达式，对于外部表显示外部数据包装器选项。命令形式 \d+ 是一样的，不过会显示更多信息：与该表的列相关的任何注释，表中是否存在 OID，如果关系是视图则显示视图定义，非默认的 replica identity 设置。默认情况下只会显示用户创建的对象，提供一个模式或者 S 修饰符可以把系统对象包括在内。注意如果使用 \d 但不带有*pattern* 参数，它等价于 \dtvmsE，后者将显示所有可见的表、视图、物化视图、序列和外部表的列表。这纯粹是一种便利措施。

• \da[S] [ *pattern* ]

  列出聚集函数，以及它们的返回类型和它们所操作的数据类型。如果指定了 pattern，只显示名称匹配该模式的聚集。默认情况下只会显示用户创建的对象，提供一个模式或者S修饰符可以把系统对象包括在内。

• \dA[+] [ *pattern* ]

  列出访问方法。如果指定了 pattern，只显示名称匹配该模式的访问方法。如果在命令名称后面追加+，则与访问方法相关的处理器函数和描述也会和访问方法本身一起被列出。

• \dAc[+] [*access-method-pattern* [*input-type-pattern*]]

  列出运算符类。 如果指定了 access-method-pattern，则仅列出与名称与该模式匹配的访问方法关联的运算符类。 如果指定了 input-type-pattern，则仅列出与名称与该模式匹配的输入类型关联的运算符类。 如果将 + 附加到命令名称，则会列出每个运算符类别及其关联的运算符系列和所有者。

• \dAf[+] [*access-method-pattern* [*input-type-pattern*]]

  列出运算符系列。 如果指定了 access-method-pattern，则仅列出与名称与该模式匹配的访问方法关联的运算符系列。 如果指定了 input-type-pattern，则仅列出与名称与该模式匹配的输入类型关联的运算符系列。 如果将 + 附加到命令名称，则会列出每个运算符系列及其所有者。

• \dAo[+] [*access-method-pattern* [*operator-family-pattern*]]

  列出与运算符系列关联的运算符。 如果指定了 access-method-pattern，则仅列出与名称与该模式匹配的访问方法关联的运算符系列的成员。 如果指定了 operator-family-pattern，则仅列出名称与该模式匹配的运算符系列的成员。 如果将 + 附加到命令名称，则会列出每个运算符及其排序运算符系列（如果它是排序运算符）。

• \dAp[+] [*access-method-pattern* [*operator-family-pattern*]]

  列出与运算符系列相关的支持函数。 如果指定了 access-method-pattern，则仅列出与名称与该模式匹配的访问方法关联的运算符系列的函数。 如果指定了 operator-family-pattern，则仅列出名称与该模式匹配的运算符系列的函数。 如果将 + 附加到命令名称，则会详细显示函数及其实际参数列表。

• \db[+] [ *pattern* ]

  列出表空间。如果指定了 pattern，只显示名称匹配该模式的表空间。如果在命令名称后面追加+，则与表空间相关的选项、磁盘上的尺寸、权限以及描述也会和表空间本身一起被列出。

• \dc[S+] [ *pattern* ]

  列出字符集编码之间的转换。如果指定了 pattern，只列出名称匹配该模式的转换。默认情况下只会显示用户创建的对象，提供一个模式或者 S 修饰符可以把系统对象包括在内。如果在命令名称后面追加+，则每一个对象相关的描述也会被列出。

• \dC[+] [ *pattern* ]

  列出类型转换。如果指定了 pattern，只列出源类型和目标类型匹配该模式的转换。如果在命令名称后面追加+，则每一个对象相关的描述也会被列出。

• \dd[S] [ *pattern* ]

  显示约束、操作符类、操作符族、规则以及触发器类型对象的描述。所有其他注释可以通过那些对象类型相应的反斜线命令查看。\dd 显示匹配 pattern 的对象的描述，如果没有给出参数则显示合适类型的可见对象的描述。但是在任一种情况下都只列出具有描述的对象。默认情况下只会显示用户创建的对象，提供一个模式或者 S 修饰符可以把系统对象包括在内。对象的描述可以用 SQL 命令 COMMENT 创建。

• \dD[S+] [ *pattern* ]

  列出域。如果指定了 pattern，只有名称匹配该模式的域会被显示。默认情况下，只有用户创建的对象会被显示，可以提供一个模式或者 S 修饰符以包括系统对象。如果+被追加到命令名称上，每一个被列出的对象会带有其相关的权限和描述。

• \ddp [ *pattern* ]

  列出默认的访问权限设置。对那些默认权限设置已经被改变得与内建默认值不同的角色（以及模式，如果适用），为每一个角色（以及模式）显示一项。如果指定了 pattern，只列出角色名称或者模式名称匹配该模式的项。ALTER DEFAULT PRIVILEGES 命令被用来设置默认访问权限。

• \dE[S+] [ *pattern* ] \di[S+] [ *pattern* ] \dm[S+] [ *pattern* ] \ds[S+] [ *pattern* ] \dt[S+] [ *pattern* ] \dv[S+] [ *pattern* ]

  在这一组命令中，字母 E、i、m、s、t 和 v 分别对应着外部表、索引、物化视图、序列、表和视图。你可以以任何顺序指定这些字母中的任意一个或者多个，这样可以得到这些类型的对象的列表。例如，\dti会列出表和索引。如果在命令名称后面追加+，则会列出每个对象及其持久性状态（永久、临时或未记录）、磁盘上的物理大小以及相关的描述（如果有）。如果指定了 pattern，只列出名称匹配该模式的对象。默认情况下只会显示用户创建的对象，提供一个模式或者 S 修饰符可以把系统对象包括在内。

• \des[+] [ *pattern* ]

  列出外部服务器（助记：“外部服务器”）。如果指定了 pattern，只列出名称匹配该模式的那些服务器。如果使用了 \des+ 形式，将显示每个服务器的完整描述，包括该服务器的 访问权限、类型、版本、选项和描述。

• \det[+] [ *pattern* ]

  列出外部表（助记：“外部表”）。如果指定了 pattern，只列出表名称或者模式名称匹配该模式的项。如果使用了 \det+ 选项，一般选项和外部表描述也会被显示。

• \deu[+] [ *pattern* ]

  列出用户映射（助记：“外部用户”）。如果指定了 pattern，只列出用户名匹配该模式的那些映射。如果使用了 \deu+ 形式，有关每个映射的额外信息也会被显示。小心 \deu+ 可能也会显示远程用户的用户名和口令，所以要小心不要把它们泄露出去。

• \dew[+] [ *pattern* ]

  列出外部数据包装器（助记：“外部包装器”）。如果指定了 pattern，只列出名称匹配该模式的那些外部数据包装器。如果使用了 \dew+ 形式，外部数据包装器的访问权限、选项和描述也会被显示。

• \df[anptwS+] [ *pattern* ]

  列出函数，以及它们的结果数据类型、参数数据类型和函数类型，函数类型被分为“agg”（聚集）、“normal”、“procedure”、“trigger”以及“window”。如果要只显示指定类型的函数，可以在该命令上增加相应的字母 a、n、p、t 或者 w。如果指定了 pattern，只显示名称匹配该模式的函数。默认情况下只会显示用户创建的对象，提供一个模式或者 S修饰符可以把系统对象包括在内。如果使用了 \df+ 形式，则有关每个函数的额外信息也会被显示，包括易失性、并行安全性、拥有者、安全性分类、访问权限、语言、源代码和描述。提示如果要查找接收指定数据类型参数或者返回指定类型值的函数，可以使用分页器的搜索能力来滚动显示 \df 输出。

• \dF[+] [ *pattern* ]

  列出文本搜索配置。如果指定了 pattern，只显示名称匹配该模式的配置。如果使用了 \dF+ 形式，每种配置的完整描述也会被显示，包括底层的文本搜索解析器和用于每一种解析器记号类型的字典列表。

• \dFd[+] [ *pattern* ]

  列出文本搜索字典。如果指定了 pattern，只显示名称匹配该模式的字典。如果使用了 \dFd+ 形式，有关每一种选中的字典的额外信息也会被显示，包括底层的文本搜索模板和选项值。

• \dFp[+] [ *pattern* ]

  列出文本搜索解析器。如果指定了 pattern，只显示名称匹配该模式的解析器。如果使用了 \dFp+ 形式，每一种解析器的完整描述也会被显示，包括底层的函数和可识别的记号类型列表。

• \dFt[+] [ *pattern* ]

  列出文本搜索模板。如果指定了 pattern，只显示名称匹配该模式的模板。如果使用了 \dFt+ 形式，每一种模板有关的额外信息也会被显示，包括底层的函数名称。

• \dg[S+] [ *pattern* ]

  列出数据库角色（因为“用户”和“组”的概念已经被统一成“角色”，这个命令现在等价于 \du）。默认情况下只会显示用户创建的角色，提供一个模式或者 S 修饰符可以把系统角色包括在内。如果指定了 pattern，只列出名称匹配该模式的那些角色。如果使用了 \dg+ 形式，有关每种角色的额外信息也将被显示，当前这种形式会为角色增加显示注释。

• \dl

  这是\lo_list的一个别名，它显示大对象的列表。

• \dL[S+] [ *pattern* ]

  列出过程语言。如果指定了 pattern，只列出名称匹配该模式的语言。默认情况下只会显示用户创建的语言，提供一个模式或者 S 修饰符可以把系统对象包括在内。如果向命令名称追加+，则每一种语言会和它的调用处理器、验证器、访问权限以及它是否为系统对象一起列出。

• \dn[S+] [ *pattern* ]

  列出模式（名字空间）。如果指定了 pattern，只列出名称匹配该模式的模式。默认情况下只会显示用户创建的对象，提供一个模式或者 S 修饰符可以把系统对象包括在内。如果向命令名称追加+，每个对象会与它相关的权限及描述（如果有）一起被列出。

• \do[S+] [ *pattern* ]

  列出操作符及其操作数和结果类型。如果指定了 pattern，只列出名称匹配该模式的操作符。默认情况下只会显示用户创建的对象，提供一个模式或者S修饰符可以把系统对象包括在内。如果向命令名称追加+，有关每个操作符的额外信息也将被显示，当前只包括底层函数的名称。

• \dO[S+] [ *pattern* ]

  列出排序规则。如果指定了 pattern，只列出名称匹配该模式的排序规则。默认情况下只会显示用户创建的对象，提供一个模式或者 S 修饰符可以把系统对象包括在内。如果向命令名称追加+，每个排序规则将和它相关的描述（如果有）一起被列出。注意只有可用于当前数据库编码的排序规则会被显示，因此在同一个安装下的不同数据库中执行此命令可能会得到不同的结果。

• \dp [ *pattern* ]

  列出表、视图和序列，包括与它们相关的访问权限。如果指定了 pattern，只列出名称匹配该模式的表、视图以及序列。

• \dP[itn+] [ *pattern* ]

  列出分区关系。如果指定了 pattern，则仅列出名称与模式匹配的条目。 修改符 t（表）和 i（索引）可以追加到命令中，筛选要列出的关系类型。默认会列出分区表和索引。如果用了修饰符 n（“nested”）或指定了模式，则包括非根分区关系，并显示每个分区关系的父级的列。如果+被附加到命令名中，那么还会显示每个关系分区的大小总和，以及关系的描述。 如果 n 与_相结合，将显示两种大小：一种包含直接连接的叶分区的总大小，另一种显示所有分区的总大小，包括间接附加的子分区。

• \drds [ *role-pattern* [ *database-pattern* ] ]

  列出已定义的配置设置。这些设置可以是针对角色的、针对数据库的或者同时针对两者的。role-pattern 和 database-pattern 分别被用来选择要列出的角色和数据库。如果省略它们或者指定了*，则会列出所有设置，分别会包括针对角色和针对数据库的设置。ALTER ROLE 以及 ALTER DATABASE 命令可以用来定义一个角色以及一个数据库的配置设置。

• \dRp[+] [ *pattern* ]

  列出复制的 publication。如果指定有 pattern，只有那些名称匹配该模式的 publication 会被列出。如果+被追加到命令的名称上，与每个 publication 相关的表也会被显示。

• \dRs[+] [ *pattern* ]

  列出复制的订阅。如果指定有 pattern，只有那些名字匹配该模式的订阅才会被列出。如果+被追加到命令的名称上，订阅的额外属性会被显示。

• \dT[S+] [ *pattern* ]

  列出数据类型。如果指定了 pattern，只列出名称匹配该模式的类型。如果向命令名称追加+，每一种类型、其内部名称和尺寸、允许的值（如果是一种 enum 类型）以及相关权限会被一同列出。默认情况下只会显示用户创建的对象，提供一个模式或者 S 修饰符可以把系统对象包括在内。

• \du[S+] [ *pattern* ]

  列出数据库角色（因为“用户”和“组”的概念已经被统一成“角色”，这个命令现在等价于 \dg）。默认情况下只会显示用户创建的角色，提供一个模式或者 S 修饰符可以把系统角色包括在内。如果指定了 pattern，只列出名称匹配该模式的那些角色。如果使用了 \du+ 形式，有关每一种角色的额外信息也会被显示，当前只会多显示角色的注释。

• \dx[+] [ *pattern* ]

  列出已安装的扩展。如果指定了 pattern，只列出名称匹配该模式的那些扩展。如果使用了 \dx+ 形式，所有属于每个匹配扩展的对象会被列出。

• \dy[+] [ *pattern* ]

  列出事件触发器。如果指定了 pattern，只列出名称匹配该模式的事件触发器。如果在命令名称后面加上+，还会为每个列出的对象显示其相关的描述。

• \e或\edit [ *filename* ] [ *line_number* ]

  如果指定了 filename，则它是被编辑的文件，在编辑器退出后，该文件的内容会被拷贝到当前查询缓冲区中。如果没有给定 filename，当前查询缓冲区会被拷贝到一个临时文件中，并且接着以相同的方式编辑。或者，如果当前查询缓冲区为空，则最近被执行的查询会被拷贝到一个临时文件并且以同样的方式编辑。然后会根据 adb 的一般规则重新解析查询缓冲区的新内容，把整个缓冲区当作一个单一行来处理。任何完整的查询都会立即执行； 也就是说，如果查询缓冲区包含分号或以分号结尾，则执行该点之前的所有内容并将其从查询缓冲区中删除。查询缓冲区中剩余的内容将重新显示。输入分号或者 \g 会把它发送出去，输入 \r 会通过清除查询缓冲区来取消它。把缓冲区当作单一行主要会影响元命令：缓冲区中在一个元命令之后的任何东西都将被当作该元命令的参数，即便元命令之后的内容跨越多行也是如此。（因此不能以这种方式来制作使用元命令的脚本。应该使用 \i。）如果指定了一个行号，adb 将会把游标（注意不是服务器端的游标）定位到文件或者查询缓冲区的指定行上。注意如果给出了一个全是数字的参数，adb 就会假定它是行号而不是文件名。提示有关如何配置和自定义编辑器的信息。

• \echo *text* [ ... ]

  将经过计算的参数打印到标准输出，以空格分隔，后跟换行符。这可以用来在脚本的输出中间混入信息，例如：=> **\echo date``** Tue Oct 26 21:40:57 CEST 1999 如果第一个参数是一个没有加引号的 -n，则不会加上最后的新行（第一个参数也不会）。提示如果使用 \o 命令来重定向查询的输出，你可能希望使用 \qecho 来取代这个命令。另请参见 \warn。

• \ef [ *function_description* [ *line_number* ] ]

  这个命令会以一个 CREATE OR REPLACE FUNCTION或CREATE OR REPLACE PROCEDURE 命令的形式取出并且编辑指定函数或过程的定义。编辑的方式与 \edit 完全相同。在编辑器退出后，在编辑器退出后，则会立即执行更新的命令。否则重新显示；可以键入分号或者 \g 把它发出，也可以用 \r 取消之。目标函数可以单独用名称或者用名称和参数（例如 foo(integer, text)）来指定。如果有多于一个函数具有同样的名称，则必须给出参数的类型。如果没有指定函数，将会给出一个空白的 CREATE FUNCTION 模板来编辑。如果指定了一个行号，adb 将把游标定位在该函数体的指定行上（注意函数体通常不是开始于文件的第一行）。和大部分其他元命令不同，该行的整个剩余部分总是会被当作 \ef 的参数，并且在参数中不会执行变量篡改以及反引号展开。提示有关如何配置和自定义编辑器可见下面的 Environment。

• \encoding [ *encoding* ]

  设置客户端字符集编码。如果没有参数，这个命令会显示当前的编码。

• \errverbose

  以最详细的程度重复最近的服务器错误消息，就好像 VERBOSITY 被设置为 verbose 且 SHOW_CONTEXT 被设置为 always。

• \ev [ *view_name* [ *line_number* ] ]

  这个命令会以一个 CREATE OR REPLACE VIEW 的形式取出并且编辑指定函数的定义。编辑的方式与 \edit 完全相同。在编辑器退出后，如果向其添加分号，则会立即执行更新的命令。否则重新显示；可以键入分号或者 \g 把它发出，也可以用 \r 取消之。如果没有指定函数，将会给出一个空白的 CREATE VIEW 模板来编辑。如果指定了一个行号，adb 将把游标定位在该视图定义的指定行上。和大部分其他元命令不同，该行的整个剩余部分总是会被当作 \ev 的参数，并且在参数中不会执行变量篡改以及反引号展开。

• \f [ *string* ]

  设置用于非对齐查询输出的域分隔符。默认值是竖线（|）。它等效于 \pset fieldsep。

• \g [ (*option*=*value* [...]) ] [ *filename* ] \g [ (*option*=*value* [...]) ] [ |*command* ]

  把当前查询缓冲区发送给服务器执行。如果括号出现在 \g 之后，它们将包围以空格分隔的 option=value 格式选项子句列表，其解释方式与 \psetoption**value 命令相同，但仅在此查询期间生效。 在此列表中，= 符号周围不允许有空格，但选项子句之间需要空格。 如果省略 =value，命名的 option 的更改方式与 \pset option 相同，没有明确的 value。如果给定了 filename 或 |command 参数，则查询的输出将写入命名文件或通过管道传输到给定的 shell 命令，而不是像往常一样显示它。 仅当查询成功返回零个或多个元组时才会写入文件或命令，而不是在查询失败或者是不返回数据的 SQL 命令时写入。如果当前查询缓冲区为空，则重新执行最近一次被发送的查询。除了这种行为之外，没有参数的 \g 实际上等效于一个分号。对于参数，\g 提供了一个替代 \o 命令的“一次性”，另外还允许对通常由 \pset 设置的输出格式选项进行一次性调整。当最后一个参数以|开始时，则该行的所有剩余部分总是会被当做要执行的 command，并且在参数中不会执行变量篡改以及反引号展开。该行的剩余部分会被简单地按字面传给 shell。

• \gdesc

  显示当前查询缓冲区的结果的描述（即列名和数据类型）。查询不会被实际执行，不过，如果它含有某种类型的语法错误，该错误将被以通常的方式报出。如果当前查询缓冲区为空，则会描述最近被发送的查询。

• \gexec

  把当前查询缓冲区发送到服务器，然后该查询输出（如果有）中的每一行的每一列都当作一个要被执行的 SQL 语句。例如，要在my_table 的每一列上都创建一个索引：=> **SELECT format('create index on my_table(%I)', attname)** -> **FROM pg_attribute** -> **WHERE attrelid = 'my_table'::regclass AND attnum > 0** -> **ORDER BY attnum** -> **\gexec** CREATE INDEX CREATE INDEX CREATE INDEX CREATE INDEX 产生的查询会按照其所在行被返回的顺序执行，如果有多个列，则同一行中按照从左至右的顺序执行。NULL 域会被忽略。产生的查询会被原样发送给服务器处理，因此它们即不能是 adb 元命令，也不能包含 adb 变量引用。如果其中任何一个查询失败，剩余查询的执行将会继续，除非设置了 ON_ERROR_STOP。每个查询的执行都遵照 ECHO 的处理（在使用 \gexec 时，通常建议设置 ECHO为all 或者 queries）。查询日志、单步模式、计时以及其他查询执行特性也适用于每一个生成的查询。如果当前查询缓冲区为空，则会重新执行最近被发送的查询。

• \gset [ *prefix* ]

  把当前查询输入缓冲区发送给服务器并且将查询的输出存储在 adb 变量中。被执行的查询必须只返回一行。该行的每一列会被存储到一个单独的变量中，变量和该列的名字一样。例如：=> **SELECT 'hello' AS var1, 10 AS var2** -> **\gset** => **\echo :var1 :var2** hello 10 如果指定了一个 prefix，那么该字符串会被追加在该查询的输出列名称之前用来创建要使用的变量名：=> **SELECT 'hello' AS var1, 10 AS var2** -> **\gset result_** => **\echo :result_var1 :result_var2** hello 10 如果一个列的结果为 NULL，那么对应的变量会被重置而不是被设置。如果查询失败或者没有返回一行，则不会有任何变量被更改。如果当前查询缓冲区为空，则重新执行最近被发送的查询。

• \gx [ (*option*=*value* [...]) ] [ *filename* ] \gx [ (*option*=*value* [...]) ] [ |*command* ]

  \gx 等效于 \g，\gx 等价于 \g，除了它强制此查询的扩展输出模式，就好像 expanded=on 被包含在列表中 \pset 选项。请参考 \x。

• \h or \help [ *command* ]

  给出指定 SQL 命令的语法帮助。如果没有指定 command，则 adb 会列出可以显示语法帮助的所有命令。如果 command 是一个星号（*），则会显示所有 SQL 命令的语法帮助。与大部分其他元命令不同，该行的所有剩余部分总是会被当做 \help 的参数，并且在参数中不会执行变量篡改以及反引号展开。注意为了简化输入，由几个词构成的命令不需要被加上引号。因此，键入 \help alter table 是可以的。

• \H or \html

  开启 HTML 查询输出格式。如果 HTML 格式已经开启，这会把它切换回默认的对齐文本格式。这个命令是为了兼容性和方便，有关设置其他输出选项请见 \pset。

• \i or \include filename

  从文件 filename 读取输入并且把它当作从键盘输入的命令来执行。如果 filename 是-（连字符），那么会一直读取标准输入直到碰到一个 EOF 指示符或者 \q 元命令。这可以用来把交互式输入与文件输入混杂。注意只有在最外层激活了 readline 行为的情况下才将会使用 readline 行为。注意如果想在屏幕上看到被读入的行，必须把变量 ECHO 设置成 all。

• \if expression \elif expression \else \endif

  这一组命令实现可嵌套的条件块。条件块必须以一个 \if 开始并且以一个 \endif 结束。两者之间可能有任意数量的 \elif 子句，后面也可能有选择地跟着一个单一的 \else 子句。一般查询以及其他类型的反斜线命令可以出现在这些命令之间构成条件块。\if和 \elif 命令读取它们的参数并且将它们作为布尔表达式进行计算。如果表达式得到真则处理正常继续下去，否则会跳过下面的行直到到达一个匹配的 \elif、\else 或者 \endif。一旦一个 \if 或者 \elif测试成功，同一个块中后面的 \elif 命令的参数将不会被计算但会被当作为假。跟在一个 \else 后面的行只有在先前的匹配的 \if 或 \elif 成功时才被处理。就像任何其他反斜线命令参数一样，\if 或者 \elif 命令的 expression 参数服从变量篡改以及反引号展开。然后会像一个 on/off 选项变量的值一样来计算它。因此，对下列项无歧义、大小写无关的匹配都是有效的值：true、false、1、0、on、off、yes、no。例如，t、T 以及 tR 都将被认为是真。无法被正确计算为真或假的表达式将产生一个警告并且被当做假。正在被跳过的行还是会被正常地解析以标识查询和反斜线命令，但是查询不会被发送到服务器，并且非条件（\if、\elif、\else、\endif）反斜线命令会被忽略。条件命令会被检查以判断嵌套是否有效。被跳过的行中的变量引用不会被展开，并且也不会执行反引号展开。一个给定条件块中的所有反斜线命令必须出现在相同的源文件中。如果在所有的本地 \if 块被关闭之前，主输入文件或者一个 \include 进来的文件上就达到了 EOF，则 adb 将产生一个错误。这里是一个例子：-- 检查数据库中两个单独记录的存在性并且把结果存在单独的adb变量中 SELECT EXISTS(SELECT 1 FROM customer WHERE customer_id = 123) as is_customer, EXISTS(SELECT 1 FROM employee WHERE employee_id = 456) as is_employee \gset \if :is_customer SELECT * FROM customer WHERE customer_id = 123; \elif :is_employee \echo 'is not a customer but is an employee' SELECT * FROM employee WHERE employee_id = 456; \else \if yes \echo 'not a customer or employee' \else \echo 'this will never print' \endif \endif

• \ir or \include_relative filename

  \ir 命令类似于 \i，但是以不同的方式处理相对路径文件名。在交互模式中执行时，这两个命令的行为相同。不过，当被从脚本中调用时，\ir 相对于脚本所在的目录而不是根据当前工作目录来解释文件名。

• \l[+] or \list[+] [ *pattern* ]

  列出服务器中的数据库并且显示它们的名称、拥有者、字符集编码以及访问权限。如果指定了 pattern，则只列出名称匹配该模式的数据库。如果向命令名称追加+，则还会显示数据库的尺寸、默认表空间以及描述（尺寸信息只对当前用户能连接的数据库可用）。

• \lo_export *loid* *filename*

  从数据库中读取具有 OID loid 的大对象并且将它写入到 filename。注意这和服务器函数 lo_export 有微妙的不同，后者会以运行数据库服务器的用户权限来执行并且运行在服务器的文件系统上。提示使用 \lo_list 可以找出大对象的 OID。

• \lo_import *filename* [ *comment* ]

  把该文件存储到 AntDB 大对象。可选地，它可以把给定的注释关联到该对象。例如：foo=> **\lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'** lo_import 152801该响应表示该大对象得到的对象 ID 是 152801，未来可以用这个 ID 来访问这个新创建的大对象。为了便于阅读，推荐总是给每一个对象都关联人类可读的注释。OID 和注释都可以用\lo_list 命令查看。注意这个命令和服务器端的 lo_import 有微妙的不同，因为它以本地文件系统上的本地用户的身份运行，而不是服务器用户和文件系统。

• \lo_list

  显示当前存储在数据库中的所有 AntDB 大对象，同时显示它们的任何注释。

• \lo_unlink *loid*

  从数据库中删除 OID 为 loid 的大对象。提示使用 \lo_list 可以找出该大对象的 OID。

• \o or \out [ *filename* ] \o or \out [ |*command* ]

  安排把未来的查询结果保存到文件 filename 中或者用管道导向到 shell 命令 command。如果没有指定参数，查询输出会被重置到标准输出。如果该参数以|开始，则该行的所有剩余部分总是会被当做要执行的 command，并且在参数中不会执行变量篡改以及反引号展开。该行的剩余部分会被简单地按字面传给 shell。“查询结果”包括从数据库服务器得到的所有表、命令响应和提示，还有查询数据库的各种反斜线命令（如 \d）的输出，但不包括错误消息。提示要在查询结果之间混入文本输出，可以使用 \qecho。

• \p or \print

  把当前查询缓冲区打印到标准输出。如果当前查询缓冲区为空，会打印最近被执行的查询。

• \password [ *username* ]

  更改指定用户（默认情况下是当前用户）的口令。这个命令会提示要求输入新口令、对口令加密然后把加密后的口令作为一个 ALTER ROLE 命令发送到服务器。这确保新口令不会以明文的形式出现在命令历史、服务器日志或者其他地方。

• \prompt [ *text* ] *name*

  提示用户提供一个文本用于分配给变量 name。可以指定一个可选的提示字符串 text（对于多个词组成的提示，把文本包裹在单引号中）。默认情况下，\prompt 使用终端进行输入和输出。不过，如果使用了 -f 命令行开关，\prompt 会使用标准输入和标准输出。

• \pset [ *option* [ *value* ] ]

  这个命令设置影响查询结果表输出的选项。option 表示要设置哪个选项。value 的语义取决于选中的选项。对于某些选项，如果省略 value 会导致该选项值被切换或者被重置，具体是哪些选项可见特定选项的描述。如果没有上面提到的那种行为，那么省略*value* 只会导致当前设置被显示。不带任何参数的 \pset 显示所有打印选项的当前状态。可调整的打印选项有：bordervalue 必须是一个数字。通常，数字越大，表格就会有更多的边框和线条，但具体要看是哪一种格式。在 HTML 格式中，这会直接被转换成border=...属性。在大部分其他格式中，只有值 0（没有边框）、1（内部分隔线）和 2（表格边框）有意义，并且 2 以上的值会被视为与 border = 2 相同。latex和 latex-longtable 格式会额外地允许一个值 3 表示在数据行之间增加分隔线。columns 为wrapped格式设置目标宽度，还有扩展自动模式中决定输出是否足够多到需要分页器或者切换到垂直显示的宽度限制。零（默认）导致目标宽度由环境变量 COLUMNS 所控制，如果没有设置COLUMNS则使用检测到的屏幕宽度。此外，如果 columns 为零则 wrapped 格式只影响屏幕输出。如果 columns 为非零则文件和管道输出也会被包裹成该宽度。csv_fieldsep 规定要用于 CSV 输出格式的字段分隔符。如果分隔符出现在字段的值中，则该字段遵循标准 CSV 规则在双引号中输出。默认值为逗号。expanded (or x)如果 value 被指定，它必须是 on 或者 off，它们分别会启用或者禁用扩展模式，也可以是 auto。如果 value 被省略，则该命令会在开启和关闭设置之间切换。当扩展模式被启用时，查询结果被显示在两列中，第一列是列名而第二列是列值。如果在通常的“水平”模式中数据不适合屏幕，则可以用这种模式。在自动设置中，只要查询输出有多于一列并且比屏幕宽，就会使用扩展模式。否则，将使用常规模式。只有在对齐格式和 wrapped 格式中自动设置才有效。在其他格式中，它的行为总是像扩展模式被关闭一样。fieldsep指定在非对齐输出格式中使用的域分隔符。用那种方式，用户可以创建 tab 分隔的输出，这种形式其他程序可能更喜欢。要设置 tab 为域分隔符，可以键入 \pset fieldsep '\t'。默认的域分隔符是'|'（一个竖线）。fieldsep_zero 把用在非对齐输出格式中的域分隔符设置为一个零字节。footer 如果 value 被指定，它必须是 on 或者 off，它们分别会启用或者禁用表格页脚（(*n* rows)计数）的显示。如果 value 被省略，则该命令会切换页脚显示为打开或者关闭。format 设置输出格式为下列的一种： aligned，asciidoc，csv，html，latex，latex-longtable，troff-ms，unaligned或 wrapped。允许唯一的缩写。aligned 格式是标准,人类可阅读的、良好格式化的文本输出；这是默认值。unaligned格式把一个数据行的所有列都写在一行上，之间用当前活动的域分隔符分隔。这可用于生成意图由其他程序读取的输出，例如，tab 分隔或者逗号分隔格式。 但是，如果字段分隔符出现在列的值中，则不专门处理该字符；因此 CSV 格式可能更适合此类目的。csv 格式写入以逗号分隔的列值，应用引号规则描述在 RFC 4180。 此输出与服务器 COPY 命令的 CSV 格式兼容。 除非 tuples_only 参数为 on，否则将生成具有列名称的标头行。不打印标题和页脚。 每行都由系统相关的行尾字符结束，该字符通常是类似 Unix 的系统的单一换行符（\n）或应用于微软Windows 的回车和换行顺序（\r\n）。 除了逗号之外的\pset csv_fieldsep字段分隔符，还可以使用 \pset csv_fieldsep 选择。wrapped 格式和 aligned 相似，但是前者会把过宽的数据值分成多个行以便输出能够适合目标行的宽度。目标行的宽度由columns 选项决定。注意adb将不会尝试对列头部标题进行换行，因此如果列头部需要的总宽度超过目标宽度，wrapped格式的行为就变得和 aligned 一样了。The asciidoc，html，latex，latex-longtable 和 troff-ms 格式分别用相应的标记语言把要输出的表格放在文档中。不过它们的输出并不是完整的文档。 这在HTML中也许不重要，但是在 LaTeX 中必须有完整的文档包装器。 latex 格式使用 LaTeX 的 tabular 环境。 latex-longtable 格式需要 LaTeX、longtable 和 booktabs 包。linestyle 设置边框线的绘制样式为 ascii、old-ascii 或者 unicode 之一。允许不产生歧义的缩写（这意味着一个字母就足够了）。默认的设置是 ascii。这个选项只影响 aligned 以及 wrapped 输出格式。ascii 样式使用纯 ASCII 字符。数据中的新行使用一个+符号在右手边的空白处显示。当在 wrapped 格式中包裹两行中间没有新行字符的数据时，会在第一行右手边空白处显示一个点号（.），并且在下一行的左手边空白处也显示一个点号（.）。old-ascii 样式使用纯 ASCII 字符，使用 AntDB 8.4 及更早版本中用过的格式化样式。数据中的新行使用:符号来代替左手边的列分隔符显示。在包裹两行中间没有新行字符的数据时，会用一个;符号取代左手边的列分隔符。unicode 样式使用 Unicode 的方框绘制字符。数据中的新行会使用一个回车符号显示在右手边的空白处。在包裹两行中间没有新行字符的数据时，会在第一行的右手边空白处显示一个省略号，并且在下一行的左手边空白处也显示一个省略号。当border 设置大于零时，linestyle 选项也决定边框线用什么字符绘制。纯ASCII字符到处都可以使用，但是在识别 Unicode 字符的显示上使用 Unicode 字符会更好看。null 设置要用来替代空值被打印的字符串。默认是什么也不打印，对于一个空字符串这很容易弄错。例如，有人可能更想用 \pset null '(null)'。numericlocale 如果 value 被指定，它必须是 on 或者 off，它们将分别启用或者禁用一个与区域相关的字符来分隔数字和左边的十进制标记。如果*value*被省略，该命令会在常规输出和区域相关的数字输出之间切换。pager 控制对查询和 adb 的帮助输出使用分页器程序。如果环境变量 PSQL_PAGER 或 PAGER 被设置，输出会被用管道输送到指定的程序。否则将使用与平台相关的默认分页器程序（例如 more）。如果 pager 选项被设为 off，则不会使用分页器程序。如果 pager 选项被设为 on，则会在适当的时候使用分页器，即当输出到终端并且无法适合屏幕时就会使用分页器。pager选项也可以被设置为 always，这会导致对所有的终端输出都是用分页器而不管输出是否适合屏幕。不带 value 的 \pset pager 会切换分页器开、关状态。pager_min_lines 如果 pager_min_lines 被设置为一个大于页面高度的数字，在至少这么多输出行被显示之前都不会调用分页器程序。默认设置为 0。recordsep 指定用在非对齐输出格式中的记录（行）分隔符。recordsep_zero 把用在非对齐输出格式中的记录分隔符设置为一个零字节。tableattr (or T)在 HTML 格式中，这会指定要放在 table 标记内的属性。例如，这可能是 cellpadding 或者 bgcolor。注意你可能不想在这里指定 border，因为那由 \pset border 负责。如果没有给出 value，则表属性会被重置。在 latex-longtable 格式中，这个选项控制每个包含左对齐数据类型的列的宽度比例。这个选项的值是一个由空格分隔的值列表，例如'0.2 0.2 0.6'。没有指定的输出列会使用最后一个指定的值。title (or C)设置用于任何后续被打印表的表标题。这可以用来给输出加上描述性的标签。如果没有给出 value，这个标题会被复原。tuples_only (or t)如果 value 被指定，它必须是 on或者 off，这个选项将启用或者禁用只显示元组的模式。如果 value 被省略，则该命令会在常规输出和只显示元组输出之间切换。常规输出包括列头、标题以及多种页脚之类的额外信息。在只显示元组的模式中，只会显示实际的表数据。unicode_border_linestyle 设置 unicode 线型的边框绘制风格为 single 或者 double 之一。 unicode_column_linestyle 设置 unicode 线型的列绘制风格为 single 或者 double 之一。unicode_header_linestyle 设置unicode 线型的页眉绘制风格为 single 或者 double 之一。这些不同格式的外观可以在Examples小节的图示中看到。提示 \pset 有多种快捷命令。请参见 \a、\C、\f、\H、\t、\T 以及 \x。

• \q or \quit

  退出 adb 程序。在一个脚本文件中，只有该脚本的执行会被终止。

• \qecho *text* [ ... ]

  这个命令和 \echo 一样，不过输出将被写到 \o 所设置的查询输出通道。

• \r or \reset

  重置（清除）查询缓冲区。

• \s [ *filename* ]

  打印 adb 的命令行历史到 filename。如果省略 filename，该历史会被写入到标准输出（如果适用则使用分页器）。如果编译adb时没有加上 Readline 支持，则这个命令不可用。

• \set [ *name* [ *value* [ ... ] ] ]

  设置 adb 变量 name 为 value，如果给出了多于一个值，则把该变量的值设置为所有给出的值的串接。如果只给了一个参数，该变量会被设置为空字符串值。要重置一个变量，可以使用 \unset 命令。不带任何参数的 \set 显示所有当前设置的 adb 变量的名称和值。合法的变量名可以包含字母、数字和下划线。详见下文的 Variables。变量名是大小写敏感的。某些变量是特殊的，它们控制adb 的行为或者会被自动设置以反映连接状态。这些变量在下文的 Variables 中记录。注意这个命令和 SQL 命令 SET 无关。

• \setenv *name* [ *value* ]

  把环境变量 name 设置为 value，如果没有提供 value，则会重置该环境变量。例如：testdb=> **\setenv PAGER less** testdb=> **\setenv LESS -imx4F**

• \sf[+] *function_description*

  这个命令以一个 CREATE OR REPLACE FUNCTION 命令或者 CREATE OR REPLACE PROCEDURE 命令取出并且显示指定函数或者过程的定义。定义会被打印到当前的查询输出渠道，就像 \o 所作的那样。目标函数可以单独用名称指定，也可以用名称和参数指定，例如 foo(integer, text)。如果有多于一个函数具有相同的名字，则必须给出参数的类型。如果向命令名称追加+，那么输出行会被编号，函数体的第一行会被编为 1。与大部分其他元命令不同，该行的所有剩余部分总是会被当做 \sf 的参数，并且在参数中不会执行变量篡改以及反引号展开。

• \sv[+] *view_name*

  这个命令以一个 CREATE OR REPLACE VIEW 命令取出并且显示指定视图的定义。定义会被打印到当前的查询输出渠道，就像 \o所作的那样。如果在命令名称上追加+，那么输出行会从 1 开始编号。与大部分其他元命令不同，该行的所有剩余部分总是会被当做\sv的参数，并且在参数中不会执行变量篡改以及反引号展开。

• \t

  切换输出列名标题和行计数页脚的显示。这个命令等效于 \pset tuples_only，提供它只是为了使用方便而已。

• \T *table_options*

  指定在 HTML 输出格式中，要放在 table 标签内的属性。这个命令等效于 \pset tableattr *table_options*。

• \timing [ *on* | *off* ]

  如果给出一个参数，这个参数用来打开或者关闭对每个 SQL 语句执行时长的显示。如果没有参数，则在打开和关闭之间切换。显示的数据以毫秒为单位，超过 1 秒的区间还会被显示为“分钟:秒”的格式，如果必要还会加上小时和日的字段。

• \unset *name*

  重置（删除）adb 变量 name。大部分控制 adb 行为的变量不能被重置，相反，\unset 命令会被解释为把它们设置为其默认值。

• \w or \write filename \w or \write |command

  把当前查询缓冲区写到文件 filename 或者用管道导出到 shell 命令 command。如果当前查询缓冲区为空，则写最近被执行的查询。如果参数以|开始，则该行的整个剩余部分会被当做要执行的 command，并且在参数中不会执行变量篡改以及反引号展开。该行的剩余部分会被简单地按字面传递给 shell。

• \warn *text* [ ... ]

  此命令与 \echo 相同，只是输出将写入 adb 的标准错误通道，而不是标准输出。

• \watch [ *seconds* ]

  反复执行当前的查询缓冲区（就像 \g 那样）直到被中止或者查询失败。两次执行之间等待指定的秒数（默认是 2 秒）。显示每个查询结果时带上一个由 \pset title 字符串（如果有）、从查询开始起的时间以及延时间隔组成的页眉。如果当前查询缓冲区为空，则会重新执行最近被发送的查询。

• \x [ *on* | *off* | *auto* ]

  设置或者切换扩展表格格式化模式。究其本身而言，这个命令等效于 \pset expanded。

• \z [ *pattern* ]

  列出表、视图和序列，以及它们相关的访问权限。如果指定了 pattern，则只会列出名称匹配该模式的表、视图和序列。这是\dp（“display privileges”）的一个别名。

• \! [ *command* ]

  如果没有参数，就跳出到一个子 shell，当子 shell 退出时 adb 会继续。如果有一个参数，则执行 shell 命令 command。与大部分其他元命令不同，该行的所有剩余部分总是会被当做\!的参数，并且在参数中不会执行变量篡改以及反引号展开。该行的剩余部分会被简单地按字面传递给 shell。

• \? [ *topic* ]

  显示帮助信息。可选的 topic 参数（默认是 commands）选择解释 adb 的哪一部分：commands 表示 adb 的反斜线命令；options 表示可以传递给 adb 的命令行选项；而 variables 显示有关 adb 配置变量的帮助。

• \;

  反斜线分号并非和前述命令相同的元命令，它只是会把一个分号加入到查询缓冲区且不会进一步执行。通常，只要adb达到了命令结束的分号，它就将分发一个 SQL 命令给服务器，即使在当前行上还留有更多输入。因此，例如输入 select 1; select 2; select 3;将导致三个 SQL 命令被逐个发送给服务器，在继续到下一个命令前会显示每一个命令的结果。不过，被输入为\;的分号将不会触发命令处理，这样在它之前的命令以及其后的命令实际上会被组合在一个请求中发送给服务器。例如 select 1\; select 2\; select 3;会导致在到达非反斜线分号时用一个单一的请求把三个 SQL 命令发送给服务器。服务器会把这样一个请求当作单一的事务执行，除非该字符串中有显式的 BEGIN/COMMIT 命令把它划分成多个事务。adb 对每个请求仅打印出它接收到的最后一个查询结果。在这个例子中，尽管所有三个 SELECT 确实都被执行了，但 adb 只会打印出 3。

模式

很多 \d 命令都可以用一个 pattern 参数来指定要被显示的对象名称。在最简单的情况下，模式正好就是该对象的准确名称。在模式中的字符通常会被变成小写形式（就像在 SQL 名称中那样），例如 \dt FOO将会显示名为 foo 的表。就像在 SQL 名称中那样，把模式放在双引号中可以阻止它被转换成小写形式。如果需要在一个模式中包括一个真正的双引号字符，则需要把它写成两个相邻的双引号，这同样是符合 SQL 引用标识符的规则。例如，\dt "FOO""BAR" 将显示名为FOO"BAR（不是 foo"bar）的表。和普通的 SQL 名称规则不同，你不能只在模式的一部分周围放上双引号，例如 \dt FOO"FOO"BAR 将会显示名为 fooFOObar 的表。

只要 pattern 参数被完全省略，\d命令会显示在当前 schema 搜索路径中可见的全部对象 — 这等价于用*作为模式（如果一个对象所在的 schema 位于搜索路径中并且没有同类且同名的对象出现在搜索路径中该 schema 之前的 schema 中，则说该对象是可见的。这表示可以直接用名称引用该对象，而不需要用 schema 来进行限定）。要查看数据库中所有的对象而不管它们的可见性，可以把*.*用作模式。

如果放在一个模式中，*将匹配任意字符序列（包括空序列），而?会匹配任意的单个字符（这种记号方法就像 Unix shell 的文件名模式一样）。例如，\dt int*会显示名称以 int 开始的表。但是如果被放在双引号内，*和?就会失去这些特殊含义而变成普通的字符。

包含一个点号（.）的模式被解释为一个 schema 名称模式后面跟上一个对象名称模式。例如，\dt foo*.*bar*会显示名称以 foo 开始的 schema 中所有名称包括 bar 的表。如果没有出现点号，那么模式将只匹配当前 schema 搜索路径中可见的对象。同样，双引号内的点号会失去其特殊含义并且变成普通的字符。

高级用户可以使用字符类等正则表达式记法，如[0-9]可以匹配任意数字。所有的正则表达式特殊字符都按照规则工作，以下字符除外：.会按照上面所说的作为一种分隔符，*会被翻译成正则表达式记号.*，?会被翻译成.，而$则按字面意思匹配。根据需要，可以通过书写?、(*R*+|)、(*R*|)和*R*?来分别模拟模式字符.、*R**和*R*?。$不需要作为一个正则表达式字符，因为模式必须匹配整个名称，而不是像正则表达式的常规用法那样解释（换句话说，$会被自动地追加到模式上）。如果不希望该模式的匹配位置被固定，可以在开头或者结尾写上*。注意在双引号内，所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。还有，在操作符名称模式中（即作为 \do 的参数），正则表达式特殊字符也按照字面意思进行匹配。

高级特性

变量

adb 提供了和普通 Unix 命令 shell 相似的变量替换特性。变量简单来说就是一对名称/值，其中值可以是任意长度的任意字符串。名称必须由字母（包括非拉丁字母）、数字和下划线构成。

要设置一个变量，可以使用 adb 的元命令 \set。例如，

testdb=> \set foo bar

会设置foo为值bar。要检索该变量的内容，可以在名称前放一个分号，例如：

testdb=> \echo :foo
bar

如果调用 \set 时没有第二个参数，该变量会被设置为一个空字符串值。要重置（即删除）一个变量，可以使用命令 \unset。要显示所有变量的值，在调用 \set 时不带任何参数即可。

注意

\set 的参数服从与其他命令相同的替换规则。因此可以构造有趣的引用，例如\ set :foo 'something'以及分别得到Perl或者PHP的“软链接”或者“可变变量”。不幸的是，这些构造出来的东西并没有什么用处。在另一方面，\set bar :foo 是一种很好的拷贝变量的方法。

有一些变量会被 adb 特殊对待。它们表示特定的选项设置，运行时这类选项设置可以通过修改该变量的值来改变，或者在某些情况下它们表示 adb 的可更改的状态。按照惯例，所有被特殊对待的变量的名称由全部大写形式的 ASCII 字母（还有可能是数字和下划线）组成。为了确保未来最大的兼容性，最好避免把这类变量名用于自己的目的。

控制 adb 行为的变量通常不能被重置或者设置为无效值。允许 \unset 命令，但它会被解释为将变量设置为它的默认值。没有第二参数的 \set 命令会被解释为将变量设置为 on（对于接受该值的控制变量），对不接受该值的变量则会拒绝这个命令。此外，接受值 on 和off 的控制变量也能接受其他常见的布尔值拼写方式，例如 true 和 false。

被特殊对待的变量是：

• AUTOCOMMIT

  在被设置为 on（默认）时，每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交，必须输入一个 BEGIN 或者START TRANSACTION SQL 命令。当被设置为 off 或者被重置时，在显式发出 COMMIT 或者 END 之前，SQL 命令不会被提交。自动提交打开模式会为你发出一个隐式的 BEGIN，这会发生在任何不在一个事务块中且本身即不是BEGIN及其他事务控制命令且不是无法在事务块中执行的命令（例如 VACUUM）之前。注意在自动提交关闭模式中，必须通过 ABORT 或者 ROLLBACK 显式地放弃任何失败的事务。还要记住，如果退出会话时没有提交，则所有的工作都会丢失。注意自动提交打开模式是 AntDB 的传统行为，但是自动提交关闭模式更接近于 SQL 的规范。如果更喜欢自动提交关闭模式，可以在系统级的 pslqrc 文件或者个人的 ~/.psqlrc 文件中设置它。

• COMP_KEYWORD_CASE

  确定在补全一个 SQL 关键词时要使用的大小写形式。如果被设置为 lower 或者 upper，补全后的词将分别是小写或者大写形式。如果被设置为 preserve-lower 或者 preserve-upper（默认），补全后的词将会保持该词已输入部分的大小写形式，但是如果被补全的词还没有被输入，则它会被分别补全成小写或者大写形式。

• DBNAME

  当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量（包括程序启动时），但是可以被更改或者重置。

• ECHO

  如果被设置为 all，所有非空输入行会被按照读入它们的样子打印到标准输出（不适用于交互式读取的行）。要在程序开始时选择这种行为，可以使用开关 -a。如果被设置为 queries，adb 会 在发送每个查询给服务器时将它们打印到标准输出。选择这种行为的开关是 -e。如果被设置为 errors，那么只有失败的查询会被显示在标准错误输出上。这种行为的开关是 -b。如果被重置或者设置为 none（默认值）则不会显示任何查询。

• ECHO_HIDDEN

  当这个变量被设置为 on 且一个反斜线命令查询数据库时，相应的查询会被先显示。这种特性可以帮助我们学习 AntDB 的内部并且在自己的程序中提供类似的功能（要在程序开始时选择这种行为，可以使用开关 -E）。如果把这个变量设置为值 noexec，则对应的查询只会被显示而并不真正被发送给服务器执行。默认值是 off。

• ENCODING

  当前的客户端字符集编码。每一次你连接到一个数据库（包括程序启动）时以及当你用 \encoding 更改编码时，这个变量都会被设置，但它可以被更改或者重置。

• ERROR

  如果上一个 SQL 查询失败则为 true，如果成功则是 false。另见 SQLSTATE。

• FETCH_COUNT

  如果这个变量被设置为一个大于零的整数值，SELECT 查询的结果会以一组一组的方式取出并且显示（而不是像默认的那样把整个结果集拿到以后再显示），每一组就会包括这么多个行。因此，这种方式只会使用有限的内存量，而不管整个结果集的大小。在启用这个特性时，通常会使用 100 到 1000 的设置。记住在使用这种特性时，一个查询可能会在已经显示了一些行之后失败。提示尽管可以把这种特性用于任何的输出格式，但是默认的 aligned 格式看起来会比较糟糕，因为每一组的 FETCH_COUNT 个行将被单独格式化，这就会导致不同的行组的列宽不同。其他的输出格式会更好。

• HIDE_TABLEAM

  如果此变量设置为 true，则不显示表的访问方法的详细信息。这主要用于回归测试。

• HISTCONTROL

  如果这个变量被设置为 ignorespace，则以一个空格开始的行不会被放入到历史列表中。如果被设置为值 ignoredups，则匹配之前的历史行的行不会被放入。值 ignoreboth组合了上述两种值。如果被重置或者被设置为 none（默认值），所有在交互模式中被读入的行都会保存在历史列表中。注意这个特性是可耻地从 Bash 抄袭过来的。

• HISTFILE

  该文件名将被用于存储历史列表。如果被重设，文件名将从 PSQL_HISTORY 环境变量中取得。如果该环境变量也没有被设置，则默认值是 ~/.psql_history，在 Windows 上是 %APPDATA%\postgresql\psql_history。例如，\set HISTFILE ~/.psql_history- :DBNAME 放在 ~/.psqlrc 中将会导致 adb 为每一个数据库维护一个单独的历史。注意这个特性是可耻地从Bash 抄袭过来的。

• HISTSIZE

  存储在命令历史中的最大命令数（默认值是 500）。如果被设置为一个负值，则不会应用限制。注意这个特性是可耻地从 Bash 抄袭过来的。

• HOST

  当前连接到的数据库服务器端口。每次连接到一个数据库时都会设置该变量（包括程序启动时），但是可以被更改或者重置。

• IGNOREEOF

  如果被设置为 1 或者更小，向一个 adb 的交互式会话发送一个 EOF 字符（通常是 Control+D）将会终止应用。如果设置为一个较大的数字值，则必须键入多个连续的 EOF 字符才能让交互式会话终止。如果该变量被设置为一个非数字值，则它会被解释为 10。默认值为 0。注意这个特性是可耻地从 Bash 抄袭过来的。

• LASTOID

  最后被影响的 OID 的值，这可能会由 INSERT 或者 \lo_import 命令返回。这个变量只保证在下一个 SQL 命令被显示完之前有效。 AntDB 服务器从 12 版开始不再支持 OID 系统列，因此，在面向此类服务器时，跟随在 INSERT 后面的 LASTOID 将始终为 0。

• LAST_ERROR_MESSAGE LAST_ERROR_SQLSTATE

  当前 adb 会话中最近一个失败查询的主错误消息和相关的 SQLSTATE 代码，如果在当前会话中没有发生错误，则是一个空字符串和 00000。

• ON_ERROR_ROLLBACK

  当被设置为 on 时，如果事务块中的一个语句产生一个错误，该错误会被忽略并且该事务会继续。当被设置为 interactive 时，只在交互式会话中忽略这类错误，而读取脚本文件时则不会忽略错误。当被重置或者设置为 off（默认值）时，事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理是在事务块的每个命令之前都为你发出一个隐式的 SAVEPOINT，然后在该命令失败时回滚到该保存点。

• ON_ERROR_STOP

  默认情况下，出现一个错误后命令处理会继续下去。当这个变量被设置为 on 后，出现错误后命令处理会立即停止。在交互模式下，adb 将会返回到命令提示符；否则，adb将会退出并且返回错误代码 3 来把这种情况与致命错误区分开来，致命错误会被报告为错误代码 1。在两种情况下，任何当前正在运行的脚本（顶层脚本以及任何它已经调用的其他脚本）将被立即中止。如果顶层命名字符串包含多个 SQL 命令，将在当前命令处停止处理。

• PORT

  当前连接到的数据库服务器端口。每次连接到一个数据库时都会设置该变量（包括程序启动时），但是可以被更改或者重置。

• PROMPT1 PROMPT2 PROMPT3

  这些变量指定 adb 发出的提示符的模样。

• QUIET

  把这个变量设置为 on 等效于命令行选项 -q。在交互模式下可能用处不大。

• ROW_COUNT

  上一个 SQL 查询返回的行数或者受影响的行数，如果该查询失败或者没有报告行计数则为 0。

• SERVER_VERSION_NAME SERVER_VERSION_NUM

  字符串形式的服务器版本号，例如9.6.2、10.1 或者 11beta1，以及数字形式的服务器版本号，例如 90602 或者 100001。每次你连接到一个数据库（包括程序启动）时，这些都会被设置，但可以被改变或者重设。

• SHOW_CONTEXT

  这个变量可以被设置为值 never、errors 或者 always 来控制是否在来自服务器的消息中显示 CONTEXT 域。默认是 errors（表示在错误消息中显示上下文，但在通知和警告消息中不显示）。 当 VERBOSITY 被设置为 terse 或 sqlstate 时，这个设置无效（另见 \errverbose，它可以用来得到刚遇到的错误的详细信息）。

• SINGLELINE

  设置这个变量为 on 等效于命令行选项 -S。

• SINGLESTEP

  设置这个变量为 on 等效于命令选项 -s。

• SQLSTATE

  与上一个 SQL 查询的失败相关的错误代码，如果上一个查询成功则为 00000。

• USER

  当前连接的数据库用户。每次连接到一个数据库时都会设置该变量（包括程序启动时），但是可以被更改或者重置。

• VERBOSITY

  这个变量可以被设置为值 default、verbose、terse 或者 sqlstate 来控制错误报告的详细程度（另见 \errverbose，在想得到之前的错误的详细版本时使用）。

• VERSION VERSION_NAME VERSION_NUM

  这些变量在程序启动时被设置以反映 adb 的版本，分别是一个详细的字符串、一个短字符串（例如 9.6.2、10.1 或者 11beta1）以及一个数字（例如 90602 或者 100001）。它们可以被更改或重设。

SQL 中插入变量

adb 变量的一个关键特性是可以把它们替换（“插入”）到常规 SQL 语句中，也可以把它们作为元命令的参数。此外，adb 还提供了功能来确保被用作 SQL 文字和标识符的变量值会被正确地引用。插入一个值而不需要加引用的语法是在变量名前面加上一个冒号（:）。例如，

testdb=> \set foo 'my_table'
testdb=> SELECT * FROM :foo;

将查询表 my_table。注意这可能会不安全：该变量的值会被按字面拷贝，因此它可能包含不平衡的引号甚至反斜线命令。必须确保把它放在那里是有意义的。

当一个值被用作 SQL 文本或者标识符时，最安全的是把它加上引用。要引用一个变量的值作为 SQL 文本，可以把变量名称放在单引号中并且在引号前面写一个冒号。要引用作为 SQL 标识符，则可以把变量名称放在双引号中并且在引号前面写一个冒号。这种结构可以正确地处理变量值中嵌入的引号和其他特殊字符。之前的例子用这种方法写会更安全：

testdb=> \set foo 'my_table'
testdb=> SELECT * FROM :"foo";

在被引用的 SQL 文本和标识符中将不会执行变量插入。因此，一个诸如':foo'的结构不会从一个变量的值产生一个被引用的文本（即便能够也会不安全，因为无法正确地处理嵌入在值中的引号）。

使用这种机制的一个例子是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量，然后把该变量的值作为一个被引用的字符串插入：

testdb=> \set content `cat my_file.txt`
testdb=> INSERT INTO my_table VALUES (:'content');

（注意如果 my_file.txt 包含 NUL 字节，这样也不行。adb不支持在变量值中嵌入 NUL 字节）。

因为冒号可以合法地出现在 SQL 命令中，一次明显的插入尝试（即:name、:'name'或者:"name"）不会被替换，除非所提及的变量就是当前被设置的。在任何情况下，可以用一个反斜线对冒号进行转义以避免它被替换。

:{?*name*}特殊语法根据该变量存在与否返回 TRUE 或者 FALSE，并且因此总是会被替换，除非分号被反斜线转义。

变量的冒号语法对嵌入式查询语言（例如 ECPG）来说是标准的 SQL。用于数组切片和类型造型的冒号语法是 AntDB 扩展，它有时可能会与标准用法冲突。把一个变量值转义成 SQL 文本或者标识符的冒号引用语法是一种 adb 扩展。

提示符

adb 发出的提示符可以根据用户的喜好自定义。PROMPT1、PROMPT2 和 PROMPT3 这三个变量包含了描述提示符外观的字符串和特殊转义序列。Prompt 1 是当 adb 等待新命令时发出的常规提示符。Prompt 2 是在命令输入时需要更多输入时发出的提示符，例如因为当命令没有被分号终止或者引用没有被关闭时就会发出这个提示符。在运行一个 SQL COPY FROM STDIN 命令并且需要在终端上输入一个行值时，会发出 Prompt 3。

被选中的提示符变量会被原样打印，除非碰到一个百分号（%）。百分号的下一个字符会被特定的其他文本替换。预定义好的替换有：

• %M

  数据库服务器的完整主机名（带有域名），或者当该连接是建立在一个 Unix 域套接字上时则是 [local]，或者当 Unix 域套接字不在编译在系统内的默认位置上时则是 [local:*/dir/name*]。

• %m

  数据库服务器的主机名称（在第一个点处截断），或者当连接建立在一个 Unix 域套接字上时是 [local]。

• %>

  数据库服务器正在监听的端口号。

• %n

  数据库会话的用户名（在数据库会话期间，这个值可能会因为命令 SET SESSION AUTHORIZATION 的结果而改变）。

• %/

  当前数据库的名称。

• %~

  和%/类似，但是如果数据库是默认数据库时输出是~（波浪线）。

• %#

  如果会话用户时一个数据库超级用户，则是#，否则是一个>（在数据库会话期间，这个值可能会因为命令 SET SESSION AUTHORIZATION 的结果而改变）。

• %p

  当前连接到的后端的进程 ID。

• %R

  在提示符 1 下通常是=，但如果会话位于一个条件块的一个非活动分支中则是@，如果会话处于单行模式中则是^，如果会话从数据库断开连接（\connect失败时会发生这种情况）则是!。在提示符 2 中，根据为什么 adb 期待更多的输入，%R 会被一个相应的字符替换：如果命令还没有被终止是-，如果有一个未完的/* ... */注释则是*，如果有一个未完的被引用字符串则是一个单引号，如果有一个未完的被引用标识符则是一个双引号，如果有一个未完的美元引用字符串则是一个美元符号，如果有一个还没有被配对的左圆括号则是(。在提示符 3 中 %R 不会产生任何东西。

• %x

  事务状态：当不在事务块中时是一个空字符串，在一个事务块中时是*，在一个失败的事务块中时是!，当事务状态是未判定时（例如因为没有连接）为?。

• %l

  当前语句中的行号，从 1 开始。

• %digits

  带有指定的八进制码的字符会被替换。

• %:name:

  adb 变量 name 的值。

• %``*command`*```

  *command*的输出，类似于平常的“反引号”替换。

• %[ ... %]

  提示符可以包含终端控制字符，例如改变提示符文本的颜色、背景或者风格以及更改终端窗口标题的控制字符。为了让 Readline 的行编辑特性正确工作，这些不可打印的控制字符必须被包裹在%[和%]之间以指定它们是不可见的。在提示附中可以出现多个这样的标识对。例如：testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# '会导致一个在兼容 VT100 的彩色终端上的粗体（1;）的、黑底黄字（33;40）的提示符。

• %w

  与 PROMPT1 的最近输出相同宽度的空白。 这可以用作 PROMPT2 设置，以便多行语句与第一行对齐，但没有可见的辅助提示。

要在你的提示符中插入一个百分号，可以写成%%。提示符 1 和 2 的默认提示是'%/%R%x%# '，提示符 3 的提示是'>> '。

注意

这个特性是可耻地从 tcsh 抄袭过来的。

命令行编辑

为了方便的行编辑和检索，adb 支持 Readline 库。adb 退出时命令历史会被自动保存，而当 adb 启动时命令历史会被重新载入。adb 也支持 tab 补全，不过补全逻辑绝不是一个 SQL 解析器。tab 补全产生的查询也可能会受其他 SQL 命令干扰，例如 SET TRANSACTION ISOLATION LEVEL。如果出于某种原因不想用 tab 键补全，可以把下面的代码放在主目录下的名为 .inputrc 文件中关闭该特性：

$if adb
set disable-completion on
$endif

（这不是 adb 特性而是 Readline 的特性。进一步的细节请阅读它的文档。）

环境

• COLUMNS

  如果 \pset columns 为零，这个环境变量控制用于 wrapped 格式的宽度以及用来确定是否输出需要用到分页器或者切换到扩展自动模式中的垂直格式的宽度。

• PGDATABASE PGHOST PGPORT PGUSER

  默认连接参数。

• PG_COLOR

  规定在诊断消息中是否使用颜色。可能的值为 always、 auto、never。

• PSQL_EDITOR EDITOR VISUAL

  \e、\ef 以及 \ev 命令所使用的编辑器。会按照列出的顺序检查这些变量，第一个被设置的将被使用。如果都没有被设置，默认是使用 Unix 系统上的 vi 或者 Windows 系统上的 notepad.exe。

• PSQL_EDITOR_LINENUMBER_ARG

  当 \e、\ef 或者 \ev 带有一个行号参数时，这个变量指定用于传递起始行号给用户编辑器的命令行参数。对于 Emacs 或者 vi 之类的编辑器，这个变量是一个加号。如果需要在选项名称和行号之间有空格，可以在该变量的值中包括一个结尾的空格。例如：PSQL_EDITOR_LINENUMBER_ARG='+' PSQL_EDITOR_LINENUMBER_ARG='--line '在 Unix 系统上默认是+（对应于默认编辑器 vi，且对很多其他常见编辑器可用）。在 Windows 系统上没有默认值。

• PSQL_HISTORY

  命令历史文件的替代位置。波浪线（~）扩展会被执行。

• PSQL_PAGER PAGER

  如果一个查询的结果在屏幕上放不下，它们会通过这个命令分页显示。典型的值是 more 或 less。通过把 PSQL_PAGER 或 PAGER 设置为空字符串可以禁用分页器的使用，调整 \pset 命令与分页器相关的选项也能达到同样的效果。会按照列出的顺序检查这些变量，第一个被设置的将被使用。如果都没有被设置，则大部分平台上默认使用 more，但在 Cygwin 上使用 less。

• PSQLRC

  用户的 .psqlrc 文件的替代位置。波浪线（~）扩展会被执行。

• SHELL

  被\!命令执行的命令。

• TMPDIR

  存储临时文件的目录。默认是 /tmp。

和大部分其他 AntDB 工具一样，这个工具也使用 libpq 所支持的环境变量。

文件

• psqlrc and ~/.psqlrc

  如果没有 -X 选项，在连接到数据库后但在接收正常的命令之前，adb 会尝试依次从系统级的启动文件（psqlrc）和用户的个人启动文件（~/.psqlrc）中读取并且执行命令。这些文件可以被用来设置客户端或者服务器，通常是一些 \set 和 SET 命令。系统级的启动文件是 psqlrc，它应该在安装好的 AntDB 的“系统配置”目录中，最可靠的定位方法是运行 adb_config --sysconfdir。默认情况下，这个目录将是 ../etc/（相对于包含 AntDB 可执行文件的目录）。可以通过 PGSYSCONFDIR 环境变量显式地设置这个目录的名称。用户个人的启动文件是 .psqlrc，它应该在调用用户的主目录中。在 Windows 上，由于没有用户主目录的概念，个人的启动文件是%APPDATA%\postgresql\psqlrc.conf。用户启动文件的位置可以通过 PSQLRC 环境变量设置。系统级和用户个人的启动文件都可以弄成是针对特定 adb 版本的，方法是在文件名后面加上一个横线以及 AntDB 的主、次版本号，例如 ~/.psqlrc-9.2 或者 ~/.psqlrc-9.2.5。版本最为匹配的文件会优先于不那么匹配的文件读入。

• .psql_history

  命令行历史被存储在文件 ~/.psql_history中，或者是 Windows 的文件%APPDATA%\postgresql\psql_history 中。历史文件的位置可以通过 HISTFILE adb 变量或者 PSQL_HISTORY 环境变量明确的设置。

示例

第一个例子展示了如何如何跨越多行输入一个命令。注意提示符的改变：

testdb=> CREATE TABLE my_table (
testdb(>  first integer not null default 0,
testdb(>  second text)
testdb-> ;
CREATE TABLE

现在再看看表定义：

testdb=> \d my_table
              Table "public.my_table"
 Column |  Type   | Collation | Nullable | Default
--------+---------+-----------+----------+---------
 first  | integer |           | not null | 0
 second | text    |           |          | 

现在我们把提示符改一改：

testdb=> \set PROMPT1 '%n@%m %~%R%# '
antdb@localhost testdb=>

假定已经用数据填充了这个表并且想看看其中的数据：

antdb@localhost testdb=> SELECT * FROM my_table;
 first | second
-------+--------
     1 | one
     2 | two
     3 | three
     4 | four
(4 rows)

你可以用 \pset 命令以不同的方式显示表：

antdb@localhost testdb=> \pset border 2
Border style is 2.
antdb@localhost testdb=> SELECT * FROM my_table;
+-------+--------+
| first | second |
+-------+--------+
|     1 | one    |
|     2 | two    |
|     3 | three  |
|     4 | four   |
+-------+--------+
(4 rows)

antdb@localhost testdb=> \pset border 0
Border style is 0.
antdb@localhost testdb=> SELECT * FROM my_table;
first second
----- ------
    1 one
    2 two
    3 three
    4 four
(4 rows)

antdb@localhost testdb=> \pset border 1
Border style is 1.
antdb@localhost testdb=> \pset format csv
Output format is csv.
antdb@localhost testdb=> \pset tuples_only
Tuples only is on.
antdb@localhost testdb=> SELECT second, first FROM my_table;
one,1
two,2
three,3
four,4
antdb@localhost testdb=> \pset format unaligned
Output format is unaligned.
antdb@localhost testdb=> \pset fieldsep '\t'
Field separator is "    ".
antdb@localhost testdb=> SELECT second, first FROM my_table;
one     1
two     2
three   3
four    4

或者使用短命令：

antdb@localhost testdb=> \a \t \x
Output format is aligned.
Tuples only is off.
Expanded display is on.
antdb@localhost testdb=> SELECT * FROM my_table;
-[ RECORD 1 ]-
first  | 1
second | one
-[ RECORD 2 ]-
first  | 2
second | two
-[ RECORD 3 ]-
first  | 3
second | three
-[ RECORD 4 ]-
first  | 4
second | four

此外，可以使用 \g 为一个查询设置这些输出格式选项：

antdb@localhost testdb=> SELECT * FROM my_table
antdb@localhost testdb-> \g (format=aligned tuples_only=off expanded=on)
-[ RECORD 1 ]-
first  | 1
second | one
-[ RECORD 2 ]-
first  | 2
second | two
-[ RECORD 3 ]-
first  | 3
second | three
-[ RECORD 4 ]-
first  | 4
second | four

如果需要，可以用 \crosstabview 命令以交叉表的形式显示查询结果：

testdb=> SELECT first, second, first > 2 AS gt2 FROM my_table;
 first | second | gt2 
-------+--------+-----
     1 | one    | f
     2 | two    | f
     3 | three  | t
     4 | four   | t
(4 rows)

testdb=> \crosstabview first second
 first | one | two | three | four 
-------+-----+-----+-------+------
     1 | f   |     |       | 
     2 |     | f   |       | 
     3 |     |     | t     | 
     4 |     |     |       | t
(4 rows)

这第二个例子展示了表的“乘法”（连接），行按照序号降序排序且列按照独立的、升序的方式排序。

testdb=> SELECT t1.first AS "A", t2.first+100 AS "B", t1.first*(t2.first+100) AS "AxB",
testdb(> row_number() over(order by t2.first) AS ord
testdb(> FROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC
testdb(> \crosstabview "A" "B" "AxB" ord
 A | 101 | 102 | 103 | 104 
---+-----+-----+-----+-----
 4 | 404 | 408 | 412 | 416
 3 | 303 | 306 | 309 | 312
 2 | 202 | 204 | 206 | 208
 1 | 101 | 102 | 103 | 104
(4 rows)

查看和修改事务自动提交

一个完整的事务包括如下步骤：

• begin transaction;
• execute some sql;
• commit or rollback;

自动提交的含义是：每条语句会作为一个事务，在语句执行之前，客户端自动执行 begin ，在语句执行完成后，客户端自动执行事务结束操作：提交或者回滚，在 autocommit 打开后，事务的开始和结束操作均由客户端自动完成。

如果 autocommit 为 off， 则需要手动开启事务并手动结束事务。

adb 中的 autocommit 是默认开启的，也就是事务是自动提交的。

如何确认呢？在 adb 中执行 \set 就可以看到：

antdb=# \set 
AUTOCOMMIT = 'on' 
COMP_KEYWORD_CASE = 'preserve-upper' 
DBNAME = 'postgres' 
ECHO = 'none'

在输出中可以看到 AUTOCOMMIT = 'on' .

如何修改。在add中执行 \set AUTOCOMMIT off ：

antdb=# \set AUTOCOMMIT off 
antdb=# \set 
AUTOCOMMIT = 'off' 
COMP_KEYWORD_CASE = 'preserve-upper' 
DBNAME = 'postgres' 
ECHO = 'none'

退出 adb 后，设置失效。通过 adb重新登录后， autocommit 恢复默认值：

[antdb@localhost ~]$ adb 
psql (5.0.0 035f740 based on PG 11.6) 
Type "help" for help. 
antdb=# \set 
AUTOCOMMIT = 'on'

如果想 psql 中的 autocommit 默认为 off， 需要修改一个配置文件： ~/.psqlrc ，效果如下：

antdb=# \! cat ~/.psqlrc 
\set AUTOCOMMIT off 
antdb=# \set 
AUTOCOMMIT = 'off' 

在通过 adb 登录的时候，会首先加载 ~/.psqlrc 中的内容。

reindexdb

reindexdb — 重索引一个 AntDB 数据库

大纲

reindexdb [connection-option...] [option...] [ --schema | -S schema ] ... [ --table | -t table ] ... [ --index | -i index ] ... [dbname]

reindexdb` [*`connection-option`*...] [*`option`*...] `--all` | `-a

reindexdb [connection-option...] [option...] --system | -s [dbname]

描述

reindexdb 是用于重建一个 AntDB 数据库中索引的工具。

reindexdb 是 SQL 命令 REINDEX 的一个包装器。在通过这个工具和其他方法访问服务器来重索引数据库之间没有实质性的区别。

选项

reindexdb 接受下列命令行参数：

• -a --all

  重索引所有数据库。

• --concurrently

  使用 CONCURRENTLY 选项。

• [-d] *dbname* [--dbname=]*dbname*

  当 -a/--all 未使用时，指定要重新索引的数据库的名称。 如果未指定，则从环境变量 PGDATABASE 中读取数据库名称。 如果未设置，则使用为连接指定的用户名。 dbname 可以是 连接字符串。 如果是这样，连接字符串参数将覆盖任何冲突的命令行选项。

• -e --echo

  回显 reindexdb 生成并发送到服务器的命令。

• -i *index* --index=*index*

  只是重建 index。可以通过写多个 -i 开关来重建多个索引。

• -j *njobs* --jobs=*njobs*

  通过同时运行 njobs 命令并行执行 reindex 命令。 此选项可能会减少处理时间，但也会增加数据库服务器上的负载。reindexdb将打开到数据库的 njobs 连接，因此请确保 max_connections 设置足够高，可以容纳所有连接。请注意，此选项与 --index 和 --system 选项不兼容。

• -q --quiet

  不显示进度消息。

• -s --system

  索引数据库的系统目录。

• -S *schema* --schema=*schema*

  只对 schema 重建索引。 通过写多个 -S 开关可以指定多个要重建索引的模式。

• -t *table* --table=*table*

  只索引 table。可以通过写多个 -t 开关来重索引多个表。

• -v --verbose

  在处理时打印详细信息。

• -V --version

  打印 reindexdb 版本并退出。

• -? --help

  显示有关 reindexdb 命令行参数的帮助并退出。

reindexdb 也接受下列命令行参数用于连接参数：

• -h *host* --host=*host*

  指定运行服务器的机器的主机名。如果该值以一个斜线开始，它被用作 Unix 域套接字的目录。

• -p *port* --port=*port*

  指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。

• -U *username* --username=*username*

  要作为哪个用户连接。

• -w --no-password

  从不发出一个口令提示。如果服务器要求口令认证并且没有其他方式提供口令（例如一个 .pgpass 文件），那么连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入口令。

• -W --password

  强制 reindexdb 在连接到一个数据库之前提示要求一个口令。这个选项不是必不可少的，因为如果服务器要求口令认证，reindexdb将自动提示要求一个口令。但是，reindexdb 将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下值得用 -W 来避免额外的连接尝试。

• --maintenance-db=*dbname*

  当使用 -a/--all 时，指定要连接到的数据库名称以发现应重新索引哪些数据库。 如果未指定，将使用 antdb 数据库， 如果不存在，将使用 template1。 这可以是连接字符串。 如果是这样，连接字符串参数将覆盖任何冲突的命令行选项。 此外，在连接到其他数据库时，将重新使用除数据库名称本身之外的连接字符串参数。

环境

• PGDATABASE PGHOST PGPORT PGUSER

  默认连接参数

• PG_COLOR

  规定在诊断消息中是否使用颜色。可能的值为 always、 auto、never。

和大部分其他 AntDB 工具相似，这个工具也使用 libpq 支持的环境变量。

注解

reindexdb 可能需要多次连接到 AntDB 服务器，每一次都会询问一个口令。在这种情况下使用一个 ~/.pgpass 文件会更方便。

例子

要重索引数据库 test：

$ reindexdb test

要重索引名为 abcd 的数据库中的表 foo 和索引 bar：

$ reindexdb --table foo --index bar abcd

vacuumdb

vacuumdb — 对一个 AntDB 数据库进行垃圾收集和分析

大纲

vacuumdb [connection-option...] [option...] [ --table | -t table [( column [,...] )] ] ... [dbname]

vacuumdb` [*`connection-option`*...] [*`option`*...] `--all` | `-a

描述

vacuumdb是用于清理一个 AntDB 数据库的工具。vacuumdb 也将产生由 AntDB 查询优化器所使用的内部统计信息。

vacuumdb是 SQL 命令 VACUUM 的一个包装器。在通过这个工具和其他方法访问服务器来清理和分析数据库之间没有实质性的区别。

选项

vacuumdb 接受下列命令行参数：

• -a --all

  清理所有数据库。

• [-d] *dbname* [--dbname=]*dbname*

  指定要清理或分析的数据库的名称，当不使用 -a/--all 时。 如果未指定，则从环境变量 PGDATABASE 中读取数据库名称。 如果环境变量也没有设置，指定给该连接的用户名将用作数据库名。 dbname 可以是 connection string。 如果是这样，连接时的字符串参数将覆盖任何冲突的命令行选项。

• --disable-page-skipping

  根据可见性地图的内容禁用跳过页面。注意此选项仅对运行 AntDB 9.6 或更高版本的服务器有效。

• -e --echo

  回显 vacuumdb 生成并发送给服务器的命令。

• -f --full

  执行“完全”清理。

• -F --freeze

  强有力地“冻结”元组。

• -j *njobs* --jobs=*njobs*

  通过同时运行 njobs 个命令来并行执行清理或者分析命令。这个选项可能会减少处理的时间， 但是它也会增加数据库服务器的负载。vacuumdb 将开启 *njobs*个到数据 库的连接，因此请确认你的 max_connections 设置足够高以容纳所有的连接。注意如果某些系统目录被并行处理，使用这种模式加上 -f（FULL）选项可能会导致 死锁失败。

• --min-mxid-age *mxid_age*

  仅在 multixact ID 年龄至少为 mxid_age 的表上执行清空或分析命令。 此设置对于确定要处理的表的优先级比较有用，以防止multixact ID 回绕。。对于此选项的用途，关系的 multixact ID 年龄是主关系及其关联的 TOAST 表的年龄中最大的，如果存在的话。 由于 vacuumdb 发出的命令在需要时还将处理 TOAST 表的关系，它无需单独考虑。注意此选项仅对运行 AntDB 9.6 或更高版本的服务器有效。

• --min-xid-age *xid_age*

  仅在事务 ID 年龄至少为 xid_age 的表上执行清空或分析命令。 此设置对于确定要处理的表的优先级比较有用，以防止事务 ID 回绕。对于此选项的用途，关系的事务 ID 年龄是主关系及其关联的 TOAST 表的年龄中最大的，如果存在的话。 由于 vacuumdb 发出的命令在需要时还将处理 TOAST 表的关系，它无需单独考虑。注意此选项仅对运行 AntDB 9.6 或更高版本的服务器有效。

• -P *parallel_degree* --parallel=*parallel_degree*

  指定 parallel vacuum 的平行度。这允许清理利用多个 CPU 来处理索引。注意此选项仅适用于运行 AntDB13 及更高版本的服务器。

• -q --quiet

  不显示进度消息。

• --skip-locked

  跳过无法立即锁定以进行处理的关系。注意此选项仅对运行 AntDB 12 或更高版本的服务器有效。

• -t *table* [ (*column* [,...]) ] --table=*table* [ (*column* [,...]) ]

  只清理或分析 table。列名只能和 --analyze 或 --analyze-only 选项一起被指定。通过写多个 -t 开关可以清理多个表。提示如果你指定列，你可能必须转义来自 shell 的括号（见下面的例子）。

• -v --verbose

  在处理期间打印详细信息。

• -V --version

  打印vacuumdb版本并退出。

• -z --analyze

  也计算优化器使用的统计信息。

• -Z --analyze-only

  只计算优化器使用的统计信息（不清理）。

• --analyze-in-stages

  与 --analyze-only 相似，只计算优化器使用的统计信息（不做清理）。 使用不同的配置设置运行分析的几个（目前是 3 个）阶段以更快地产生可用的统计信息。这个选项对分析一个刚从转储恢复或者通过 adb_upgrade 得到 的数据库有用。这个选项将尝试尽可能快地创建一些统计信息来让该数据库可用，然后在后 续的阶段中产生完整的统计信息。

• -? --help

  显示有关 vacuumdb 命令行参数的帮助并退出。

vacuumdb 也接受下列命令行参数用于连接参数：

• -h *host* --host=*host*

  指定运行服务器的机器的主机名。如果该值以一个斜线开始，它被用作 Unix 域套接字的目录。

• -p *port* --port=*port*

  指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。

• -U *username* --username=*username*

  要作为哪个用户连接。

• -w --no-password

  从不发出一个口令提示。如果服务器要求口令认证并且没有其他方式提供口令（例如一个 .pgpass 文件），那么连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入口令。

• -W --password

  强制 vacuumdb 在连接到一个数据库之前提示要求一个口令。这个选项不是必不可少的，因为如果服务器要求口令认证，vacuumdb 将自动提示要求一个口令。但是，vacuumdb 将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下值得用 -W 来避免额外的连接尝试。

• --maintenance-db=*dbname*

  当使用 -a/--all 时，指定要连接到的数据库名称以发现应该清理的数据库。 如果未指定，将使用 antdb 数据库，如果不存在，将使用 template1。 这可以是 connection string。 如果是这样，连接字符串参数将覆盖任何冲突的命令行选项。 此外，在连接到其他数据库时，将重新使用除数据库名称本身之外的连接字符串参数。

环境

• PGDATABASE PGHOST PGPORT PGUSER

  默认连接参数

• PG_COLOR

  规定在诊断消息中是否使用颜色。可能的值为 always、 auto 和 never。

和大部分其他 AntDB 工具相似，这个工具也使用 libpq 支持的环境变量。

注解

vacuumdb 可能需要多次连接到 AntDB 服务器，每次都询问一个口令。在这种情况下有一个 ~/.pgpass 文件会很方便。

要清理数据库 test：

$ vacuumdb test

要清理和为优化器分析一个名为 bigdb 的数据库：

$ vacuumdb --analyze bigdb

要清理在名为 xyzzy 的数据库中的一个表 foo，并且为优化器分析该表的 bar 列：

$ vacuumdb --analyze --verbose --table='foo(bar)' xyzzy