pg-extend-rs - GitLite

KO | EN

gitlite — search

#javascript #react #ai #typescript #llm #deep-learning #linux #nodejs #cli #kubernetes #vue #awesome-list #security #ios

pg-extend-rs

(★ 279)

Postgres extension library for Rust

File Explorer

Download Latest Version (.zip)

- config
- - test.yml
- dependabot.yml
- - Cargo.toml
  - README.md
- - Cargo.toml
- - Cargo.toml
- - Cargo.toml
  - README.md
- - Cargo.toml
  - README.md
- - Cargo.toml
  - README.md
- - Cargo.toml
  - README.md
- - Cargo.toml
  - README.md
- - lib.rs
- - adding_tests.rs
  - fdw.rs
  - logging.rs
  - memory_context.rs
  - nullable_tests.rs
  - panicking_tests.rs
  - strings.rs
- Cargo.toml
- Makefile.toml
- postgresql.conf
- - lib.rs
  - log.rs
  - pg_alloc.rs
  - pg_bool.rs
  - pg_datum.rs
  - pg_error.rs
  - pg_fdw.rs
  - pg_sys.rs
  - pg_type.rs
- build.rs
- Cargo.toml
- Makefile.toml
- pg_majorversion.h
- wrapper.h
- - lib.rs
  - lifetime.rs
- Cargo.toml
- Makefile.toml
- README.md
.gitignore
Cargo.lock
Cargo.toml
CHANGELOG.md
CODE_OF_CONDUCT.md
LICENSE-APACHE
LICENSE-MIT
Makefile.toml
README.md

# Installation Guide

1. Get the code

git clone https://github.com/bluejekyll/pg-extend-rs

Downloads the entire project code from GitHub to your computer.

cd pg-extend-rs

Moves into the project folder you just downloaded.

2. Rust

Medium Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Rust (rustup) Installing via rustup also installs cargo.

> cargo make all-features -p v12 # if -p is left off, then the default is v12

Type this command into your terminal and run it.

> cargo make all-features

Type this command into your terminal and run it.

> cargo make default-features

Type this command into your terminal and run it.

> cargo make no-default-features

Type this command into your terminal and run it.

> cargo make all-features -p v10

Type this command into your terminal and run it.

✅ If cargo build finishes without errors, it worked. The executable is created under target/.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Build Status](https://github.com/bluejekyll/pg-extend-rs/workflows/test/badge.svg?branch=master)](https://github.com/bluejekyll/pg-extend-rs/actions?query=workflow%3Atest)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/bluejekyll/pg-extend-rs/master/LICENSE-MIT)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](https://raw.githubusercontent.com/bluejekyll/pg-extend-rs/master/LICENSE-APACHE)
[![Dependabot Status](https://api.dependabot.com/badges/status?host=github&repo=bluejekyll/pg-extend-rs)](https://dependabot.com)
[![](http://meritbadge.herokuapp.com/pg-extend)](https://crates.io/crates/pg-extend)
[![Discord](https://img.shields.io/discord/589988605322199149.svg)](https://discord.gg/y7ZvY5p)

# Rust based Postgres extension

The main things provided by this crate are some macros that help with writing Postgres extensions in Rust.

The objective (not all these are yet implemented):

- Automatic type conversions, see `PgDatum` and `TryFromPgDatum` to `Into<PgDatum>`
- `pg_magic` macro for declaring libraries as Postgres extensions
- `pg_extern` attribute for wrapping Rust functions in Postgres C style definitions
- panic handlers for conversion into Postgres errors
- allocator that uses Postgres `palloc` allocator and `pfree`
- *tbd* integrate postgres error logs with `log`
- *tbd* support all Datum types
- *tbd* support table like returns and manipulation
- *tbd* generators for the psql scripts to load functions

## Getting started

This project uses `cargo-make` for automation. While not necessary, it does help with a lot of the build tasks, so is recommended. This can be installed with `cargo install cargo-make`.

Once installed, it will install Postgres into the `target` directory for testing. There are profiles for each supported Postgres version, `v10`, `v11`, and `v12`. The specific minor version used is in

To run all tests with all features, for example, run:

```shell
> cargo make all-features -p v12 # if -p is left off, then the default is v12
```

## Building

If using `cargo-make` then the environment variable `PG_DIR` can be used to specify the location of the Postgres install.

First install Postgres. The build should be able to find the directory for the Postgres server headers, it uses the `pg_config --includedir-server` to attempt to find the directory. If it is unsuccessful then this environment variable is required:

`PG_INCLUDE_PATH=[/path/to/postgres]/include/server # e.g. /usr/local/pgsql/include/server`

For the dynamic library to compile, your project should also have `.cargo/config` file with content:

```toml
[target.'cfg(unix)']
rustflags = "-C link-arg=-undefineddynamic_lookup"

[target.'cfg(windows)']
rustflags = "-C link-arg=/FORCE"
```

This informs the linker that some of the symbols for Postgres won't be available until runtime on the dynamic library load.

## Running the integration tests

Standard tests can be run with the normal `cargo test`, but the integration tests are a little more involved. They require a connection to an actual Postgres DB. These instructions were performed on macOS. Create a DB in Postgres to be use. In this example a DB was created in the `/usr/local/var/posgres` path, with the name `postgres`. When using `cargo-make` all the automation of starting, installing and setting up the DB is handled for you:

Test all features:

```shell
> cargo make all-features
```

Test default features:

```shell
> cargo make default-features
```

Test no-default-features:

```shell
> cargo make no-default-features
```

Testing against different versions; `v10`, `v11`, `v12` are valid:

```shell
> cargo make all-features -p v10
```

### Without cargo-make

To run the test must know the DB name to use, the DB must be running, and then the tests can be run:

```shell
export POSTGRES_TEST_DB=postgres

pg_ctl -D /usr/local/var/postgres start
cargo test
```

## Examples

- [adding](https://github.com/bluejekyll/pg-extend-rs/tree/master/examples/adding)
- [panicking](https://github.com/bluejekyll/pg-extend-rs/tree/master/examples/panicking)

## Features

TBD

## Community

For live discussions beyond this repository, please see this [Discord](https://discord.gg/y7ZvY5p).