此命令将使用默认数据库（以您的扩展名称命名），或者您可以在最后一个参数中指定另一个数据库名称。

如果指定的数据库不存在，cargo pgrx connect 将创建它。同样，如果指定的 Postgres 版本没有运行，它将自动启动。

$ cargo pgrx connect --help
Connect, via psql, to a Postgres instance

Usage: cargo pgrx connect [OPTIONS] [PG_VERSION] [DBNAME]

Arguments:
  [PG_VERSION]  Do you want to run against pg12, pg13, pg14, pg15, pg16, or pg17 [env: PG_VERSION=]
  [DBNAME]      The database to connect to (and create if the first time).  Defaults to a database with the same name as the current extension name [env: DBNAME=]

Options:
  -p, --package <PACKAGE>              Package to determine default `pg_version` with (see `cargo help pkgid`)
      --manifest-path <MANIFEST_PATH>  Path to Cargo.toml
  -v, --verbose...                     Enable info logs, -vv for debug, -vvv for trace
      --pgcli                          Use an existing `pgcli` on the $PATH [env: PGRX_PGCLI=]
  -h, --help                           Print help
  -V, --version                        Print version

本地安装您的扩展

$ cargo pgrx install
building extension with features ``
"cargo" "build" "--message-format=json-render-diagnostics"
    Finished dev [unoptimized + debuginfo] target(s) in 0.06s

installing extension
     Copying control file to /usr/share/postgresql/13/extension/strings.control
     Copying shared library to /usr/lib/postgresql/13/lib/strings.so
    Building for SQL generation with features ``
    Finished dev [unoptimized + debuginfo] target(s) in 0.06s
 Discovering SQL entities
  Discovered 6 SQL entities: 0 schemas (0 unique), 6 functions, 0 types, 0 enums, 0 sqls, 0 ords, 0 hashes, 0 aggregates
     Writing SQL entities to /usr/share/postgresql/13/extension/strings--0.1.0.sql
    Finished installing strings

如果出于某种原因，您不喜欢使用 cargo pgrx run <PG_VERSION>，您可以使用 cargo pgrx install 将您的扩展安装到当前由 pg_config 工具描述的 Postgres 安装中，该工具目前位于您的 $PATH 中。

您需要 pg_config --pkglibdir 和 pg_config --sharedir 的写入权限。如果这有问题，请考虑使用 cargo pgrx install --sudo，它会以当前用户身份编译扩展，并使用 sudo 将扩展文件复制到正确的位置，并提示您输入密码。

默认情况下，cargo pgrx install 以调试模式构建您的扩展。指定 --release 将改变这一点。

$ cargo pgrx install --help
Install the extension from the current crate to the Postgres specified by whatever `pg_config` is currently on your $PATH

Usage: cargo pgrx install [OPTIONS]

Options:
  -p, --package <PACKAGE>              Package to build (see `cargo help pkgid`)
      --manifest-path <MANIFEST_PATH>  Path to Cargo.toml
  -v, --verbose...                     Enable info logs, -vv for debug, -vvv for trace
  -r, --release                        Compile for release mode (default is debug)
      --profile <PROFILE>              Specific profile to use (conflicts with `--release`)
      --test                           Build in test mode (for `cargo pgrx test`)
  -c, --pg-config <PG_CONFIG>          The `pg_config` path (default is first in $PATH)
  -s, --sudo                           Use `sudo` to install the extension artifacts
      --all-features                   Activate all available features
      --no-default-features            Do not activate the `default` feature
  -F, --features <FEATURES>            Space-separated list of features to activate
  -h, --help                           Print help
  -V, --version                        Print version

测试您的扩展

$ cargo pgrx test
"cargo" "test" "--features" " pg_test"
    Finished test [unoptimized + debuginfo] target(s) in 0.07s
     Running unittests (target/debug/deps/spi-312296af509607bc)

running 2 tests
building extension with features ` pg_test`
"cargo" "build" "--features" " pg_test" "--message-format=json-render-diagnostics"
    Finished dev [unoptimized + debuginfo] target(s) in 0.06s

installing extension
     Copying control file to /home/ana/.pgrx/13.5/pgrx-install/share/postgresql/extension/spi.control
     Copying shared library to /home/ana/.pgrx/13.5/pgrx-install/lib/postgresql/spi.so
    Building for SQL generation with features ` pg_test`
    Finished test [unoptimized + debuginfo] target(s) in 0.07s
 Discovering SQL entities
  Discovered 11 SQL entities: 1 schemas (1 unique), 8 functions, 0 types, 0 enums, 2 sqls, 0 ords, 0 hashes, 0 aggregates
     Writing SQL entities to /home/ana/.pgrx/13.5/pgrx-install/share/postgresql/extension/spi--0.0.0.sql
    Finished installing spi
test tests::pg_test_spi_query_by_id_direct ... ok
test tests::pg_test_spi_query_by_id_via_spi ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 1.61s

Stopping Postgres

cargo pgrx test ${VERSION} 将运行您的 #[test] 和 #[pg_test] 标注函数，使用 cargo 的测试系统。请注意，如果您请求 cargo pgrx test all，这将只运行为 cargo-pgrx 配置的版本以及设置在您的扩展 Cargo.toml 中的 pgrx 库的测试。

在测试过程中，pgrx 将启动一个临时的 Postgres 实例，其 PGDATA 目录位于 ./target/pgrx-test-data-PGVER/。这个 Postgres 实例在测试框架完成后立即停止。临时实例的区域设置为 C.UTF-8（或者在 macOS 上，等效于具有 ctype 的 UTF8 的 C 区域），如果 C.UTF-8 区域不可用，则使用 C。

输出是标准的 "cargo test" 输出和一些 Postgres 日志输出。在测试失败的情况下，失败报告将包括特定测试生成的任何 Postgres 日志消息。

Rust #[test] 函数表现正常，而 #[pg_test] 函数则在 Postgres 实例内部运行，并拥有访问所有 Postgres 内部结构的完整权限。所有测试都并行运行，无论它们的类型。

此外，一个 #[pg_test] 函数在一个事务中运行，当测试完成时会终止事务。因此，它对数据库所做的任何更改都不会被保留。

管理方面的说明是，可以使用 --runas 和 --pgdata 选项来控制用于运行测试执行单独的 postmaster 进程的操作系统用户。如果使用 --runas，则可能还需要将 --pgdata 设置为该用户可读可写的基目录 -- 默认的 PGDATA 目录位于 ./target/pgrx-test-pgdata，将具有运行 cargo pgrx test 的用户的权限，并且不能被 --runas 用户 chown。

$ cargo pgrx test --help
Run the test suite for this crate

Usage: cargo pgrx test [OPTIONS] [PG_VERSION] [TESTNAME]

Arguments:
  [PG_VERSION]  Do you want to run against pg12, pg13, pg14, pg15, pg16, pg17 or all? [env: PG_VERSION=]
  [TESTNAME]    If specified, only run tests containing this string in their names

Options:
  -p, --package <PACKAGE>              Package to build (see `cargo help pkgid`)
      --manifest-path <MANIFEST_PATH>  Path to Cargo.toml
  -v, --verbose...                     Enable info logs, -vv for debug, -vvv for trace
  -r, --release                        compile for release mode (default is debug)
      --profile <PROFILE>              Specific profile to use (conflicts with `--release`)
  -n, --no-schema                      Don't regenerate the schema
      --runas <USER>                   Use `sudo` to initialize and run the Postgres test instance as this system user
      --pgdata <DIR>                   Initialize the test database cluster here, instead of the default location.  If used with `--runas`, then it must be writable by the user
      --all-features                   Activate all available features
      --no-default-features            Do not activate the `default` feature
  -F, --features <FEATURES>            Space-separated list of features to activate
  -h, --help                           Print help
  -V, --version                        Print version

构建安装包

$ cargo pgrx package
building extension with features ``
"cargo" "build" "--release" "--message-format=json-render-diagnostics"
    Finished release [optimized] target(s) in 0.07s

installing extension
     Copying control file to target/release/spi-pg13/usr/share/postgresql/13/extension/spi.control
     Copying shared library to target/release/spi-pg13/usr/lib/postgresql/13/lib/spi.so
    Building for SQL generation with features ``
    Finished release [optimized] target(s) in 0.07s
 Discovering SQL entities
  Discovered 8 SQL entities: 0 schemas (0 unique), 6 functions, 0 types, 0 enums, 2 sqls, 0 ords, 0 hashes, 0 aggregates
     Writing SQL entities to target/release/spi-pg13/usr/share/postgresql/13/extension/spi--0.0.0.sql
    Finished installing spi

cargo pgrx package [--debug] 在 --release 模式下构建您的扩展，到一个目录结构中，位于 ./target/[debug | release]/extension_name-PGVER，使用来自您的 pg_config 工具的 Postgres 安装路径信息。

目的是您将切换到该目录并构建一个 tarball 或 .deb 或 .rpm 包。

cargo pgrx package 创建的目录结构从文件系统的根目录开始，因为可能安装的版本管理器会将 pg_config --pkglibdir 和 pg_config --sharedir 分割成不同的基路径。

（在上面的示例截图中，使用 cargo pgrx package 使用手动安装的 Postgres 12 版本构建目录结构。）

此命令可以从 Dockerfile 中使用，例如，用于自动构建各种 Linux 发行版或 MacOS Postgres 安装程序的安装包。

$ cargo pgrx package --help
Create an installation package directory

Usage: cargo pgrx package [OPTIONS]

Options:
  -p, --package <PACKAGE>              Package to build (see `cargo help pkgid`)
      --manifest-path <MANIFEST_PATH>  Path to Cargo.toml
  -v, --verbose...                     Enable info logs, -vv for debug, -vvv for trace
  -d, --debug                          Compile for debug mode (default is release)
      --profile <PROFILE>              Specific profile to use (conflicts with `--debug`)
      --test                           Build in test mode (for `cargo pgrx test`)
  -c, --pg-config <PG_CONFIG>          The `pg_config` path (default is first in $PATH)
      --out-dir <OUT_DIR>              The directory to output the package (default is `./target/[debug|release]/extname-pgXX/`)
      --all-features                   Activate all available features
      --no-default-features            Do not activate the `default` feature
  -F, --features <FEATURES>            Space-separated list of features to activate
  -h, --help                           Print help
  -V, --version                        Print version

检查您的扩展模式

如果您只想查看 pgrx 将生成的完整扩展模式，请使用 cargo pgrx schema。

$ cargo pgrx schema --help
Generate extension schema files

Usage: cargo pgrx schema [OPTIONS] [PG_VERSION]

Arguments:
  [PG_VERSION]  Do you want to run against pg12, pg13, pg14, pg15, pg16, or pg17?

Options:
  -p, --package <PACKAGE>              Package to build (see `cargo help pkgid`)
      --manifest-path <MANIFEST_PATH>  Path to Cargo.toml
  -v, --verbose...                     Enable info logs, -vv for debug, -vvv for trace
      --test                           Build in test mode (for `cargo pgrx test`)
  -r, --release                        Compile for release mode (default is debug)
      --profile <PROFILE>              Specific profile to use (conflicts with `--release`)
  -c, --pg-config <PG_CONFIG>          The `pg_config` path (default is first in $PATH)
      --all-features                   Activate all available features
      --no-default-features            Do not activate the `default` feature
  -F, --features <FEATURES>            Space-separated list of features to activate
  -o, --out <OUT>                      A path to output a produced SQL file (default is `stdout`)
  -d, --dot <DOT>                      A path to output a produced GraphViz DOT file
      --skip-build                     Skip building a fresh extension shared object
  -h, --help                           Print help
  -V, --version                        Print version

扩展版本升级脚本

使用cargo pgrx new foo创建pgrx扩展时，新扩展模板目录树中包含一个名为./sql的目录。

$ tree
.
├── Cargo.toml
├── blah.control
├── sql
└── src
    └── lib.rs

2 directories, 3 files

您将在这个目录中手动创建扩展版本升级脚本。您创建的文件应按照Postgres 扩展更新文档中规定的方式进行命名。通常格式为foo--oldver--newver.sql。例如，foo--1.0.0--1.0.1.sql。

当用户在一个具有foo扩展的数据库中运行ALTER EXTENSION foo UPDATE;时，Postgres会构建一个升级脚本图，从当前安装的版本开始，以扩展.control文件中定义的default_version结束。然后Postgres将沿着最短路径执行这些脚本。

您负责以任何允许Postgres从当前版本更新到下一个版本的方式手动编写这些扩展升级脚本。pgrx没有自动生成这些脚本的能力。

虽然pgrx不生成这些升级脚本，但它现在知道它们，并且所有生成扩展工件（如cargo pgrx test/run/install/package）的pgrx命令都会自动将这些文件从./sql目录复制到由pg_config指定的最终目的地。

关于pgx管理的开发环境信息

$ cargo pgrx info --help
Provides information about pgrx-managed development environment

Usage: cargo pgrx info [OPTIONS] <COMMAND>

Commands:
  path       Print path to a base version of Postgres build
  pg-config  Print path to pg_config for a base version of Postgres
  version    Print specific version for a base Postgres version
  help       Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...  Enable info logs, -vv for debug, -vvv for trace
  -h, --help        Print help
  -V, --version     Print version

cargo pgx info帮助检索有关pgx管理的开发环境（如管理的Postgres安装）的信息。

实验性：版本化共享对象支持

pgrx实验性地支持生成版本化共享库的选项。这允许并行安装扩展的多个版本，并可以启用在扩展版本之间弃用（和删除）函数。在使用此功能时必须注意一些注意事项。因此，目前它是实验性的。

激活

通过从扩展的.control文件中删除module_pathname配置值来启用版本化共享对象支持。

概念

Postgres有一个隐含的要求，即C扩展必须在版本之间保持ABI兼容性。这个功能的背后想法是，当新版本与旧版本不兼容时，允许两个版本的扩展之间的互操作性。

操作的机制是对共享库文件名进行版本化，并将函数定义硬编码为指向版本化的共享库文件。如果没有版本化共享对象支持，C函数的SQL定义将如下所示：

CREATE OR REPLACE FUNCTION "hello_extension"() RETURNS text /* &str */
STRICT
LANGUAGE c /* Rust */
AS 'MODULE_PATHNAME', 'hello_extension_wrapper';

MODULE_PATHNAME 在 Postgres 中被配置文件 .control 中的配置值所替换。对于基于 pgrx 的扩展，这通常被设置为 $libdir/<extension-name>。

当使用版本化共享对象支持时，相同的 SQL 将如下所示

CREATE OR REPLACE FUNCTION "hello_extension"() RETURNS text /* &str */
STRICT
LANGUAGE c /* Rust */
AS '$libdir/extension-0.0.0', 'hello_extension_wrapper';

请注意，版本化的共享库在函数定义中是硬编码的。这对应于 extension-0.0.0.so 文件，这是 pgrx 生成的。

需要注意的是，生成的 SQL 是与版本相关的。这意味着所有之前定义的 C 函数必须在版本升级脚本中重新定义，以指向当前版本化的 so。例如，当将扩展版本更新到 0.1.0 时，共享对象将被命名为 <extension-name>-0.1.0.so，并且 cargo pgrx schema 将为上述函数生成以下 SQL

CREATE OR REPLACE FUNCTION "hello_extension"() RETURNS text /* &str */
STRICT
LANGUAGE c /* Rust */
AS '$libdir/extension-0.1.0', 'hello_extension_wrapper';

此 SQL 必须用于从 0.0.0 到 0.1.0 的升级脚本中，以便将 hello_extension 函数指向新的共享对象。 pgrx 不会 进行任何魔术操作来确定函数是在哪个版本中引入或修改的，并且只会将其放置在相应的版本化 so 文件中。通过扩展，您可以始终预期共享库将包含 所有 在扩展源代码中定义的函数。

此功能并非旨在帮助数据类型的向后兼容性。

@MODULE_PATHNAME@ 模板化

如果您已经为 Rust 函数提供了自定义的 SQL 定义，您可以在自定义 SQL 中使用 @MODULE_PATHNAME@ 模板。此值将被替换为实际共享对象的路径。

以下示例说明了这是如何工作的

#[pg_extern(sql = r#"
    CREATE OR REPLACE FUNCTION tests."overridden_sql_with_fn_name"() RETURNS void
    STRICT
    LANGUAGE c /* Rust */
    AS '@MODULE_PATHNAME@', '@FUNCTION_NAME@';
"#)]
fn overridden_sql_with_fn_name() -> bool {
    true
}

注意事项

有一些场景与这个功能完全不兼容，因为它们依赖于 Postgres 中的某些全局状态，所以加载两个版本的共享库将导致问题。

这些场景包括

• 当使用共享内存时
• 当使用查询计划钩子时