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

After a successful run, the orchestrator:

- Optionally updates `shared_preload_libraries` when `CONFIG_FILE` is set.
- Prints the installed PostgreSQL and extension versions.
- Creates `postgresql-<version>-engine.tar.gz` in the directory from which the command was launched.
- Writes the complete process log to `postgresql-<version>-process.log` in that same directory.

## Individual installers

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

```bash
./install_postgresql.sh 18.6
./install_pg_cron.sh 18.6
./install_timescaledb.sh 18.6
./install_pgaudit.sh 18.6
./install_set_user.sh 18.6
./install_pg_stat_statements.sh 18.6
./install_pg_repack.sh 18.6
./install_pg_stat_monitor.sh 18.6
```

`install_postgresql.sh` recreates both the staging directory and the versioned PostgreSQL prefix before downloading sources. Extension installers recreate only the staging directory and preserve the PostgreSQL prefix.

## 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. The build 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_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 |
| `STAGING_DIR` | `/app/staging_area/copilot/tmp` | Temporary 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 |

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

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.