Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Installation Guide for PGMQ #323

Merged
merged 7 commits into from
Nov 6, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 95 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,31 @@ The fastest way to get started is by running the Tembo docker image, where PGMQ
docker run -d --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 quay.io/tembo/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](https://pgxn.github.io/pgxnclient/install.html)

Install PGMQ using PGXN

```bash
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
Expand All @@ -17,13 +42,81 @@ 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](https://www.postgresql.org/download/windows/).

- 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`.

2. Install Build Tools (MinGW)

- Download and install [MinGW](https://sourceforge.net/projects/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.

3. Install `pgmq` from Source

- Download the `pgmq` source:

```powershell
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
```

4. Create the pgmq Extension

- After installation, connect to PostgreSQL and create the pgmq extension:

```sql
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:

```bash
brew install postgresql
```

2. Clone the PGMQ repository and build it:

```bash
git clone https://github.com/tembo-io/pgmq.git
cd pgmq/pgmq-extension
make
sudo make install
```

3. Create the extension in PostgreSQL:

```sql
CREATE EXTENSION pgmq cascade;
```

## Installing Postgres

If you already have Postgres installed locally, you can skip to [Install PGMQ to Postgres](#install-pgmq-to-postgres).

If you need to install Postgres or want to set up a new environment for PGMQ development, [pgenv](https://github.com/theory/pgenv/) is a command line utility that makes it very easy to install and manage multiple versions of Postgres.
Follow the [installation instructions](https://github.com/theory/pgenv/?tab=readme-ov-file#installation) to install it.
If you are on MacOS, you may need link `brew link icu4c --force` in order to successfully build Postgres.
Follow the [installation instructions](https://github.com/theory/pgenv/?tab=readme-ov-file#installation) 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

Expand Down