multi_compress 0.3.5 → 0.5.0

data/db_deployment/mysql/bin/doctor

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MYSQL="${MYSQL:-mysql}"
+DEFAULTS_FILE=""
+MYSQL_SOCKET="${MYSQL_SOCKET:-}"
+
+usage() {
+  cat <<'TEXT'
+Usage: MYSQL_SOCKET=/run/mysqld/mysqld.sock ./bin/doctor [--mysql PATH] [--defaults-extra-file PATH]
+
+Run this on the MySQL 5.7 host. The bundle uses a local Unix socket so the UDF
+library is installed into the plugin_dir of that same mysqld.
+TEXT
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --mysql)
+      [ "$#" -ge 2 ] || { echo '--mysql requires a path' >&2; exit 2; }
+      MYSQL="$2"; shift 2 ;;
+    --defaults-extra-file)
+      [ "$#" -ge 2 ] || { echo '--defaults-extra-file requires a path' >&2; exit 2; }
+      DEFAULTS_FILE="$2"; shift 2 ;;
+    --help|-h)
+      usage; exit 0 ;;
+    *)
+      echo "multi_compress mysql doctor: unknown option: $1" >&2; exit 2 ;;
+  esac
+done
+
+# shellcheck source=common
+source "$ROOT/bin/common"
+mcdb_resolve_mysql
+mcdb_mysql_args
+command -v make >/dev/null 2>&1 || mcdb_die 'make is required'
+command -v cc >/dev/null 2>&1 || mcdb_die 'a C compiler is required (cc/gcc/clang)'
+command -v ar >/dev/null 2>&1 || mcdb_die 'ar is required'
+mcdb_require_mysql57
+mcdb_require_expected_socket
+
+PLUGIN_DIR="$(mcdb_plugin_dir)"
+SERVER_SOCKET="$(mcdb_server_socket)"
+SERVER_HOSTNAME="$(mcdb_server_hostname)"
+MAX_ALLOWED_PACKET="$(mcdb_server_max_allowed_packet)"
+[ -n "$PLUGIN_DIR" ] || mcdb_die 'MySQL returned an empty @@plugin_dir'
+[ -d "$PLUGIN_DIR" ] || mcdb_die "@@plugin_dir is not a local directory: $PLUGIN_DIR"
+case "$MAX_ALLOWED_PACKET" in
+  ''|*[!0-9]*) mcdb_die "MySQL returned an invalid @@GLOBAL.max_allowed_packet: $MAX_ALLOWED_PACKET" ;;
+esac
+if [ "$MAX_ALLOWED_PACKET" -lt 33554432 ]; then
+  echo "multi_compress mysql doctor: WARNING @@GLOBAL.max_allowed_packet is ${MAX_ALLOWED_PACKET}; configure at least 32M for the 16 MiB MCDB1 limit" >&2
+fi
+
+printf '%s\n' \
+  "MySQL: $(mcdb_server_version)" \
+  "mysql client: $MYSQL" \
+  "server hostname: $SERVER_HOSTNAME" \
+  "server socket: $SERVER_SOCKET" \
+  "plugin directory: $PLUGIN_DIR" \
+  "max_allowed_packet: $MAX_ALLOWED_PACKET" \
+  "bundle: $ROOT" \
+  'doctor: OK'

data/db_deployment/mysql/bin/enable

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MYSQL="${MYSQL:-mysql}"
+DEFAULTS_FILE=""
+MYSQL_SOCKET="${MYSQL_SOCKET:-}"
+
+usage() {
+  cat <<'TEXT'
+Usage: MYSQL_SOCKET=/run/mysqld/mysqld.sock ./bin/enable [--mysql PATH] [--defaults-extra-file PATH]
+
+Registers the three MultiCompress UDFs once. Existing healthy registrations are
+left untouched; this command never drops functions automatically.
+TEXT
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --mysql)
+      [ "$#" -ge 2 ] || { echo '--mysql requires a path' >&2; exit 2; }
+      MYSQL="$2"; shift 2 ;;
+    --defaults-extra-file)
+      [ "$#" -ge 2 ] || { echo '--defaults-extra-file requires a path' >&2; exit 2; }
+      DEFAULTS_FILE="$2"; shift 2 ;;
+    --help|-h)
+      usage; exit 0 ;;
+    *)
+      echo "multi_compress mysql enable: unknown option: $1" >&2; exit 2 ;;
+  esac
+done
+
+# shellcheck source=common
+source "$ROOT/bin/common"
+mcdb_resolve_mysql
+mcdb_mysql_args
+mcdb_require_mysql57
+mcdb_require_expected_socket
+mcdb_read_udf_state
+
+if mcdb_state_is_clean_absent; then
+  mcdb_register_expected_udfs
+  mcdb_read_udf_state
+  mcdb_state_is_clean_enabled || mcdb_die 'registration did not create the expected UDF state'
+  mcdb_smoke_check
+  echo 'MultiCompress MySQL UDFs are enabled. Apply the generated readable-view SQL in the application migration.'
+  exit 0
+fi
+
+if mcdb_state_is_clean_enabled; then
+  mcdb_smoke_check
+  echo 'MultiCompress MySQL UDFs are already enabled; no changes made.'
+  exit 0
+fi
+
+mcdb_require_clean_owned_state
+mcdb_die 'UDF registrations are partial; run make status and resolve the state before enabling'

data/db_deployment/mysql/bin/install

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MYSQL="${MYSQL:-mysql}"
+DEFAULTS_FILE=""
+MYSQL_SOCKET="${MYSQL_SOCKET:-}"
+
+usage() {
+  cat <<'TEXT'
+Usage: sudo MYSQL_SOCKET=/run/mysqld/mysqld.sock ./bin/install [--mysql PATH] [--defaults-extra-file PATH]
+
+Builds and installs a fresh MySQL 5.7 UDF library. It refuses to replace a
+library while any expected UDF is registered; use ./bin/upgrade for upgrades.
+TEXT
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --mysql)
+      [ "$#" -ge 2 ] || { echo '--mysql requires a path' >&2; exit 2; }
+      MYSQL="$2"; shift 2 ;;
+    --defaults-extra-file)
+      [ "$#" -ge 2 ] || { echo '--defaults-extra-file requires a path' >&2; exit 2; }
+      DEFAULTS_FILE="$2"; shift 2 ;;
+    --help|-h)
+      usage; exit 0 ;;
+    *)
+      echo "multi_compress mysql install: unknown option: $1" >&2; exit 2 ;;
+  esac
+done
+
+[ "${EUID:-$(id -u)}" -eq 0 ] || { echo 'multi_compress mysql install: run as root: sudo ./bin/install ...' >&2; exit 2; }
+DOCTOR_ARGS=(--mysql "$MYSQL")
+if [ -n "$DEFAULTS_FILE" ]; then
+  DOCTOR_ARGS+=(--defaults-extra-file "$DEFAULTS_FILE")
+fi
+MYSQL_SOCKET="$MYSQL_SOCKET" "$ROOT/bin/doctor" "${DOCTOR_ARGS[@]}"
+
+# shellcheck source=common
+source "$ROOT/bin/common"
+mcdb_resolve_mysql
+mcdb_mysql_args
+mcdb_read_udf_state
+if ! mcdb_state_is_clean_absent; then
+  mcdb_die 'fresh install refuses to replace a library while UDF registrations exist; run status or upgrade instead'
+fi
+
+PLUGIN_DIR="$(mcdb_plugin_dir)"
+TEMP_LIBRARY="$PLUGIN_DIR/.${MCDB_UDF_LIBRARY}.$$.$RANDOM.tmp"
+trap 'rm -f "$TEMP_LIBRARY"' EXIT
+
+make -C "$ROOT/mysql_udf" clean udf MYSQL_UDF_ABI=mysql57
+install -d -m 0755 "$PLUGIN_DIR"
+install -m 0755 "$ROOT/mysql_udf/build/$MCDB_UDF_LIBRARY" "$TEMP_LIBRARY"
+mv -f "$TEMP_LIBRARY" "$PLUGIN_DIR/$MCDB_UDF_LIBRARY"
+trap - EXIT
+
+printf '%s\n' \
+  'MultiCompress MySQL UDF library installed.' \
+  "  library: $PLUGIN_DIR/$MCDB_UDF_LIBRARY" \
+  '' \
+  'Register the UDFs once on this MySQL server:' \
+  '  make enable'

data/db_deployment/mysql/bin/status

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MYSQL="${MYSQL:-mysql}"
+DEFAULTS_FILE=""
+MYSQL_SOCKET="${MYSQL_SOCKET:-}"
+
+usage() {
+  cat <<'TEXT'
+Usage: MYSQL_SOCKET=/run/mysqld/mysqld.sock ./bin/status [--mysql PATH] [--defaults-extra-file PATH]
+
+Reports MultiCompress UDF registrations. This command needs SELECT on mysql.func.
+TEXT
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --mysql)
+      [ "$#" -ge 2 ] || { echo '--mysql requires a path' >&2; exit 2; }
+      MYSQL="$2"; shift 2 ;;
+    --defaults-extra-file)
+      [ "$#" -ge 2 ] || { echo '--defaults-extra-file requires a path' >&2; exit 2; }
+      DEFAULTS_FILE="$2"; shift 2 ;;
+    --help|-h)
+      usage; exit 0 ;;
+    *)
+      echo "multi_compress mysql status: unknown option: $1" >&2; exit 2 ;;
+  esac
+done
+
+# shellcheck source=common
+source "$ROOT/bin/common"
+mcdb_resolve_mysql
+mcdb_mysql_args
+mcdb_require_mysql57
+mcdb_require_expected_socket
+PLUGIN_DIR="$(mcdb_plugin_dir)"
+LIBRARY="$PLUGIN_DIR/$MCDB_UDF_LIBRARY"
+mcdb_read_udf_state
+
+printf '%s\n' \
+  "MySQL: $(mcdb_server_version)" \
+  "server hostname: $(mcdb_server_hostname)" \
+  "server socket: $(mcdb_server_socket)" \
+  "plugin directory: $PLUGIN_DIR" \
+  "library: $LIBRARY" \
+  "library sha256: $(mcdb_library_checksum "$LIBRARY")"
+
+if [ "${#MCDB_REGISTERED_ROWS[@]}" -eq 0 ]; then
+  echo 'registrations: none'
+else
+  echo 'registrations:'
+  printf '  %s\n' "${MCDB_REGISTERED_ROWS[@]}"
+fi
+
+if mcdb_state_is_clean_enabled; then
+  mcdb_smoke_check
+  echo 'state: enabled'
+elif mcdb_state_is_clean_absent; then
+  echo 'state: absent'
+else
+  echo 'state: inconsistent or foreign registration detected'
+  exit 2
+fi

data/db_deployment/mysql/bin/uninstall

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MYSQL="${MYSQL:-mysql}"
+DEFAULTS_FILE=""
+MYSQL_SOCKET="${MYSQL_SOCKET:-}"
+
+usage() {
+  cat <<'TEXT'
+Usage: sudo MYSQL_SOCKET=/run/mysqld/mysqld.sock ./bin/uninstall [--mysql PATH] [--defaults-extra-file PATH]
+
+Removes MultiCompress-owned UDF registrations and its native library. The Makefile
+requires CONFIRM=REMOVE_MULTI_COMPRESS before this script can run.
+TEXT
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --mysql)
+      [ "$#" -ge 2 ] || { echo '--mysql requires a path' >&2; exit 2; }
+      MYSQL="$2"; shift 2 ;;
+    --defaults-extra-file)
+      [ "$#" -ge 2 ] || { echo '--defaults-extra-file requires a path' >&2; exit 2; }
+      DEFAULTS_FILE="$2"; shift 2 ;;
+    --help|-h)
+      usage; exit 0 ;;
+    *)
+      echo "multi_compress mysql uninstall: unknown option: $1" >&2; exit 2 ;;
+  esac
+done
+
+[ "${EUID:-$(id -u)}" -eq 0 ] || { echo 'multi_compress mysql uninstall: run as root' >&2; exit 2; }
+
+# shellcheck source=common
+source "$ROOT/bin/common"
+mcdb_resolve_mysql
+mcdb_mysql_args
+mcdb_require_mysql57
+mcdb_require_expected_socket
+mcdb_read_udf_state
+mcdb_require_clean_owned_state
+PLUGIN_DIR="$(mcdb_plugin_dir)"
+mcdb_drop_owned_udfs
+rm -f "$PLUGIN_DIR/$MCDB_UDF_LIBRARY"
+
+echo "MultiCompress MySQL UDFs disabled and library removed from $PLUGIN_DIR."

data/db_deployment/mysql/bin/upgrade

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MYSQL="${MYSQL:-mysql}"
+DEFAULTS_FILE=""
+MYSQL_SOCKET="${MYSQL_SOCKET:-}"
+
+usage() {
+  cat <<'TEXT'
+Usage: sudo MYSQL_SOCKET=/run/mysqld/mysqld.sock ./bin/upgrade [--mysql PATH] [--defaults-extra-file PATH]
+
+Performs the required MySQL UDF upgrade order: DROP FUNCTION, replace the
+library, CREATE FUNCTION, then smoke-check. The Makefile requires
+CONFIRM=UPGRADE_MULTI_COMPRESS before this script can run.
+TEXT
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --mysql)
+      [ "$#" -ge 2 ] || { echo '--mysql requires a path' >&2; exit 2; }
+      MYSQL="$2"; shift 2 ;;
+    --defaults-extra-file)
+      [ "$#" -ge 2 ] || { echo '--defaults-extra-file requires a path' >&2; exit 2; }
+      DEFAULTS_FILE="$2"; shift 2 ;;
+    --help|-h)
+      usage; exit 0 ;;
+    *)
+      echo "multi_compress mysql upgrade: unknown option: $1" >&2; exit 2 ;;
+  esac
+done
+
+[ "${EUID:-$(id -u)}" -eq 0 ] || { echo 'multi_compress mysql upgrade: run as root' >&2; exit 2; }
+DOCTOR_ARGS=(--mysql "$MYSQL")
+if [ -n "$DEFAULTS_FILE" ]; then
+  DOCTOR_ARGS+=(--defaults-extra-file "$DEFAULTS_FILE")
+fi
+MYSQL_SOCKET="$MYSQL_SOCKET" "$ROOT/bin/doctor" "${DOCTOR_ARGS[@]}"
+
+# shellcheck source=common
+source "$ROOT/bin/common"
+mcdb_resolve_mysql
+mcdb_mysql_args
+mcdb_read_udf_state
+mcdb_require_clean_owned_state
+mcdb_state_is_clean_enabled || mcdb_die 'upgrade requires all three MultiCompress UDFs to be enabled'
+CAPTURED_REGISTRATIONS=("${MCDB_REGISTERED_ROWS[@]}")
+mcdb_smoke_check
+
+restore_captured_registrations() {
+  local registration name dl returns
+
+  for registration in "${CAPTURED_REGISTRATIONS[@]}"; do
+    IFS=$'\t' read -r name dl <<< "$registration"
+    case "$name" in
+      multi_compress_db_version|multi_compress_db_decompress) returns='STRING' ;;
+      multi_compress_db_is_valid) returns='INTEGER' ;;
+      *) mcdb_die "captured unexpected UDF registration: $name" ;;
+    esac
+    mcdb_query "CREATE FUNCTION ${name} RETURNS ${returns} SONAME '${dl}';"
+  done
+}
+
+PLUGIN_DIR="$(mcdb_plugin_dir)"
+LIBRARY="$PLUGIN_DIR/$MCDB_UDF_LIBRARY"
+[ -f "$LIBRARY" ] || mcdb_die "installed library is missing: $LIBRARY"
+BACKUP="$PLUGIN_DIR/.${MCDB_UDF_LIBRARY}.backup.$$.$RANDOM"
+TEMP_LIBRARY="$PLUGIN_DIR/.${MCDB_UDF_LIBRARY}.new.$$.$RANDOM.tmp"
+RESTORED=0
+cleanup() {
+  rm -f "$TEMP_LIBRARY"
+  if [ "$RESTORED" -eq 1 ]; then
+    rm -f "$BACKUP"
+  fi
+}
+trap cleanup EXIT
+
+make -C "$ROOT/mysql_udf" clean udf MYSQL_UDF_ABI=mysql57
+install -m 0755 "$ROOT/mysql_udf/build/$MCDB_UDF_LIBRARY" "$TEMP_LIBRARY"
+
+if ! mcdb_drop_owned_udfs; then
+  mcdb_die 'could not drop existing MultiCompress UDFs; library was not replaced'
+fi
+if ! cp -p "$LIBRARY" "$BACKUP"; then
+  restore_captured_registrations || true
+  mcdb_die 'could not back up the installed library; original registrations were restored when possible'
+fi
+
+mv -f "$TEMP_LIBRARY" "$LIBRARY"
+if mcdb_register_expected_udfs && mcdb_smoke_check; then
+  [ "${#CAPTURED_REGISTRATIONS[@]}" -eq 3 ] || mcdb_die 'captured registration state is incomplete'
+  rm -f "$BACKUP"
+  RESTORED=1
+  echo 'MultiCompress MySQL UDFs upgraded successfully.'
+  exit 0
+fi
+
+ROLLBACK_OK=1
+mcdb_drop_owned_udfs || ROLLBACK_OK=0
+if [ -f "$BACKUP" ]; then
+  mv -f "$BACKUP" "$LIBRARY" || ROLLBACK_OK=0
+else
+  ROLLBACK_OK=0
+fi
+if ! restore_captured_registrations || ! mcdb_smoke_check; then
+  ROLLBACK_OK=0
+fi
+if [ "$ROLLBACK_OK" -eq 1 ]; then
+  RESTORED=1
+  echo 'multi_compress mysql upgrade: failed; previous library and registrations were restored' >&2
+else
+  echo 'multi_compress mysql upgrade: failed and rollback did not complete; inspect mysql.func and plugin_dir immediately' >&2
+fi
+exit 1

data/db_deployment/mysql/bin/verify

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+if command -v sha256sum >/dev/null 2>&1; then
+  sha256sum -c SHA256SUMS
+elif command -v shasum >/dev/null 2>&1; then
+  shasum -a 256 -c SHA256SUMS
+else
+  echo "multi_compress mysql verify: sha256sum or shasum is required" >&2
+  exit 2
+fi

data/db_deployment/postgres/Makefile

@@ -0,0 +1,45 @@
+SHELL := /bin/bash
+
+# PG_CONFIG is the normal public override. It is used for both compilation and
+# installation paths. BUILD_PG_CONFIG/RUNTIME_PG_CONFIG exist for uncommon
+# containerised deployments where headers are installed separately from the
+# running server; ordinary DBAs never need to set them.
+PG_CONFIG ?=
+BUILD_PG_CONFIG ?= $(PG_CONFIG)
+RUNTIME_PG_CONFIG ?= $(PG_CONFIG)
+DB ?=
+SCHEMA ?= multi_compress
+MIGRATION_ROLE ?=
+READ_ROLE ?=
+CONFIRM ?=
+
+.PHONY: help verify doctor install enable uninstall
+
+help:
+	@printf '%s\n' \
+	  'MultiCompress PostgreSQL deployment bundle' \
+	  '' \
+	  '  make verify' \
+	  '  make doctor [PG_CONFIG=/path/to/pg_config]' \
+	  '  sudo make install [PG_CONFIG=/path/to/pg_config]' \
+	  '  sudo -u postgres make enable DB=app_production MIGRATION_ROLE=app_migrations READ_ROLE=dbeaver_readonly [SCHEMA=multi_compress]' \
+	  '  sudo make uninstall CONFIRM=REMOVE_MULTI_COMPRESS [PG_CONFIG=/path/to/pg_config]'
+
+verify:
+	./bin/verify
+
+doctor:
+	./bin/doctor $(if $(BUILD_PG_CONFIG),--pg-config "$(BUILD_PG_CONFIG)")
+
+install: verify
+	./bin/install $(if $(BUILD_PG_CONFIG),--build-pg-config "$(BUILD_PG_CONFIG)") $(if $(RUNTIME_PG_CONFIG),--runtime-pg-config "$(RUNTIME_PG_CONFIG)")
+
+enable:
+	@test -n "$(DB)" || { echo 'DB is required: make enable DB=app_production' >&2; exit 2; }
+	@test -n "$(MIGRATION_ROLE)" || { echo 'MIGRATION_ROLE is required: make enable ... MIGRATION_ROLE=app_migrations' >&2; exit 2; }
+	@test -n "$(READ_ROLE)" || { echo 'READ_ROLE is required: make enable ... READ_ROLE=dbeaver_readonly' >&2; exit 2; }
+	./bin/enable --database "$(DB)" --schema "$(SCHEMA)" --migration-role "$(MIGRATION_ROLE)" --read-role "$(READ_ROLE)"
+
+uninstall:
+	@test "$(CONFIRM)" = "REMOVE_MULTI_COMPRESS" || { echo 'uninstall requires CONFIRM=REMOVE_MULTI_COMPRESS' >&2; exit 2; }
+	./bin/uninstall $(if $(RUNTIME_PG_CONFIG),--pg-config "$(RUNTIME_PG_CONFIG)")

data/db_deployment/postgres/README.md

@@ -0,0 +1,60 @@
+# MultiCompress PostgreSQL deployment bundle
+
+This bundle is generated by the exact `multi_compress` gem version used by the
+application. It builds the native reader on the PostgreSQL host, avoiding any
+assumption about glibc, CPU architecture or PostgreSQL build flags.
+
+Install PostgreSQL server development files for the running major version and a
+C toolchain first. On a package-managed host this is normally the matching
+`postgresql-server-dev-<major>` package; `make doctor` checks that prerequisite
+before changing the server.
+
+```bash
+make verify
+make doctor
+sudo make install
+sudo -u postgres make enable DB=app_production \
+  MIGRATION_ROLE=app_migrations READ_ROLE=dbeaver_readonly
+```
+
+Pass a non-default server installation explicitly:
+
+```bash
+sudo make install PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config
+```
+
+`install` only places the extension files on the host. `enable` rejects
+non-UTF8 databases, refuses an existing extension in another schema, and grants
+`USAGE` to the migration role plus `EXECUTE` to the migration and read roles.
+Grant the read role `SELECT` on each generated view in the application migration.
+Run the native install on every database host that must query MCDB1 columns,
+including reporting databases, failover targets and restored environments.
+
+The application stores `MultiCompress::Database.compress(text)` in a `bytea`
+column. Generate the DBeaver/read-side view in the application repository. Use
+`--extension-schema NAME` below only if `make enable` used a non-default schema:
+
+```bash
+bundle exec multi_compress db view postgres \
+  --table app.events \
+  --column payload_compressed \
+  --view admin.events_readable \
+  --columns id,created_at,status \
+  --as payload \
+  --output db/views/events_readable.sql
+```
+
+Commit that SQL (or put it in a Rails migration). DBeaver users then query:
+
+```sql
+SELECT id, created_at, status, payload
+FROM admin.events_readable
+WHERE id = 123;
+```
+
+The view decompresses selected rows. Always filter with indexed, uncompressed
+columns first; do not use it for unbounded `LIKE '%text%'` searches.
+
+`make verify` catches accidental corruption after extraction; it does not
+authenticate an archive. Use an out-of-band SHA-256, a minisign/GPG signature,
+or signed release provenance for a real trust chain.

data/db_deployment/postgres/bin/doctor

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PG_CONFIG="${PG_CONFIG:-pg_config}"
+
+usage() {
+  cat <<'TEXT'
+Usage: ./bin/doctor [--pg-config PATH]
+
+Checks whether this PostgreSQL host can build the MultiCompress extension.
+TEXT
+}
+
+die() {
+  echo "multi_compress postgres doctor: $*" >&2
+  exit 2
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --pg-config)
+      [ "$#" -ge 2 ] || die "--pg-config requires a path"
+      PG_CONFIG="$2"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      die "unknown option: $1"
+      ;;
+  esac
+done
+
+if [[ "$PG_CONFIG" == */* ]]; then
+  [ -x "$PG_CONFIG" ] || die "pg_config is not executable: $PG_CONFIG"
+else
+  PG_CONFIG="$(command -v "$PG_CONFIG" || true)"
+  [ -n "$PG_CONFIG" ] || die "pg_config was not found; install PostgreSQL server development files or pass --pg-config PATH"
+fi
+
+command -v make >/dev/null 2>&1 || die "make is required"
+command -v cc >/dev/null 2>&1 || die "a C compiler is required (cc/gcc/clang)"
+command -v ar >/dev/null 2>&1 || die "ar is required"
+
+PGXS="$($PG_CONFIG --pgxs 2>/dev/null || true)"
+HEADERS="$($PG_CONFIG --includedir-server 2>/dev/null || true)"
+[ -f "$PGXS" ] || die "PGXS is missing; install postgresql-server-dev for $($PG_CONFIG --version)"
+[ -f "$HEADERS/postgres.h" ] || die "PostgreSQL server headers are missing; install postgresql-server-dev for $($PG_CONFIG --version)"
+
+printf '%s\n' \
+  "PostgreSQL: $($PG_CONFIG --version)" \
+  "pg_config: $PG_CONFIG" \
+  "PGXS: $PGXS" \
+  "headers: $HEADERS" \
+  "library directory: $($PG_CONFIG --pkglibdir)" \
+  "extension directory: $($PG_CONFIG --sharedir)/extension" \
+  "bundle: $ROOT" \
+  "doctor: OK"