# PostgreSQL Source Installation Scripts

These shell scripts build PostgreSQL from source and install PostgreSQL extensions into a versioned prefix:

```text
/app/postgres/rdbms/<postgresql-version>
```

The scripts use strict Bash error handling and require a working compiler and build environment. Sources are downloaded from the PostgreSQL FTP site and GitHub repositories.

## Install everything

Run the orchestrator with the PostgreSQL version to install:

```bash
./install_postgresql_extensions.sh 18.6
```

The version may also be supplied explicitly with `-v` or `--version`:

```bash
./install_postgresql_extensions.sh --version 18.6
```

The orchestrator accepts a custom installation prefix and PostgreSQL `configure` options:

```bash
./install_postgresql_extensions.sh \
  --version 18.6 \
  --prefix /app/postgres/rdbms/18.6 \
  --options="--with-ssl=openssl,--with-lz4"
```

`-p`/`--prefix` defaults to `/app/postgres/rdbms/<version>`. `-o`/`--options` accepts a comma-separated list of `configure` arguments; if omitted, the defaults are `--with-ssl=openssl,--with-lz4`. The prefix is passed to all component installers. If the selected prefix already exists, the orchestrator asks whether to recreate it; the prompt defaults to No, and non-interactive runs cancel safely.

The orchestrator runs the installers in this order:

1. PostgreSQL
2. pg_cron
3. TimescaleDB
4. pgAudit
5. set_user
6. pg_stat_statements
7. auto_explain
8. passwordcheck
9. pg_repack
10. pg_stat_monitor
11. pgvector
12. HypoPG
13. pg_hint_plan
14. wal2json

After a successful run, the orchestrator:

- Optionally updates `shared_preload_libraries` when `CONFIG_FILE` is set.
- Prints the installed PostgreSQL and extension versions.
- Recreates `sources/<complete-version>/` before starting, where `<complete-version>` is the final directory name of the selected prefix (for example, prefix `/app/postgres/rdbms/18.6.3` uses `sources/18.6.3/`). Each successfully installed component's source tree is saved there with an executable `install_<postgresql-version>.sh` recipe containing that component's configure/build/install commands.
- Creates `postgresql-<prefix-basename>-engine.tar.gz` in the directory from which the command was launched (for example, a prefix ending in `18.6.3` produces `postgresql-18.6.3-engine.tar.gz`).
- Writes the complete process log to `postgresql-<version>-process.log` in that same directory.
- Prints and logs the total execution duration in hours, minutes, and seconds.

## Individual installers

Each component can also be installed independently. The PostgreSQL installation must already exist before running an extension installer.

```bash
./install_postgresql.sh --version 18.6
./install_pg_cron.sh --version 18.6
./install_timescaledb.sh --version 18.6
./install_pgaudit.sh --version 18.6
./install_set_user.sh --version 18.6
./install_pg_stat_statements.sh --version 18.6
./install_auto_explain.sh --version 18.6
./install_passwordcheck.sh --version 18.6
./install_pg_repack.sh --version 18.6
./install_pg_stat_monitor.sh --version 18.6
./install_pgvector.sh --version 18.6
./install_hypopg.sh --version 18.6
./install_pg_hint_plan.sh --version 18.6
./install_wal2json.sh --version 18.6
```

Each installer also accepts `-v 18.6` and the previous positional form (`./install_pg_cron.sh 18.6`). The all-in-one orchestrator passes its complete `--version` value to every component installer.

All source downloads, extracted source trees, and build workspaces use the `tmp/` directory alongside the scripts by default. `install_postgresql.sh` recreates that staging directory and the versioned PostgreSQL prefix before downloading sources. Each extension installer recreates only the staging directory and preserves the PostgreSQL prefix.

When the main orchestrator is invoked without `--help` or `-h`, it first recreates `tmp/` alongside the scripts. Help mode prints usage only and does not create, delete, or modify files.

Every installer accepts `--help` or `-h`, for example:

```bash
./install_pgvector.sh --help
```

The generated `install_<version>.sh` recipes also accept `--help`/`-h` and can be run from their saved component source directory to repeat that component's configure/build/install steps.

## Resuming a failed extension build

If an extension build fails, rerun that extension's standalone installer with the same PostgreSQL version and installation prefix. The standalone installer rebuilds only that extension and preserves the installed PostgreSQL prefix. For example, to retry HypoPG for PostgreSQL 17.11 installed in a custom prefix:

```bash
PREFIX=/app/staging_area/postgres/rdbms/17.11/ ./install_hypopg.sh --version 17.11
```

Replace `install_hypopg.sh` with the failed extension's installer, and use the prefix where PostgreSQL is installed. If you used the default prefix, omit `PREFIX`:

```bash
./install_hypopg.sh --version 17.11
```

## Script descriptions

### `install_postgresql_extensions.sh`

All-in-one entry point. It invokes every installer, applies optional configuration changes, prints a product summary, writes a process log, and packages the installed PostgreSQL prefix.

### `install_postgresql.sh`

Downloads, configures, builds, and installs PostgreSQL. By default, `configure` uses:

```text
--with-ssl=openssl
--with-lz4
```

### `install_pg_cron.sh`

Builds and installs `pg_cron` against the selected PostgreSQL installation.

### `install_timescaledb.sh`

Bootstraps and builds TimescaleDB with CMake, installing it into the selected PostgreSQL prefix.

### `install_pgaudit.sh`

Builds and installs pgAudit using PostgreSQL PGXS. It selects a tag matching the PostgreSQL major version when possible.

### `install_set_user.sh`

Builds and installs the `set_user` extension using the selected PostgreSQL `pg_config`.

### `install_pg_stat_statements.sh`

Downloads the matching PostgreSQL source tree and builds `pg_stat_statements` from `contrib` using PGXS.

### `install_passwordcheck.sh`

Downloads the matching PostgreSQL source tree and builds the `passwordcheck` contrib module using PGXS. The module is loaded at server startup through `shared_preload_libraries`; it does not have a `CREATE EXTENSION` control file.

### `install_pg_repack.sh`

Builds and installs the `pg_repack` extension and its `pg_repack` command-line utility.

### `install_pg_stat_monitor.sh`

Builds and installs Percona's `pg_stat_monitor` extension.

### `install_pgvector.sh`

Builds and installs pgvector against the selected PostgreSQL installation.

### `install_auto_explain.sh`

Builds and installs PostgreSQL's `auto_explain` contrib module from the matching PostgreSQL source. It has no `CREATE EXTENSION` control file; load it in sessions with `LOAD 'auto_explain'` or configure it for server startup.

### `install_hypopg.sh`

Builds and installs HypoPG against the selected PostgreSQL installation. Create the extension in each database where it will be used with `CREATE EXTENSION hypopg`.

### `install_pg_hint_plan.sh`

Builds and installs the pg_hint_plan tag matching the PostgreSQL major version when available. Create it in each database where it will be used with `CREATE EXTENSION pg_hint_plan`.

### `install_wal2json.sh`

Builds and installs wal2json as a PostgreSQL logical decoding output plugin. It does not use `CREATE EXTENSION` or require `shared_preload_libraries`; configure PostgreSQL with `wal_level = logical` and restart the server before creating a logical replication slot that uses the `wal2json` plugin.

### `install_common.sh`

Shared helper functions used by the installers, including:

- Required-command checks
- PostgreSQL version validation
- GitHub release/tag lookup
- Source download and extraction
- Staging-directory reset
- PostgreSQL-prefix validation

## Configuration

The following environment variables can override defaults:

| Variable | Default | Purpose |
| --- | --- | --- |
| `POSTGRES_ROOT` | `/app/postgres/rdbms` | Root directory for versioned PostgreSQL installations |
| `-p`, `--prefix` | `/app/postgres/rdbms/<version>` | Exact PostgreSQL installation prefix |
| `-o`, `--options` | `--with-ssl=openssl,--with-lz4` | Comma-separated PostgreSQL `configure` options |
| `STAGING_DIR` | `<script directory>/tmp` | Temporary source downloads, extracted source, and build directory |
| `JOBS` | `nproc` result | Parallel build job count |
| `CONFIG_FILE` | unset | PostgreSQL configuration file to update |
| `PG_CRON_TAG` | Latest compatible release/tag | pg_cron source tag |
| `TIMESCALEDB_TAG` | Latest release/tag | TimescaleDB source tag |
| `PGAUDIT_TAG` | PostgreSQL-major-compatible tag | pgAudit source tag |
| `SET_USER_TAG` | Latest release/tag | set_user source tag |
| `PG_REPACK_TAG` | Latest release/tag | pg_repack source tag |
| `PG_STAT_MONITOR_TAG` | Latest release/tag | pg_stat_monitor source tag |
| `PGVECTOR_TAG` | Latest release/tag | pgvector source tag |
| `HYPOPG_TAG` | Latest release/tag | HypoPG source tag |
| `PG_HINT_PLAN_TAG` | PostgreSQL-major-compatible tag | pg_hint_plan source tag |
| `WAL2JSON_TAG` | Latest release/tag | wal2json source tag |

Repository variables can also be overridden when using a custom mirror:

```bash
PG_CRON_REPOSITORY=owner/repository
TIMESCALEDB_REPOSITORY=owner/repository
PGAUDIT_REPOSITORY=owner/repository
SET_USER_REPOSITORY=owner/repository
PG_REPACK_REPOSITORY=owner/repository
PG_STAT_MONITOR_REPOSITORY=owner/repository
PGVECTOR_REPOSITORY=owner/repository
HYPOPG_REPOSITORY=owner/repository
PG_HINT_PLAN_REPOSITORY=owner/repository
WAL2JSON_REPOSITORY=owner/repository
```

Example:

```bash
JOBS=8 \
PG_CRON_TAG=v1.6.5 \
TIMESCALEDB_TAG=2.19.3 \
PGAUDIT_TAG=17.1 \
SET_USER_TAG=REL4_2_0 \
./install_postgresql_extensions.sh 17.11
```

When `CONFIG_FILE` is supplied, the orchestrator adds the modules and extensions that require server startup loading:

```conf
shared_preload_libraries = 'pg_cron,timescaledb,pgaudit,pg_stat_statements,pg_stat_monitor,passwordcheck'
```

`pg_repack`, pgvector, HypoPG, `set_user`, and wal2json do not require `shared_preload_libraries`. `auto_explain` and pg_hint_plan can be loaded per session or configured for server startup; they are not added automatically. wal2json is a logical decoding output plugin and requires `wal_level = logical` plus a server restart before use. `passwordcheck` and `auto_explain` are PostgreSQL contrib modules (not SQL extensions), and `pg_stat_activity` is a built-in PostgreSQL system view.

## Prerequisites

The scripts check for the tools needed by each build. The complete procedure requires:

- Bash
- `curl`
- `tar`
- `make`
- `gcc`
- `cmake`
- `python3` when `CONFIG_FILE` is used
- Standard PostgreSQL build dependencies, including OpenSSL and LZ4 development libraries

## Validation

Validate all shell scripts:

```bash
for script in install_*.sh; do
  bash -n "$script"
done
```

Check an installed PostgreSQL version:

```bash
/app/postgres/rdbms/18.6/bin/postgres --version
/app/postgres/rdbms/18.6/bin/pg_config --version
```

Check installed extension files:

```bash
ls \
  /app/postgres/rdbms/18.6/lib/pg_cron.so \
  /app/postgres/rdbms/18.6/lib/timescaledb.so \
  /app/postgres/rdbms/18.6/lib/pgaudit.so \
  /app/postgres/rdbms/18.6/lib/set_user.so \
  /app/postgres/rdbms/18.6/lib/pg_stat_monitor.so \
  /app/postgres/rdbms/18.6/lib/auto_explain.so \
  /app/postgres/rdbms/18.6/lib/hypopg.so \
  /app/postgres/rdbms/18.6/lib/pg_hint_plan.so \
  /app/postgres/rdbms/18.6/lib/wal2json.so
```

The extension SQL objects still need to be created in each target database with PostgreSQL's `CREATE EXTENSION` command.