programming/PostgreSQL/build_rdbms_01/Readme.md

# 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. pg_repack
8. pg_stat_monitor
9. pgvector

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_pg_repack.sh --version 18.6
./install_pg_stat_monitor.sh --version 18.6
./install_pgvector.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.

## 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_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_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 |

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

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 extensions that require server startup loading:

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

`pg_repack` and `set_user` do not require `shared_preload_libraries`. `pg_stat_activity` is a PostgreSQL system view and is not installed as an extension.

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

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