Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
210 lines (136 loc) · 6.45 KB

CONTRIBUTING.md

File metadata and controls

210 lines (136 loc) · 6.45 KB

Contributing to Postgres Message Queue (PGMQ)

Installation

The fastest way to get started is by running the docker image, where PGMQ comes pre-installed.

docker run -d --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 ghcr.io/pgmq/pgmq-pg:latest

PGXN Installation

PGXN is a distributed network of extensions that make it easier to install and manage PostgreSQL extensions.

Install PGXN Client:

You can install the PGXN client by following the instructions provided in the PGXN Client Installation Guide

Install PGMQ using PGXN

pgxn install pgmq

Alternatively, you can manually install PGMQ by downloading and building from the source using the following commands:

Note: Run these commands as the user who owns the PostgreSQL installation (often root on Unix-based systems) or use sudo if necessary.

curl -LO https://api.pgxn.org/dist/pgmq/1.4.2/pgmq-1.4.2.zip
unzip pgmq-1.4.2.zip
cd pgmq-1.4.2
make
make install

Building from source

PGMQ requires the postgres-server-dev package to build. For example, to install version 14 on ubuntu:

sudo apt-get install postgres-server-dev-14

Platform-Specific Installation Instructions

Windows Installation

If you're working on native Windows, follow these steps to install and build pgmq:

  1. Install PostgreSQL for Windows

  • Download the official PostgreSQL installer from PostgreSQL Windows Downloads.

  • Follow the installation process, ensuring you include pgAdmin and Command Line Tools

  • After installation, add the PostgreSQL binary directory (typically C:\Program Files\PostgreSQL\<version>\bin) to your system's PATH environment variable. This will allow access to PostgreSQL tools like pg_config.

  1. Install Build Tools (MinGW)
  • Download and install MinGW from MinGW. Select the GCC compiler for C/C++
  • During installation, ensure the binaries are added to the PATH. MinGW is essential for compiling the pgmq extension on Windows.
  1. Install pgmq from Source
  • Download the pgmq source:
Invoke-WebRequest -Uri https://api.pgxn.org/dist/pgmq/1.4.2/pgmq-1.4.2.zip -OutFile pgmq-1.4.2.zip
Expand-Archive -Path pgmq-1.4.2.zip -DestinationPath .\pgmq-1.4.2
cd .\pgmq-1.4.2

- Build and install `pgmq`: Use the following commands to compile and install pgmq using MinGW:

```bash
make PG_CONFIG="C:/Program Files/PostgreSQL/<version>/bin/pg_config"
make install
  1. Create the pgmq Extension
  • After installation, connect to PostgreSQL and create the pgmq extension:
CREATE EXTENSION pgmq cascade;

Mac Installation

If you are using macOS, you can install PostgreSQL and build PGMQ using Homebrew.

  1. Install PostgreSQL using Homebrew:
brew install postgresql
  1. Clone the PGMQ repository and build it:
git clone https://github.com/pgmq/pgmq.git
cd pgmq/pgmq-extension
make
sudo make install
  1. Create the extension in PostgreSQL:
CREATE EXTENSION pgmq cascade;

Installing Postgres

If you already have Postgres installed locally, you can skip to Install PGMQ to Postgres.

If you need to install Postgres or want to set up a new environment for PGMQ development, pgenv is a command line utility that makes it very easy to install and manage multiple versions of Postgres. Follow the installation instructions to install it. If you are on MacOS, you may need link brew link icu4c --force in order to successfully build Postgres.

Install Postgres 16.3

pgenv build 16.3
pgenv use 16.3

Connect to Postgres:

psql -U postgres

A fresh install will have not have PGMQ installed.

postgres=# \dx
                 List of installed extensions
  Name   | Version |   Schema   |         Description
---------+---------+------------+------------------------------
 plpgsql | 1.0     | pg_catalog | PL/pgSQL procedural language
(1 row)

Installing PGMQ

Clone the repo and change into the directory.

git clone https://github.com/pgmq/pgmq.git
cd pgmq/pgmq-extension

Install PGMQ to Postgres

This will install the extension to the Postgres using the pg_config that is currently on your PATH. If you have multiple versions of Postgres installed, make sure you are using the correct installation by running make install PG_CONFIG=/path/to/pg_config.

make
make install

Finally, you can create the extension and get started with the example in the README.md.

CREATE EXTENSION pgmq cascade;

Installing pg_partman (optional)

If you are working with partitioned queues, you will need to install pg_partman version <= 4.7.0

make install-pg-partman

Then,

CREATE EXTENSION pg_partman;

Running tests

Tests are written for pg_regress and pg_isolation_regress. The latter is available on Postgres 14 and higher, so the Makefile skips them for earlier versions.

Once you have a postgres instance with the extension installed, run:

make installcheck

Releases

The PGMQ Postgres Extension is released as a bundle with Postgres (in a container) and as PGXN distribution. Both of these flows are managed in a Github workflow. To create a release,

  1. Update and commit the new valid semver version in pgmq.control.
  2. Create a Github release using the extension's version for the tag and title. Auto-generate the release notes and/or add more relevant details as needed.

Container Images

Postgres images with PGMQ and all required dependencies are built and published to ghcr.io/pgmq/pg{PG_VERSION}-pgmq:{TAG} for all supported Postgres versions and PGMQ releases.

Extension Packages

The required extension files are publish to and hosted at PGXN.

Client SDKs

See subdirectories for the Rust and Python SDK release processes.