PGX: Write Postgres extensions in Rust instead oc C
source link: https://github.com/zombodb/pgx
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
pgx
Build Postgres Extensions with Rust!
pgx
is a framework for developing PostgreSQL extensions in Rust and wants to make that process as idiomatic and safe as possible. Currently, pgx
supports Postgres v10, v11, and v12.
Key Features
- A cargo sub-command (
pgx
) for creating, compiling/installing, and testing extensions - Postgres
Datum
<-->Rust type conversion viapgx::IntoDatum
andpgx::FromDatum
- Safe handling of
NULL
Datums -- Datums are simplyOption<T>
- Translation of Rust
panic!()
s into PostgresERROR
s, which abort the current transaction instead of the Postgres cluster -
#[derive(PostgresType)]
macro for automatically generating Postgres types based on Rust structs -
#[derive(PostgresEnum)]
macro for automatically generating Postgres enums based on Rust enums -
extension_sql!()
macro for providing custom extension schema DDL -
#[pg_extern]
proc-macro for automatically creating UDFs - Automatic extension schema generation
- Transparent support for generating Set Returning Functions (SRFs) by returning a
std::iter::Iterator<Item = T>
-
#[pg_test]
proc-macro for unit tests that run in-proccess in Postgres -
PgMemoryContexts
wrapper around Postgres' "MemoryContext" system - Executor/planner/transaction/subtransaction hook support
-
#[pg_guard]
proc-macro for guardingextern "C"
Rust functions that need to be passed into Postgres - Basic SPI support
- Direct
unsafe
access to large parts of Postgres internals via thepgx::pg_sys
module - Separation of Postgres symbols (types, functions, etc) by what's common across all supported versions, and then version-specific modules
- lots more!
Getting Started
First you'll want to install the pgx
cargo sub-command from crates.io. You'll use it almost exclusively during your development and testing workflow.
$ cargo install cargo-pgx
It has a number of sub-commands. For example, to create a new extension project, simply run:
$ cargo pgx new my_extension
Then cd my_extension
and run:
$ cargo pgx install
The first time, this will take awhile. Behind the scenes, pgx
is downloading, configuring, compiling and installing (within target/
) Postgres v10, v11, and v12. All of this happens in the target/
directory and the artifacts will remain until a cargo clean
. This is necessary in order to generate the proper Rust bindings for Postgres internals.
Note that cargo pgx install
will compile your extension and then install it to your locally installed Postgres instance as identified by pg_config
, so make sure that pg_config
is in your $PATH
.
From here, you can create a Postgres database and create your extension in it:
$ createdb test $ psql test > CREATE EXTENSION my_extension; > SELECT hello_my_extension();
Digging Deeper
Contributing
We are most definitely open to contributions of any kind. Bug Reports, Feature Requests, Documentation, and even sponsorships .
Providing wrappers for Postgres' internals is not a straightforward task, and completely wrapping it is going to take quite a bit of time. pgx
is generally ready for use now, and it will continue to be developed as time goes on. Your feedback about what you'd like to be able to do with pgx
is greatly appreciated.
License
Copyright 2020 ZomboDB, LLC <[email protected]>. All rights reserved. Use of this source code is governed by the MIT license that can be found in the LICENSE file.
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK