Files
programming/PostgreSQL/build_rdbms_01/Readme.md
T

268 lines
10 KiB
Markdown
Raw Normal View History

2026-09-23 17:19:50 +02:00
# 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
```
2026-10-11 16:45:57 +02:00
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.
2026-09-23 17:19:50 +02:00
The orchestrator runs the installers in this order:
1. PostgreSQL
2. pg_cron
3. TimescaleDB
4. pgAudit
5. set_user
6. pg_stat_statements
2026-10-20 11:20:10 +02:00
7. auto_explain
8. passwordcheck
9. pg_repack
10. pg_stat_monitor
11. pgvector
12. HypoPG
13. pg_hint_plan
2026-09-23 17:19:50 +02:00
After a successful run, the orchestrator:
- Optionally updates `shared_preload_libraries` when `CONFIG_FILE` is set.
- Prints the installed PostgreSQL and extension versions.
2026-10-11 16:45:57 +02:00
- 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`).
2026-09-23 17:19:50 +02:00
- Writes the complete process log to `postgresql-<version>-process.log` in that same directory.
2026-10-11 16:45:57 +02:00
- Prints and logs the total execution duration in hours, minutes, and seconds.
2026-09-23 17:19:50 +02:00
## Individual installers
Each component can also be installed independently. The PostgreSQL installation must already exist before running an extension installer.
```bash
2026-10-11 16:45:57 +02:00
./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
2026-10-20 11:20:10 +02:00
./install_auto_explain.sh --version 18.6
2026-10-15 17:35:23 +02:00
./install_passwordcheck.sh --version 18.6
2026-10-11 16:45:57 +02:00
./install_pg_repack.sh --version 18.6
./install_pg_stat_monitor.sh --version 18.6
./install_pgvector.sh --version 18.6
2026-10-20 11:20:10 +02:00
./install_hypopg.sh --version 18.6
./install_pg_hint_plan.sh --version 18.6
2026-09-23 17:19:50 +02:00
```
2026-10-11 16:45:57 +02:00
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.
2026-10-11 09:00:59 +02:00
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.
2026-09-23 17:19:50 +02:00
2026-10-11 16:45:57 +02:00
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.
2026-09-23 17:19:50 +02:00
## 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`
2026-10-11 16:45:57 +02:00
Downloads, configures, builds, and installs PostgreSQL. By default, `configure` uses:
2026-09-23 17:19:50 +02:00
```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.
2026-10-15 17:35:23 +02:00
### `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.
2026-09-23 17:19:50 +02:00
### `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.
2026-10-11 09:00:59 +02:00
### `install_pgvector.sh`
Builds and installs pgvector against the selected PostgreSQL installation.
2026-10-20 11:20:10 +02:00
### `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`.
2026-09-23 17:19:50 +02:00
### `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 |
2026-10-11 16:45:57 +02:00
| `-p`, `--prefix` | `/app/postgres/rdbms/<version>` | Exact PostgreSQL installation prefix |
| `-o`, `--options` | `--with-ssl=openssl,--with-lz4` | Comma-separated PostgreSQL `configure` options |
2026-10-11 09:00:59 +02:00
| `STAGING_DIR` | `<script directory>/tmp` | Temporary source downloads, extracted source, and build directory |
2026-09-23 17:19:50 +02:00
| `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 |
2026-10-11 09:00:59 +02:00
| `PGVECTOR_TAG` | Latest release/tag | pgvector source tag |
2026-10-20 11:20:10 +02:00
| `HYPOPG_TAG` | Latest release/tag | HypoPG source tag |
| `PG_HINT_PLAN_TAG` | PostgreSQL-major-compatible tag | pg_hint_plan source tag |
2026-09-23 17:19:50 +02:00
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
2026-10-11 09:00:59 +02:00
PGVECTOR_REPOSITORY=owner/repository
2026-10-20 11:20:10 +02:00
HYPOPG_REPOSITORY=owner/repository
PG_HINT_PLAN_REPOSITORY=owner/repository
2026-09-23 17:19:50 +02:00
```
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
```
2026-10-15 17:35:23 +02:00
When `CONFIG_FILE` is supplied, the orchestrator adds the modules and extensions that require server startup loading:
2026-09-23 17:19:50 +02:00
```conf
2026-10-15 17:35:23 +02:00
shared_preload_libraries = 'pg_cron,timescaledb,pgaudit,pg_stat_statements,pg_stat_monitor,passwordcheck'
2026-09-23 17:19:50 +02:00
```
2026-10-20 11:20:10 +02:00
`pg_repack`, pgvector, HypoPG, and `set_user` 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. `passwordcheck` and `auto_explain` are PostgreSQL contrib modules (not SQL extensions), and `pg_stat_activity` is a built-in PostgreSQL system view.
2026-09-23 17:19:50 +02:00
## 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 \
2026-10-20 11:20:10 +02:00
/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
2026-09-23 17:19:50 +02:00
```
The extension SQL objects still need to be created in each target database with PostgreSQL's `CREATE EXTENSION` command.