如果您想要创建一个 "后台工作进程"，请指定 --bgworker 参数。

cargo pgx new 不会将目录初始化为 git 仓库，但会创建一个 .gitignore 文件，以防您决定这样做。

工作空间用户： cargo pgx new $NAME 将创建一个 $NAME/.cargo/config，您应该将其移动到工作空间根目录下的 .cargo./config 中。

如果不这样做，您可能会在使用 Rust-Analyzer 等工具时遇到不必要的重建，因为它将使用错误的 rustflags 选项。

$ cargo pgx new --help
cargo-pgx-new 0.5.0
ZomboDB, LLC <[email protected]>
Create a new extension crate

USAGE:
    cargo pgx new [OPTIONS] <NAME>

ARGS:
    <NAME>    The name of the extension

OPTIONS:
    -b, --bgworker    Create a background worker template
    -h, --help        Print help information
    -v, --verbose     Enable info logs, -vv for debug, -vvv for trace
    -V, --version     Print version information

管理您的 Postgres 安装

$ cargo pgx status all
Postgres v11 is stopped
Postgres v12 is stopped
Postgres v13 is stopped
Postgres v14 is stopped
Postgres v15 is stopped

$ cargo pgx start all
    Starting Postgres v11 on port 28811
    Starting Postgres v12 on port 28812
    Starting Postgres v13 on port 28813
    Starting Postgres v14 on port 28814
    Starting Postgres v15 on port 28815

$ cargo pgx status all
Postgres v11 is running
Postgres v12 is running
Postgres v13 is running
Postgres v14 is running
Postgres v15 is running

$ cargo pgx stop all
    Stopping Postgres v11
    Stopping Postgres v12
    Stopping Postgres v13
    Stopping Postgres v14
    Stopping Postgres v15

cargo pgx 有三个命令用于管理每个 Postgres 安装：start、stop 和 status。此外，cargo pgx run（见下文）将在目标 Postgres 实例尚未运行的情况下自动启动它。

启动Postgres实例时，pgx会在端口28800 + PG_MAJOR_VERSION上启动，所以Postgres 11运行在端口28811，12运行在端口28812，依此类推。此外，第一次启动这些实例中的任何一个时，它会自动在~/.pgx/data-[11 | 12 | 13 | 14 | 15]目录中初始化一个PGDATA目录。这样做允许pgx管理它安装的Postgres版本或计算机上已有的版本，并确保在后者的情况下，pgx管理的版本不会与已运行的版本冲突。实例的区域设置为C.UTF-8（或等价地，在macOS上具有ctype为UTF8的C区域），或者如果不可用，则使用C区域。

pgx不会拆除这些实例。虽然它们存储在您主目录中的一个隐藏目录中，但pgx认为这些是重要的永久性数据库安装。

启动后，您可以使用psql（如果您已在您的$PATH上安装了它）来连接到它们，如下所示：psql -p 28812。然而，您可能只想使用cargo pgx run命令。

编译和运行您的扩展

$ cargo pgx run pg13
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 /home/ana/.pgx/13.5/pgx-install/share/postgresql/extension/strings.control
     Copying shared library to /home/ana/.pgx/13.5/pgx-install/lib/postgresql/strings.so
    Building for SQL generation with features ``
    Finished dev [unoptimized + debuginfo] target(s) in 0.07s
 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 /home/ana/.pgx/13.5/pgx-install/share/postgresql/extension/strings--0.1.0.sql
    Finished installing strings
    Starting Postgres v13 on port 28813
    Re-using existing database strings
psql (13.5)
Type "help" for help.

strings=# DROP EXTENSION strings;
ERROR:  extension "strings" does not exist
strings=# CREATE EXTENSION strings;
CREATE EXTENSION
strings=# \df strings.*
                                      List of functions
 Schema  |     Name      | Result data type |           Argument data types            | Type
---------+---------------+------------------+------------------------------------------+------
 strings | append        | text             | input text, extra text                   | func
 strings | return_static | text             |                                          | func
 strings | split         | text[]           | input text, pattern text                 | func
 strings | split_set     | SETOF text       | input text, pattern text                 | func
 strings | substring     | text             | input text, start integer, "end" integer | func
 strings | to_lowercase  | text             | input text                               | func
(6 rows)

strings=# select strings.to_lowercase('PGX');
 to_lowercase
--------------
 pgx
(1 row)

cargo pgx run <pg11 | pg12 | pg13 | pg14 | pg15>是编译和开发期间交互式测试/使用您的扩展的主要接口。

您第一次执行cargo pgx run pgXX时，需要编译的不仅仅是您的扩展，还有pgx本身及其所有依赖项。根据您的计算机，这可能需要一点时间（pgx在计算为Postgres生成的绑定时几乎有20k行Rust代码）。然而，之后（如上图所示），它会相当快。

cargo pgx run 编译您的扩展，将其安装到指定的 Postgres 安装程序中，正如其 pg_config 工具所描述的那样，使用与 cargo pgx start pgXX 相同的过程启动该 Postgres 实例，并自动将您放入连接到数据库的 psql 命令行界面，默认情况下，名称与您的扩展相同。从那里开始，创建和使用您的扩展就由您来决定了。

这也是 pgx 通过 sql-generator 二进制文件自动为您生成扩展 SQL 架构的阶段。

当您退出 psql 时，Postgres 实例将继续在后台运行。

对于已安装在您计算机上的 Postgres 安装，cargo pgx run 需要写入权限到由 pg_config --pkglibdir 和 pg_config --sharedir 描述的目录。您需要决定如何实现这一点。虽然单个 Postgres 安装可以在不同的端口和不同的数据目录中多次启动，但它不支持多个“扩展库目录”。

$ cargo pgx run --help
cargo-pgx-run 0.5.0
ZomboDB, LLC <[email protected]>
Compile/install extension to a pgx-managed Postgres instance and start psql

USAGE:
    cargo pgx run [OPTIONS] [ARGS]

ARGS:
    <PG_VERSION>    Do you want to run against Postgres `pg11`, `pg12`, `pg13`, `pg14`,
                    `pg15`? [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

OPTIONS:
        --all-features
            Activate all available features

        --features <FEATURES>
            Space-separated list of features to activate

    -h, --help
            Print help information

        --manifest-path <MANIFEST_PATH>
            Path to Cargo.toml

        --no-default-features
            Do not activate the `default` feature

    -p, --package <PACKAGE>
            Package to build (see `cargo help pkgid`)

        --pgcli
            Use an existing `pgcli` on the $PATH [env: PGX_PGCLI=]

        --profile <PROFILE>
            Specific profile to use (conflicts with `--release`)

    -r, --release
            Compile for release mode (default is debug)

    -v, --verbose
            Enable info logs, -vv for debug, -vvv for trace

    -V, --version
            Print version information

连接到数据库

$ cargo pgx connect
    Re-using existing database strings
psql (13.5)
Type "help" for help.

strings=# select strings.to_lowercase('PGX');
 to_lowercase
--------------
 pgx
(1 row)

strings=#

如果您只想连接到一个无需重新编译和安装扩展的托管版本，请使用 cargo pgx connect <pg11 | pg12 | pg13 | pg14 | pg15>。

cargo-pgx-connect 0.5.
ZomboDB, LLC <[email protected]>
Connect, via psql, to a Postgres instance

USAGE:
    cargo pgx connect [OPTIONS] [ARGS]

ARGS:
    <PG_VERSION>    Do you want to run against Postgres `pg11`, `pg12`, `pg13`, `pg14`,
                    `pg15`? [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:
    -h, --help
            Print help information

        --manifest-path <MANIFEST_PATH>
            Path to Cargo.toml

    -p, --package <PACKAGE>
            Package to determine default `pg_version` with (see `cargo help pkgid`)

        --pgcli
            Use an existing `pgcli` on the $PATH [env: PGX_PGCLI=]

    -v, --verbose
            Enable info logs, -vv for debug, -vvv for trace

    -V, --version
            Print version information

$ cargo pgx 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 pgx install --help
cargo-pgx-install 0.5.0
ZomboDB, LLC <[email protected]>
Install the extension from the current crate to the Postgres specified by whatever `pg_config` is
currently on your $PATH

USAGE:
    cargo pgx install [OPTIONS]

OPTIONS:
        --all-features
            Activate all available features

    -c, --pg-config <PG_CONFIG>
            The `pg_config` path (default is first in $PATH)

        --features <FEATURES>
            Space-separated list of features to activate

    -h, --help
            Print help information

        --manifest-path <MANIFEST_PATH>
            Path to Cargo.toml

        --no-default-features
            Do not activate the `default` feature

    -p, --package <PACKAGE>
            Package to build (see `cargo help pkgid`)

        --profile <PROFILE>
            Specific profile to use (conflicts with `--release`)

    -r, --release
            Compile for release mode (default is debug)

        --test
            Build in test mode (for `cargo pgx test`)

    -v, --verbose
            Enable info logs, -vv for debug, -vvv for trace

    -V, --version
            Print version information

$ cargo pgx 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/.pgx/13.5/pgx-install/share/postgresql/extension/spi.control
     Copying shared library to /home/ana/.pgx/13.5/pgx-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/.pgx/13.5/pgx-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 pgx test [pg11 | pg12 | pg13 | pg14 | pg15] 运行您的 #[test] 和 #[pg_test] 标注的函数，使用 cargo 的测试系统。

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

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

Rust 的 #[test] 函数表现正常，而 #[pg_test] 函数在 Postgres 实例中运行，并具有对 Postgres 内部结构的完全访问权限。所有测试都并行运行，无论其类型如何。

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

cargo-pgx-test 0.5.0
ZomboDB, LLC <[email protected]>
Run the test suite for this crate

USAGE:
    cargo pgx test [OPTIONS] [ARGS]

ARGS:
    <PG_VERSION>    Do you want to run against Postgres `pg11`, `pg12`, `pg13`, `pg14`,
                    `pg15`, or `all`? [env: PG_VERSION=]
    <TESTNAME>      If specified, only run tests containing this string in their names

OPTIONS:
        --all-features
            Activate all available features

        --features <FEATURES>
            Space-separated list of features to activate

    -h, --help
            Print help information

        --manifest-path <MANIFEST_PATH>
            Path to Cargo.toml

    -n, --no-schema
            Don't regenerate the schema

        --no-default-features
            Do not activate the `default` feature

    -p, --package <PACKAGE>
            Package to build (see `cargo help pkgid`)

        --profile <PROFILE>
            Specific profile to use (conflicts with `--release`)

    -r, --release
            compile for release mode (default is debug)

    -v, --verbose
            Enable info logs, -vv for debug, -vvv for trace

    -V, --version
            Print version information

构建安装包

$ cargo pgx 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 pgx package [--debug] 在 --release 模式下构建您的扩展，到一个由 pg_config 工具从您的 $PATH 上的 Postgres 安装路径信息创建的目录结构 ./target/[debug | release]/extension_name-PGVER。

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

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

（如上图示例截图所示，使用 cargo pgx package 构建目录结构，该结构使用我手动安装的 Postgres 12 版本。）

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

$ cargo pgx package --help
cargo-pgx-package 0.5.0
ZomboDB, LLC <[email protected]>
Create an installation package directory

USAGE:
    cargo pgx package [OPTIONS]

OPTIONS:
        --all-features
            Activate all available features

    -c, --pg-config <PG_CONFIG>
            The `pg_config` path (default is first in $PATH)

    -d, --debug
            Compile for debug mode (default is release)

        --features <FEATURES>
            Space-separated list of features to activate

    -h, --help
            Print help information

        --manifest-path <MANIFEST_PATH>
            Path to Cargo.toml

        --no-default-features
            Do not activate the `default` feature

        --out-dir <OUT_DIR>
            The directory to output the package (default is
            `./target/[debug|release]/extname-pgXX/`)

    -p, --package <PACKAGE>
            Package to build (see `cargo help pkgid`)

        --profile <PROFILE>
            Specific profile to use (conflicts with `--debug`)

        --test
            Build in test mode (for `cargo pgx test`)

    -v, --verbose
            Enable info logs, -vv for debug, -vvv for trace

    -V, --version
            Print version information

检查您的扩展模式

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

$ cargo pgx schema --help
cargo-pgx-schema 0.5.0
ZomboDB, LLC <[email protected]>
Generate extension schema files

USAGE:
    cargo pgx schema [OPTIONS] [PG_VERSION]

ARGS:
    <PG_VERSION>    Do you want to run against Postgres `pg11`, `pg12`, `pg13`, `pg14`,
                    `pg15`?

OPTIONS:
        --all-features
            Activate all available features

    -c, --pg-config <PG_CONFIG>
            The `pg_config` path (default is first in $PATH)

    -d, --dot <DOT>
            A path to output a produced GraphViz DOT file

        --features <FEATURES>
            Space-separated list of features to activate

    -h, --help
            Print help information

        --manifest-path <MANIFEST_PATH>
            Path to Cargo.toml

        --no-default-features
            Do not activate the `default` feature

    -o, --out <OUT>
            A path to output a produced SQL file (default is `stdout`)

    -p, --package <PACKAGE>
            Package to build (see `cargo help pkgid`)

        --profile <PROFILE>
            Specific profile to use (conflicts with `--release`)

    -r, --release
            Compile for release mode (default is debug)

        --skip-build
            Skip building a fresh extension shared object

        --test
            Build in test mode (for `cargo pgx test`)

    -v, --verbose
            Enable info logs, -vv for debug, -vvv for trace

    -V, --version
            Print version information

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

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

激活

通过从扩展的 .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 文件中的配置值。对于基于 pgx 的扩展，这通常设置为 $libdir/<extension-0.0.0.so。

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

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

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

重要的是要注意，输出的 SQL 是版本相关的。这意味着在版本升级脚本中必须重新定义所有先前定义的 C 函数，以便指向当前版本化的 so。例如，当将扩展版本更新到 0.1.0 时，共享对象将被命名为 <extension-0.1.0.so，而 cargo pgx 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 函数指向新的共享对象。 pgx 不会 做任何魔法来确定函数是在哪个版本中引入或修改的，而只是将其放置在相应的版本化 so 文件中。由此扩展，您可以始终期望共享库将包含在扩展源代码中定义的所有函数。

#[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
}

$ cargo install --force --locked cargo-pgx