Postgres Message Queue (PGMQ)

The Rust client for PGMQ. This gives you an ORM-like experience with the Postgres extension and makes managing connection pools, transactions, and serialization/deserialization much easier.

Installing PGMQ

PGMQ can be installed into any existing Postgres database using this Rust client. This is useful if the PGMQ extension is not supported by your PostgreSQL instance. The installation performed by the Rust client is versioned, which means it can be used to perform a fresh installation of PGMQ, or it can upgrade an existing installation to a newer version.

Two installation methods are supported. One method uses SQL scripts embedded in the Rust crate, while the other fetches the SQL scripts from the PGMQ GitHub repo. The embedded approach does not require external network requests but only supports installing (or upgrading to) the version bundled with the crate. The GitHub approach requires several network requests to GitHub, but allows installing (or upgrading to) any version available in the repo.

Create the DB

Run standard Postgres using Docker:

docker run -d -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:latest

Initialize applied migrations table

In crate versions <= 0.32.1, the crate did not track which SQL scripts had already been run, which makes upgrading to a new version difficult. To switch from the old approach to the new approach, first perform the "initialize applied migrations table" workflow.

This method is not needed for fresh installations, or if the new SQL-only installation method was used to install PGMQ.

Via the CLI

# Install the PGMQ Rust CLI
cargo install pgmq --features cli --bin pgmq-cli
# Replace the DB url and the version
pgmq-cli install -d postgres://postgres:postgres@localhost:5432/postgres init-migrations-table -v 1.9.0

In Rust

Add PGMQ to your Cargo.toml with the install-sql feature enabled:

cargo add pgmq --features install-sql

async fn init_migrations_table(pool: sqlx::Pool<sqlx::Postgres>) -> Result<(), pgmq::PgmqError> {
    let queue = pgmq::PGMQueueExt::new_with_pool(pool).await;
    // Replace the version
    queue.init_migrations_table("1.9.0").await?;
    Ok(())
}

Install using the embedded scripts

Via CLI

# Install the PGMQ Rust CLI
cargo install pgmq --features cli --bin pgmq-cli
# Replace the DB url
pgmq-cli install -d postgres://postgres:postgres@localhost:5432/postgres install-from-embedded

In Rust

See also, the install example

Add PGMQ to your Cargo.toml with the install-sql-embedded feature enabled:

cargo add pgmq --features install-sql-embedded

async fn install_sql(pool: sqlx::Pool<sqlx::Postgres>) -> Result<(), pgmq::PgmqError> {
    let queue = pgmq::PGMQueueExt::new_with_pool(pool).await;
    queue.install_sql_from_embedded().await?;
    Ok(())
}

Install using the scripts fetched from GitHub

Via CLI

# Install the PGMQ Rust CLI
cargo install pgmq --features cli --bin pgmq-cli
# Replace the DB url and the version
pgmq-cli install -d postgres://postgres:postgres@localhost:5432/postgres install-from-github -v 1.9.0

In Rust

See also, the install example

Add PGMQ to your Cargo.toml with the install-sql-github feature enabled:

cargo add pgmq --features install-sql-github

async fn install_sql(pool: sqlx::Pool<sqlx::Postgres>) -> Result<(), pgmq::PgmqError> {
    let queue = pgmq::PGMQueueExt::new_with_pool(pool).await;
    queue.install_sql_from_github(Some("1.9.0")).await?;
    Ok(())
}

Examples

The project contains several examples. You can run these using Cargo.

A basic example displaying the primary features:

cargo run --example basic

How to install PGMQ using the Rust client from within your application:

cargo run --example install --features install-sql-github,install-sql-embedded

Serialization and Deserialization

Messages can be parsed as serde_json::Value or into a struct of your design. queue.read() returns an Result<Option<Message<T>>, PgmqError> where T is the type of the message on the queue. It returns an error when there is an issue parsing the message (PgmqError::JsonParsingError) or if PGMQ is unable to reach postgres (PgmqError::DatabaseError).

License: PostgreSQL