Skip to content

Commit

Permalink
Removing content from README that is now in main documentation (#266)
Browse files Browse the repository at this point in the history
  • Loading branch information
@rustprooflabs
rustprooflabs authored Mar 21, 2023
1 parent f239fcc commit e5f96e8
Show file tree
Hide file tree
Showing 5 changed files with 26 additions and 83 deletions.
78 changes: 12 additions & 66 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ are not interpreted.
The top advantages of PL/Rust include writing natively-compiled functions to achieve the absolute best performance,
access to Rust's large development ecosystem, and Rust's compile-time safety guarantees.

> The PL/Rust [documentation is moving](https://tcdi.github.io/plrust/) to a more user friendly format. The mdbook format documentation is auto-generated from the main branch.
PL/Rust provides access to Postgres' Server Programming Interface (SPI) including dynamic queries, prepared
statements, and cursors. It also provides safe Rust types over most of Postgres built-in data types, including (but
not limited to), TEXT, INT, BIGINT, NUMERIC, FLOAT, DOUBLE PRECISION, DATE, TIME, etc.
Expand Down Expand Up @@ -215,30 +217,13 @@ you can omit the `--features "trusted"` arguments.

# Configuration

PL/Rust has a few required configuration options, but first and foremost it **must** be configured as a
`shared_preload_libraries` entry in `postgresql.conf`. For example:

```
shared_preload_libraries = 'plrust'
```
See the [PostgreSQL Configuration](https://tcdi.github.io/plrust/config-pg.html)
section of the documentation for notes on configuring PL/Rust in
`postgresql.conf`.

Failure to do so will cause the plrust extension to raise an ERROR whenever Postgres tries to first load it.

The PL/Rust-specific configuration options, some of which are **required**, are:
----

| Option | Type | Description | Required | Default |
|------------------------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|----------------------------------------------------------------------------------------------------------------------|
| `plrust.work_dir` | string | The directory where pl/rust will build functions with cargo. | yes | <none> |
| `plrust.PATH_override` | string | If `cargo` and `cc` aren't in the `postmaster`'s `$PATH`, set this. | no | environment or `~/.cargo/bin:/usr/bin` if `$PATH` is unset |
| `plrust.tracing_level` | string | A [tracing directive][docs-rs-tracing-directive]. | no | `'info'` |
| `plrust.compilation_targets` | string | Comma separated list of CPU targets (x86_64, aarch64). | no | <none> |
| `plrust.x86_64_linker` | string | Name of the linker `rustc` should use on fo cross-compile. | no | `'x86_64_linux_gnu_gcc'` |
| `plrust.aarch64_linker` | string | Name of the linker `rustc` should use on for cross-compile. | no | `'aarch64_linux_gnu_gcc'` |
| `plrust.x86_64_pgx_bindings_path` | string | Path to output from `cargo pgx cross pgx-target` on x86_64. | no-ish | <none> |
| `plrust.aarch64_pgx_bindings_path` | string | Path to output form `cargo pgx cross pgx-target` on aarch64. | no-ish | <none> |
| `plrust.compile_lints` | string | A comma-separated list of Rust lints to apply to every user function. | no | `'plrust_extern_blocks, plrust_lifetime_parameterized_traits, implied_bounds_entailment, unsafe_code, plrust_filesystem_macros, plrust_env_macros, plrust_external_mod, plrust_fn_pointers, plrust_async, plrust_leaky, plrust_print_macros, plrust_stdio, unknown_lints, deprecated, suspicious_auto_trait_impls, unaligned_references, soft_unstable, plrust_autotrait_impls'` |
| `plrust.required_lints` | string | A comma-separated list of Rust lints that are required to have been applied to a user function before PL/Rust will load the library and execute the function. | no | defaults to whatever `plrust.compile_lints` happens to be |
| `plrust.trusted_pgx_version` | string | The version of the [`plrust-trusted-pgx`](https://crates.io/crates/plrust-trusted-pgx) crate from crates.io to use when compiling user functions |

For PL/Rust to cross compile user functions it needs to know which CPU architectures via
`plrust.compilation_targets`. This is a comma-separated list of values, of which only `x86_64` and `aarch64` are
Expand All @@ -261,55 +246,16 @@ the other architecture.

### Lints

As discussed above, PL/Rust has its own "rustc driver" named `plrustc`. This must be installed using the
[`plrustc/build.sh`](plrustc/build.sh) script and the resulting executable must be on the `PATH`, or it should reside
somewhere that is included in the `plrust.PATH_override` GUC.
See the [Lints section](https://tcdi.github.io/plrust/config-lints.html)
of the documentation.

The `plrust.required_lints` GUC defines which lints must have been applied to a function before PL/Rust will load the
library and execute the function. Using the `PLRUST_REQUIRED_LINTS` environment variable, it is possible to enforce
that certain lints are always required of compiled functions, regardless of the `plrust.required_lints` GUC value.
`PLRUST_REQUIRED_LINTS`'s format is a comma-separated list of lint named. It must be set in the environment in which
Postgres is started. The intention here is that the system administrator can force certain lints for execution if for
some reason `postgresql.conf` or the users able to modify it are not trusted.

## Environment Variables

As part of PL/Rust's function compilation machinery, and in conjunction with `pgx` which does the hard work, a number
of environment variables are set when PL/Rust executes `cargo`.

These are not environment variables that need to set manually. Generally, these are auto-detected and cannot be
overridden through configuration.

| Name | Value | How it's Used |
|---------------------------------------------|-------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| PATH | `~/cargo/bin:/usr/bin` or `/usr/bin` if "postgres" user has no home directory | The `PATH` environment variable is **only** set by PL/Rust if it detects that one isn't already set. <br/>As mentioned above, this one *can* be overridden via the `plrust.PATH_override` GUC in `postgresql.conf`. |
| RUSTC | `plrustc` | This is set to plrust's "rust driver" executable, named `plrustc`. It must be on the system PATH. |
| RUSTFLAGS | `"-Clink-args=-Wl,-undefined,dynamic_lookup"` | Used by `rustc` to indicate that Postgres internal symbols are only available at run-time, not compile-time. |
| CARGO_TARGET_DIR | value of GUC `plrust.work_dir`/`target` | This is the filesystem path `cargo` will store its intermediate compilation artifacts. |
| CARGO_TARGET_X86_64_LINKER | `x86_64-linux-gnu-gcc` | Used only when cross-compiling *to* x86_64, this tells `rustc` which linker to use. The `plrust.x86_64_linker` GUC can override the default. |
| CARGO_TARGET_AARCH64_LINKER | `aarch64-linux-gnu-gcc` | Used only when cross-compiling *to* aarch64, this tells `rustc` which linker to use. The `plrust.aarch64_linker` GUC can override the default. |
| PGX_TARGET_INFO_PATH_PG${MAJOR_VERSION_NUM} | unset unless `plrust.{x86_64/aarch64}_pgx_bindings_path` GUC is set | Used only when cross-compiling *to* the specified target. This tells `pgx` where to find the generated Postgres bindings for that platform. |
| PGX_PG_CONFIG_AS_EN_VAR | `true` | Indicates to the `plrust-trusted-pgx` dependency, and ultimately `pgx` itself that instead of getting the values it needs for compilation from the Postgres `pg_config` tool, it should get them from environment variables. |
| PGX_PG_CONFIG_VERSION | Provided by the running Postgres instance | Used by `pgx` to build the PL/Rust user function. |
| PGX_PG_CONFIG_CPPFLAGS | Provided by the running Postgres instance | Used by `pgx` to build the PL/Rust user function (technically unused by PL/Rust's build process as PL/Rust does not include the pgx "cshim" for which this is normally used). |
| PGX_PG_CONFIG_INCLUDEDIR-SERVER | Provided by the running Postgres instance | Used by `pgx` to build the PL/Rust user function. |
| PLRUSTC_USER_CRATE_NAME | The name of the user crate | Used by `plrust` to help `plrustc` distinguish between the PL/Rust user function and dependencies. |
| PLRUSTC_USER_CRATE_ALLOWED_SOURCE_PATHS | The user crate dir and the cargo target dir, separated by `:`. | When compiling the user crate (given by `PLRUSTC_USER_CRATE_NAME`), `plrustc` ensures no source files outside of these (`:`-delimited) directories are accessed. Every path in the list should be absolute and have symlinks resolved. The sysroot is currently automatically added to this list. |

There are a number of other `pg_config`-related environment variables that plrust sets. These are not currently used,
but are reserved for future use, should they become necessary to build a user function:
`PGX_PG_CONFIG_BINDIR, PGX_PG_CONFIG_DOCDIR, PGX_PG_CONFIG_HTMLDIR, PGX_PG_CONFIG_INCLUDEDIR, PGX_PG_CONFIG_PKGINCLUDEDIR, PGX_PG_CONFIG_INCLUDEDIR-SERVER, PGX_PG_CONFIG_LIBDIR, PGX_PG_CONFIG_PKGLIBDIR, PGX_PG_CONFIG_LOCALEDIR, PGX_PG_CONFIG_MANDIR, PGX_PG_CONFIG_SHAREDIR, PGX_PG_CONFIG_SYSCONFDIR, PGX_PG_CONFIG_PGXS, PGX_PG_CONFIG_CONFIGURE, PGX_PG_CONFIG_CC, PGX_PG_CONFIG_CPPFLAGS, PGX_PG_CONFIG_CFLAGS, PGX_PG_CONFIG_CFLAGS_SL, PGX_PG_CONFIG_LDFLAGS, PGX_PG_CONFIG_LDFLAGS_EX, PGX_PG_CONFIG_LDFLAGS_SL, PGX_PG_CONFIG_LIBS, PGX_PG_CONFIG_VERSION`

Note that PL/Rust uses Rust's [`std::process::Command`](https://doc.rust-lang.org/beta/std/process/struct.Command.html)
to exec `cargo`. As such, it **will** inherit **all** environment variables set under the active backend `postgres`
process. We recommend Postgres' execution environment be properly sanitized to your organizations requirements.

As a pre-emptive measure, PL/Rust proactively unsets a few environment variables that could negatively impact user function
compilation:
`DOCS_RS, PGX_BUILD_VERBOSE, PGX_PG_SYS_GENERATE_BINDINGS_FOR_RELEASE, CARGO_MANIFEST_DIR, OUT_DIR, RUSTC_WRAPPER, RUSTC_WORKSPACE_WRAPPER`
(These are generally things used by the `pgx` development team and not at all necessary for PL/Rust.)

`plrustc` also performs a search for the location of the Rust sysroot which is informed by several environment variables (specifically `PLRUSTC_SYSROOT`, `SYSROOT`, `RUSTUP_TOOLCHAIN`, and `RUSTUP_HOME`). The details of how this search is performed are documented in the ([`plrustc` README](./plrustc/README.md)), but it is very similar to the search performed by `clippy`, `miri`, and other tools that use the `rustc_driver` library.
See the [Environment variables section](https://tcdi.github.io/plrust/config-env-var.html)
of the documentation.



# Quickly Getting Started

Expand Down
13 changes: 8 additions & 5 deletions doc/src/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,24 @@
- [Update PL/Rust](./update-plrust.md)
- [Cross compilation](./install-cross-compile.md)

# User Guide
# PL/Rust Usage

- [PL/Rust Functions and Arguments](./use-plrust.md)
- [Data types](./data-types.md)
- [Built-in functions](./built-in-functions.md)
- [Logging to PostgreSQL from PL/Rust](./logging.md)
- [Triggers](./triggers.md)
- [SPI](./spi.md)
- [Configuration](./config.md)
- [PostgreSQL configuration](./config-pg.md)
- [Lints](./config-lints.md)
- [Environment variables](./config-env-var.md)
- [Trusted and Untrusted PL/Rust](./trusted-untrusted.md)
- [Rules and Regulations](./rules-regulations.md)

# PL/Rust Configuration

- [PostgreSQL configuration](./config-pg.md)
- [Lints](./config-lints.md)
- [Environment variables](./config-env-var.md)



# PL/Rust Under the Hood

Expand Down
3 changes: 2 additions & 1 deletion doc/src/config-pg.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,9 @@ The PL/Rust-specific configuration options are in the following table.
| `plrust.aarch64_linker` | string | Name of the linker `rustc` should use on for cross-compile. | no | `'aarch64_linux_gnu_gcc'` |
| `plrust.x86_64_pgx_bindings_path` | string | Path to output from `cargo pgx cross pgx-target` on x86_64. | no-ish | <none> |
| `plrust.aarch64_pgx_bindings_path` | string | Path to output form `cargo pgx cross pgx-target` on aarch64. | no-ish | <none> |
| `plrust.compile_lints` | string | A comma-separated list of Rust lints to apply to every user function. | no | `'plrust_extern_blocks, plrust_lifetime_parameterized_traits, implied_bounds_entailment, unsafe_code, plrust_filesystem_macros, plrust_fn_pointers, plrust_async, unknown_lints' |
| `plrust.compile_lints` | string | A comma-separated list of Rust lints to apply to every user function. | no | `'plrust_extern_blocks, plrust_lifetime_parameterized_traits, implied_bounds_entailment, unsafe_code, plrust_filesystem_macros, plrust_env_macros, plrust_external_mod, plrust_fn_pointers, plrust_async, plrust_leaky, plrust_print_macros, plrust_stdio, unknown_lints, deprecated, suspicious_auto_trait_impls, unaligned_references, soft_unstable, plrust_autotrait_impls'` |
| `plrust.required_lints` | string | A comma-separated list of Rust lints that are required to have been applied to a user function before PL/Rust will load the library and execute the function. | no | defaults to whatever `plrust.compile_lints` happens to be |
| `plrust.trusted_pgx_version` | string | The version of the [`plrust-trusted-pgx`](https://crates.io/crates/plrust-trusted-pgx) crate from crates.io to use when compiling user functions |

For PL/Rust to cross compile user functions it needs to know which CPU architectures via
`plrust.compilation_targets`. This is a comma-separated list of values, of which only `x86_64` and `aarch64` are
Expand Down
7 changes: 0 additions & 7 deletions doc/src/config.md
View file

This file was deleted.

8 changes: 4 additions & 4 deletions doc/src/plrust.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,8 +55,8 @@ SELECT strlen('Hello, PL/Rust');

## Built on pgx

PL/Rust is built on the `pgx` framework. Documentation on the pgx crate is
[found here](https://docs.rs/pgx/latest/pgx/).


PL/Rust itself is a [`pgx`](https://github.com/tcdi/pgx)-based Postgres extension. Furthermore, each `LANGUAGE
plrust` function are themselves mini-pgx extensions. `pgx`is a generalized framework for developing Postgres extensions with Rust. Like this project, `pgx`
is developed by [TCDI](https://www.tcdi.com).

The following sections discuss PL/Rusts safety guarantees, configuration settings, and installation instructions.

0 comments on commit e5f96e8

Please sign in to comment.