multi_compress 0.3.5 → 0.5.0

data/postgres_extension/Makefile

@@ -0,0 +1,74 @@
+EXTENSION   = multi_compress
+MODULE_big  = multi_compress_pg
+OBJS        = src/multi_compress_pg.o src/mcdb_format.o
+DATA        = sql/multi_compress--0.5.0.sql
+
+PG_CONFIG   ?= pg_config
+ZSTD_DIR    ?= ../ext/multi_compress/vendor/zstd/lib
+CORE_DIR    ?= ../db_core
+BUILD       ?= build
+CC          ?= cc
+AR          ?= ar
+
+WARNFLAGS   ?= -Wall -Wextra -Werror
+PG_CPPFLAGS += -I$(CORE_DIR)/include -I$(ZSTD_DIR)
+PG_CFLAGS   += -O2 -fPIC -std=c99 $(WARNFLAGS)
+EXPORT_MAP  := $(CURDIR)/multi_compress_pg.exports
+SHLIB_LINK  += -Wl,--version-script=$(EXPORT_MAP) $(ZSTD_LIB)
+EXTRA_CLEAN += $(BUILD)
+
+ZSTD_CFLAGS  ?= -O2 -fPIC -std=c99 -I$(ZSTD_DIR) -I$(ZSTD_DIR)/common
+ZSTD_OBJ_DIR := $(BUILD)/zstd
+ZSTD_C_SRCS  := $(wildcard $(ZSTD_DIR)/common/*.c) $(wildcard $(ZSTD_DIR)/decompress/*.c)
+ZSTD_C_OBJS  := $(patsubst $(ZSTD_DIR)/%.c,$(ZSTD_OBJ_DIR)/%.o,$(ZSTD_C_SRCS))
+
+ARCH := $(shell uname -m)
+ifneq (,$(filter x86_64 amd64,$(ARCH)))
+ZSTD_ASM_SRC := $(ZSTD_DIR)/decompress/huf_decompress_amd64.S
+ifneq (,$(wildcard $(ZSTD_ASM_SRC)))
+ZSTD_ASM_OBJ := $(ZSTD_OBJ_DIR)/decompress/huf_decompress_amd64.o
+endif
+endif
+
+ZSTD_OBJS := $(ZSTD_C_OBJS) $(ZSTD_ASM_OBJ)
+ZSTD_LIB  := $(BUILD)/libzstd_dec.a
+
+PGXS := $(shell $(PG_CONFIG) --pgxs)
+include $(PGXS)
+
+.PHONY: all test parity e2e fixtures
+
+all: $(ZSTD_LIB)
+
+$(MODULE_big)$(DLSUFFIX): $(ZSTD_LIB)
+
+$(BUILD):
+	mkdir -p $@
+
+$(ZSTD_OBJ_DIR)/%.o: $(ZSTD_DIR)/%.c
+	@mkdir -p $(dir $@)
+	$(CC) $(ZSTD_CFLAGS) -MMD -MP -c $< -o $@
+
+$(ZSTD_OBJ_DIR)/%.o: $(ZSTD_DIR)/%.S
+	@mkdir -p $(dir $@)
+	$(CC) -fPIC -I$(ZSTD_DIR) -c $< -o $@
+
+$(ZSTD_LIB): $(ZSTD_OBJS) | $(BUILD)
+	$(AR) rcs $@ $^
+
+# The source wrapper includes the common MCDB1 decoder; it is not a fork.
+src/mcdb_format.o: src/mcdb_format.c $(CORE_DIR)/src/mcdb_format.c $(CORE_DIR)/include/mcdb_format.h
+
+# Golden fixtures are committed. Regeneration is a development action only.
+fixtures:
+	RUBYLIB=../lib ruby ../test/fixtures/database_v1/generate.rb
+
+parity:
+	$(MAKE) -C ../mysql_udf test
+
+test: all parity
+
+e2e:
+	./test/run_e2e.sh
+
+-include $(ZSTD_C_OBJS:.o=.d)

data/postgres_extension/README.md

@@ -0,0 +1,112 @@
+# MultiCompress PostgreSQL extension (`MCDB1` reader)
+
+This PostgreSQL extension reads the same frozen `MCDB1` envelopes as the Ruby
+API and the MySQL UDF. Rails stores `MultiCompress::Database.compress(text)` in
+`bytea`; PostgreSQL exposes decoded UTF-8 through SQL and a view for DBeaver.
+
+It is a separate server-native artifact, not part of `gem install`. The shared
+format contract is [`docs/database-envelope-v1.md`](../docs/database-envelope-v1.md).
+
+## SQL API
+
+| Function | Returns | Purpose |
+|---|---:|---|
+| `multi_compress_db_version()` | `text` | reader build, MCDB1 and zstd version smoke test |
+| `multi_compress_db_is_valid(bytea)` | `boolean` | validates an MCDB1 blob without raising |
+| `multi_compress_db_decompress(bytea)` | `text` | returns UTF-8 text or raises on corruption |
+
+`multi_compress_db_decompress` requires a UTF-8 PostgreSQL database. MCDB1 does
+not permit NUL bytes, so decoded values are valid PostgreSQL `text` values.
+
+## Production deployment: generated DBA bundle
+
+Do **not** ask a DBA to clone this repository, find a release tag, manually copy
+`multi_compress_pg.so`, or guess PostgreSQL install paths. The application
+developer generates a source bundle from the exact installed gem version:
+
+```bash
+bundle exec multi_compress db package postgres --output tmp/multi-compress-postgres.tar.gz
+```
+
+The DBA receives that one archive and runs this on the PostgreSQL host:
+
+```bash
+tar -xzf multi-compress-postgres.tar.gz
+cd multi_compress-postgres-0.5.0
+make verify
+make doctor
+sudo make install
+sudo -u postgres make enable DB=app_production \
+  MIGRATION_ROLE=app_migrations READ_ROLE=dbeaver_readonly
+```
+
+`install` compiles the extension against the selected host `pg_config` and puts
+its library/control/SQL files in the directories reported by that exact server.
+Install the matching `postgresql-server-dev-<major>` package and a C toolchain
+beforehand; `make doctor` verifies both.
+For a non-default PostgreSQL install use:
+
+```bash
+sudo make install PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config
+```
+
+`enable` rejects non-UTF8 databases and an extension already installed in a
+different schema. It runs `CREATE EXTENSION` once per application database,
+revokes public access, grants the migration role `USAGE` on the extension schema,
+and grants both named roles `EXECUTE` on the decoder functions. The application
+migration must grant the read role `SELECT` on each generated view. Repeat the
+native install on every reporting, failover and restore target before enabling
+or querying MCDB1 there.
+
+## DBeaver: generated readable view
+
+Generate the view in the application repository and put the output in a Rails
+migration or versioned SQL. It is application schema, not a hand-typed DBA task:
+
+```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
+```
+
+DBeaver users only query `admin.events_readable`. Their role needs `USAGE` on
+`admin`, `SELECT` on this view, and `EXECUTE` on the decoder functions granted by
+`make enable`; it does not need `USAGE` on `multi_compress`. If `make enable`
+used a different extension schema, pass it to the generator with
+`--extension-schema that_schema`:
+
+```sql
+SELECT id, created_at, status, payload
+FROM admin.events_readable
+WHERE id = 123;
+```
+
+The view decompresses selected rows. Filter with indexed ordinary columns before
+reading it; do not scan decoded payloads with an unbounded `LIKE '%text%'`.
+
+## Migration and constraints
+
+Do not reinterpret an existing plaintext column as MCDB1. Add a new nullable
+`bytea` column, dual-write it from the application, backfill in batches, verify
+`multi_compress.multi_compress_db_is_valid(blob)`, switch reads, then keep the
+old column for a rollback window. MCDB1 v1 is zstd-only, accepts valid UTF-8
+text without NUL bytes, and has a 16 MiB decompressed limit. The target database
+must use UTF-8 encoding for the text-returning function.
+
+## Development source build
+
+The source target remains useful for contributors and CI:
+
+```bash
+cd postgres_extension
+make PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config
+make test PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config
+make e2e
+```
+
+`test/run_e2e.sh` builds against a pinned PostgreSQL Docker target and is the
+server-side acceptance gate. It is not part of the end-user installation flow.

data/postgres_extension/multi_compress.control

@@ -0,0 +1,4 @@
+comment = 'MCDB1 reader for MultiCompress database envelopes'
+default_version = '0.5.0'
+module_pathname = '$libdir/multi_compress_pg'
+relocatable = true

data/postgres_extension/multi_compress_pg.exports

@@ -0,0 +1,12 @@
+{
+  global:
+    Pg_magic_func;
+    pg_finfo_multi_compress_db_version;
+    pg_finfo_multi_compress_db_is_valid;
+    pg_finfo_multi_compress_db_decompress;
+    multi_compress_db_version;
+    multi_compress_db_is_valid;
+    multi_compress_db_decompress;
+  local:
+    *;
+};

data/postgres_extension/sql/examples.sql

@@ -0,0 +1,12 @@
+-- Install into a dedicated schema.
+CREATE SCHEMA IF NOT EXISTS multi_compress;
+CREATE EXTENSION multi_compress WITH SCHEMA multi_compress;
+
+SELECT multi_compress.multi_compress_db_version();
+SELECT multi_compress.multi_compress_db_is_valid(payload_compressed)
+FROM events
+WHERE id = 123;
+
+SELECT multi_compress.multi_compress_db_decompress(payload_compressed)
+FROM events
+WHERE id = 123;

data/postgres_extension/sql/multi_compress--0.5.0.sql

@@ -0,0 +1,24 @@
+\echo Use "CREATE EXTENSION multi_compress" to load this file. \quit
+
+CREATE FUNCTION multi_compress_db_version()
+RETURNS text
+AS 'MODULE_PATHNAME', 'multi_compress_db_version'
+LANGUAGE C
+IMMUTABLE
+PARALLEL SAFE;
+
+CREATE FUNCTION multi_compress_db_is_valid(blob bytea)
+RETURNS boolean
+AS 'MODULE_PATHNAME', 'multi_compress_db_is_valid'
+LANGUAGE C
+IMMUTABLE
+STRICT
+PARALLEL SAFE;
+
+CREATE FUNCTION multi_compress_db_decompress(blob bytea)
+RETURNS text
+AS 'MODULE_PATHNAME', 'multi_compress_db_decompress'
+LANGUAGE C
+IMMUTABLE
+STRICT
+PARALLEL SAFE;

data/postgres_extension/sql/uninstall.sql

@@ -0,0 +1,2 @@
+-- Drop dependent views first, then remove the extension from this database.
+DROP EXTENSION IF EXISTS multi_compress;

data/postgres_extension/sql/views.sql

@@ -0,0 +1,7 @@
+-- Replace multi_compress with the schema used in CREATE EXTENSION ... WITH SCHEMA.
+CREATE OR REPLACE VIEW events_readable AS
+SELECT
+  id,
+  multi_compress.multi_compress_db_decompress(payload_compressed) AS payload,
+  created_at
+FROM events;

data/postgres_extension/src/mcdb_format.c

@@ -0,0 +1,2 @@
+/* Shared MCDB1 decoder. The implementation lives once in db_core/. */
+#include "../../db_core/src/mcdb_format.c"

data/postgres_extension/src/multi_compress_pg.c

@@ -0,0 +1,96 @@
+#include "postgres.h"
+
+#include "fmgr.h"
+#include "mb/pg_wchar.h"
+#include "utils/builtins.h"
+#include "varatt.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include <zstd.h>
+
+#include "mcdb_format.h"
+
+PG_MODULE_MAGIC;
+
+PG_FUNCTION_INFO_V1(multi_compress_db_version);
+PG_FUNCTION_INFO_V1(multi_compress_db_is_valid);
+PG_FUNCTION_INFO_V1(multi_compress_db_decompress);
+
+static void mcdb_require_utf8_database(void) {
+    if (GetDatabaseEncoding() != PG_UTF8)
+        ereport(
+            ERROR,
+            (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
+             errmsg("multi_compress requires a UTF-8 PostgreSQL database"),
+             errdetail("MCDB1 stores UTF-8 text and multi_compress_db_decompress returns text.")));
+}
+
+static void mcdb_raise(mcdb_status status, const char *detail) {
+    if (status == MCDB_ERR_ALLOC)
+        ereport(ERROR, (errcode(ERRCODE_OUT_OF_MEMORY),
+                        errmsg("multi_compress: unable to allocate MCDB1 output")));
+
+    ereport(ERROR,
+            (errcode(ERRCODE_DATA_CORRUPTED), errmsg("multi_compress: invalid MCDB1 envelope"),
+             errdetail("%s", detail && detail[0] ? detail : mcdb_status_str(status))));
+}
+
+Datum multi_compress_db_version(PG_FUNCTION_ARGS) {
+    char version[64];
+
+    (void)fcinfo;
+
+    snprintf(version, sizeof(version), "multi_compress reader %s; MCDB1; zstd %s",
+             MCDB_READER_VERSION, ZSTD_versionString());
+    PG_RETURN_TEXT_P(cstring_to_text(version));
+}
+
+Datum multi_compress_db_is_valid(PG_FUNCTION_ARGS) {
+    bytea *input;
+    char err[MCDB_ERRLEN];
+    mcdb_status status;
+
+    if (PG_ARGISNULL(0))
+        PG_RETURN_NULL();
+
+    input = PG_GETARG_BYTEA_PP(0);
+    status = mcdb_decode((const unsigned char *)VARDATA_ANY(input),
+                         (size_t)VARSIZE_ANY_EXHDR(input), NULL, NULL, err);
+
+    PG_RETURN_BOOL(status == MCDB_OK);
+}
+
+Datum multi_compress_db_decompress(PG_FUNCTION_ARGS) {
+    bytea *input;
+    size_t output_len = 0;
+    char err[MCDB_ERRLEN];
+    mcdb_status status;
+    uint64_t original_size = 0;
+    text *result;
+
+    if (PG_ARGISNULL(0))
+        PG_RETURN_NULL();
+
+    mcdb_require_utf8_database();
+
+    input = PG_GETARG_BYTEA_PP(0);
+    status = mcdb_validate_header((const unsigned char *)VARDATA_ANY(input),
+                                  (size_t)VARSIZE_ANY_EXHDR(input), &original_size);
+    if (status != MCDB_OK)
+        mcdb_raise(status, mcdb_status_str(status));
+
+    result = (text *)palloc(VARHDRSZ + (size_t)original_size);
+
+    status = mcdb_decode_into((const unsigned char *)VARDATA_ANY(input),
+                              (size_t)VARSIZE_ANY_EXHDR(input), (unsigned char *)VARDATA(result),
+                              (size_t)original_size, &output_len, err);
+    if (status != MCDB_OK)
+        mcdb_raise(status, err);
+
+    SET_VARSIZE(result, VARHDRSZ + output_len);
+
+    PG_RETURN_TEXT_P(result);
+}

data/postgres_extension/test/run_e2e.sh

@@ -0,0 +1,323 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")/../.."
+
+# Platform-specific manifest for postgres:17.9-bookworm on linux/amd64.
+DEFAULT_POSTGRES_IMAGE="postgres:17.9-bookworm@sha256:3a69b9de644363f30110fbaa78b9e3298ce71bb1aa9124c0b0ceb0a2602c3283"
+IMAGE="${MCDB_POSTGRES_IMAGE:-$DEFAULT_POSTGRES_IMAGE}"
+PLATFORM="${MCDB_POSTGRES_PLATFORM:-linux/amd64}"
+CONTAINER="${MCDB_POSTGRES_CONTAINER:-mcdb-postgres-e2e}"
+WAIT_SECONDS="${MCDB_POSTGRES_WAIT_SECONDS:-90}"
+WORK_ROOT="${MCDB_POSTGRES_WORK_ROOT:-$(mktemp -d -t multi-compress-postgres.XXXXXX)}"
+REMOVE_WORK_ROOT=0
+ARCHIVE="$WORK_ROOT/multi_compress-postgres.tar.gz"
+GEM_UNPACK_DIR="$WORK_ROOT/unpacked"
+GEM_FILE="$WORK_ROOT/multi_compress.gem"
+PACKAGED_GEM_ROOT=""
+BUNDLE_PARENT="/opt"
+
+command -v docker >/dev/null 2>&1 || { echo "docker is required" >&2; exit 2; }
+
+cleanup() {
+  docker rm -f "$CONTAINER" >/dev/null 2>&1 || true
+  [ "$REMOVE_WORK_ROOT" -eq 1 ] && rm -rf "$WORK_ROOT"
+}
+trap cleanup EXIT
+
+if [ -z "${MCDB_POSTGRES_WORK_ROOT:-}" ]; then
+  REMOVE_WORK_ROOT=1
+fi
+
+ensure_ruby_extension() {
+  if ruby -Ilib -e 'require "multi_compress"; require "multi_compress/database"' >/dev/null 2>&1; then
+    return
+  fi
+
+  echo "building Ruby extension..."
+  if command -v bundle >/dev/null 2>&1; then
+    bundle exec rake compile
+  else
+    rake compile
+  fi
+  ruby -Ilib -e 'require "multi_compress"; require "multi_compress/database"' >/dev/null
+}
+
+require_fixture() {
+  local path="$1"
+  [ -f "$path" ] || { echo "missing committed fixture: $path" >&2; exit 2; }
+}
+
+fixture_hex() {
+  ruby -e 'print File.binread(ARGV.fetch(0)).unpack1("H*")' "$1"
+}
+
+prepare_packaged_gem() {
+  gem build multi_compress.gemspec --output "$GEM_FILE" >/dev/null
+  mkdir -p "$GEM_UNPACK_DIR"
+  gem unpack "$GEM_FILE" --target "$GEM_UNPACK_DIR" >/dev/null
+  shopt -s nullglob
+  roots=("$GEM_UNPACK_DIR"/*)
+  shopt -u nullglob
+  [ "${#roots[@]}" -eq 1 ] && [ -d "${roots[0]}" ] || { echo "could not unpack exactly one multi_compress gem root" >&2; exit 2; }
+  PACKAGED_GEM_ROOT="${roots[0]}"
+  [ -f "$PACKAGED_GEM_ROOT/multi_compress.gemspec" ] || { echo "packaged gem lacks gemspec" >&2; exit 2; }
+  [ -d "$PACKAGED_GEM_ROOT/lib" ] || { echo "packaged gem lacks lib" >&2; exit 2; }
+  [ -d "$PACKAGED_GEM_ROOT/exe" ] || { echo "packaged gem lacks exe" >&2; exit 2; }
+  [ -f "$PACKAGED_GEM_ROOT/lib/multi_compress/db_deployment.rb" ] || { echo "packaged gem lacks db deployment CLI" >&2; exit 2; }
+}
+
+db_cli() {
+  ruby -I "$PACKAGED_GEM_ROOT/lib" "$PACKAGED_GEM_ROOT/exe/multi_compress" db "$@"
+}
+
+compress_hex() {
+  MCDB_TEXT="$1" ruby -Ilib -r multi_compress -r multi_compress/database \
+    -e 'print MultiCompress::Database.compress(ENV.fetch("MCDB_TEXT")).unpack1("H*")'
+}
+
+bundle_name() {
+  ruby -I "$PACKAGED_GEM_ROOT/lib" -r multi_compress/version \
+    -e 'print "multi_compress-postgres-#{MultiCompress::VERSION}"'
+}
+
+build_deployment_bundle() {
+  db_cli package postgres --output "$ARCHIVE" --force
+  test -s "$ARCHIVE"
+}
+
+install_postgres_build_tools() {
+  local runtime_pg_config="$1"
+
+  docker exec -u 0 \
+    -e "MCDB_RUNTIME_PG_CONFIG=$runtime_pg_config" \
+    "$CONTAINER" sh -ceu '
+      runtime_pg_config="${MCDB_RUNTIME_PG_CONFIG:?missing runtime pg_config}"
+      pg_major="$("$runtime_pg_config" --version | awk '\''{print $2}'\'' | cut -d. -f1)"
+      case "$pg_major" in
+        ""|*[!0-9]*)
+          echo "could not determine PostgreSQL major version" >&2
+          exit 2
+          ;;
+      esac
+
+      if ! command -v make >/dev/null 2>&1 || ! command -v cc >/dev/null 2>&1; then
+        if ! command -v apt-get >/dev/null 2>&1; then
+          echo "PostgreSQL container has no supported package manager" >&2
+          exit 2
+        fi
+        apt-get update >&2
+        DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+          build-essential ca-certificates curl gnupg tar gzip >&2
+      fi
+
+      runtime_pgxs="$("$runtime_pg_config" --pgxs 2>/dev/null || true)"
+      runtime_headers="$("$runtime_pg_config" --includedir-server 2>/dev/null || true)"
+      if [ ! -f "$runtime_pgxs" ] || [ ! -f "$runtime_headers/postgres.h" ]; then
+        if ! command -v apt-get >/dev/null 2>&1; then
+          echo "PostgreSQL development headers are unavailable" >&2
+          exit 2
+        fi
+
+        install -d -m 0755 /etc/apt/keyrings
+        curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc | \
+          gpg --dearmor --yes -o /etc/apt/keyrings/postgresql.gpg
+        . /etc/os-release
+        echo "deb [signed-by=/etc/apt/keyrings/postgresql.gpg] https://apt.postgresql.org/pub/repos/apt ${VERSION_CODENAME}-pgdg main" \
+          >/etc/apt/sources.list.d/pgdg.list
+        apt-get update >&2
+        DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+          "postgresql-server-dev-${pg_major}" >&2
+      fi
+
+      build_pg_config=""
+      for candidate in "/usr/lib/postgresql/${pg_major}/bin/pg_config" "$(command -v pg_config || true)"; do
+        [ -n "$candidate" ] && [ -x "$candidate" ] || continue
+        pgxs="$("$candidate" --pgxs 2>/dev/null || true)"
+        headers="$("$candidate" --includedir-server 2>/dev/null || true)"
+        if [ -f "$pgxs" ] && [ -f "$headers/postgres.h" ]; then
+          build_pg_config="$candidate"
+          break
+        fi
+      done
+
+      [ -n "$build_pg_config" ] || {
+        echo "PostgreSQL PGXS/server headers are unavailable" >&2
+        exit 2
+      }
+      printf "%s\n" "$build_pg_config"
+    '
+}
+
+install_bundle_on_db_host() {
+  local bundle_name="$1"
+  local build_pg_config="$2"
+  local runtime_pg_config="$3"
+  local bundle_root="${BUNDLE_PARENT}/${bundle_name}"
+
+  tar -tzf "$ARCHIVE" | grep -Fx "${bundle_name}/THIRD_PARTY_NOTICES.md" >/dev/null
+  if tar -tzf "$ARCHIVE" | grep -E '/\.DS_Store$' >/dev/null; then
+    echo 'deployment bundle must not contain .DS_Store' >&2
+    exit 2
+  fi
+  docker cp "$ARCHIVE" "$CONTAINER:/tmp/${bundle_name}.tar.gz"
+  docker exec -u 0 \
+    -e "MCDB_BUNDLE_ROOT=$bundle_root" \
+    -e "MCDB_BUILD_PG_CONFIG=$build_pg_config" \
+    -e "MCDB_RUNTIME_PG_CONFIG=$runtime_pg_config" \
+    "$CONTAINER" sh -ceu '
+      rm -rf "$MCDB_BUNDLE_ROOT"
+      mkdir -p "$(dirname "$MCDB_BUNDLE_ROOT")"
+      tar -xzf "/tmp/$(basename "$MCDB_BUNDLE_ROOT").tar.gz" -C "$(dirname "$MCDB_BUNDLE_ROOT")"
+      cd "$MCDB_BUNDLE_ROOT"
+      make verify
+      make doctor PG_CONFIG="$MCDB_BUILD_PG_CONFIG"
+      make install BUILD_PG_CONFIG="$MCDB_BUILD_PG_CONFIG" RUNTIME_PG_CONFIG="$MCDB_RUNTIME_PG_CONFIG"
+    '
+
+}
+
+apply_readable_view() {
+  local path="$1"
+  db_cli view postgres \
+    --table app.events \
+    --column payload_compressed \
+    --view admin.events_readable \
+    --columns id \
+    --output "$path"
+  docker exec -i "$CONTAINER" psql -X -U app_migrations -d postgres -v ON_ERROR_STOP=1 < "$path"
+}
+
+ensure_ruby_extension
+prepare_packaged_gem
+build_deployment_bundle
+
+for name in corrupt_magic corrupt_payload corrupt_crc invalid_utf8 nul_text trailing_skippable trailing_frame; do
+  require_fixture "test/fixtures/database_v1/${name}.mcdb"
+done
+
+TEXT='Привет, DBeaver! Сәлем! 🌍'
+BIG=$(ruby -e 'print "a" * 300')
+VALID_HEX=$(compress_hex "$TEXT")
+BIG_HEX=$(compress_hex "$BIG")
+BUNDLE_NAME="$(bundle_name)"
+VIEW_SQL="$(mktemp -t multi-compress-postgres-view.XXXXXX.sql)"
+trap 'rm -f "$VIEW_SQL"; cleanup' EXIT
+
+docker rm -f "$CONTAINER" >/dev/null 2>&1 || true
+docker run --platform "$PLATFORM" -d --name "$CONTAINER" \
+  -e POSTGRES_HOST_AUTH_METHOD=trust "$IMAGE" >/dev/null
+
+echo "waiting for PostgreSQL in $IMAGE..."
+deadline=$(( $(date +%s) + WAIT_SECONDS ))
+until docker exec "$CONTAINER" pg_isready -U postgres -d postgres >/dev/null 2>&1; do
+  if [ "$(date +%s)" -ge "$deadline" ]; then
+    echo "PostgreSQL did not become ready within ${WAIT_SECONDS}s" >&2
+    docker logs "$CONTAINER" >&2 || true
+    exit 1
+  fi
+  sleep 2
+done
+
+q() { docker exec "$CONTAINER" psql -X -U postgres -d postgres -Atq -v ON_ERROR_STOP=1 -c "$1"; }
+qfail() {
+  if q "$1" >/dev/null 2>&1; then return 1; else return 0; fi
+}
+q_read() { docker exec "$CONTAINER" psql -X -U dbeaver_readonly -d postgres -Atq -v ON_ERROR_STOP=1 -c "$1"; }
+q_read_fail() {
+  if q_read "$1" >/dev/null 2>&1; then return 1; else return 0; fi
+}
+
+RUNTIME_PG_CONFIG=$(docker exec "$CONTAINER" sh -ceu 'command -v pg_config' | tr -d '\r\n')
+[ -n "$RUNTIME_PG_CONFIG" ] || { echo "PostgreSQL runtime does not provide pg_config" >&2; exit 2; }
+BUILD_PG_CONFIG=$(install_postgres_build_tools "$RUNTIME_PG_CONFIG")
+install_bundle_on_db_host "$BUNDLE_NAME" "$BUILD_PG_CONFIG" "$RUNTIME_PG_CONFIG"
+
+q "CREATE ROLE app_migrations LOGIN;
+   CREATE ROLE dbeaver_readonly LOGIN;
+   CREATE SCHEMA app;
+   CREATE SCHEMA admin;
+   CREATE TABLE app.events (id integer PRIMARY KEY, payload_compressed bytea NULL);
+   INSERT INTO app.events VALUES
+     (1, decode('$VALID_HEX', 'hex')),
+     (2, NULL),
+     (3, decode('$BIG_HEX', 'hex')),
+     (4, decode('$VALID_HEX', 'hex'));
+   GRANT USAGE ON SCHEMA app, admin TO app_migrations, dbeaver_readonly;
+   GRANT CREATE ON SCHEMA admin TO app_migrations;
+   GRANT SELECT ON app.events TO app_migrations;"
+docker exec -u postgres -e "MCDB_BUNDLE_ROOT=${BUNDLE_PARENT}/${BUNDLE_NAME}" "$CONTAINER" sh -ceu '
+  cd "$MCDB_BUNDLE_ROOT"
+  make enable DB=postgres MIGRATION_ROLE=app_migrations READ_ROLE=dbeaver_readonly
+'
+apply_readable_view "$VIEW_SQL"
+q 'GRANT SELECT ON admin.events_readable TO dbeaver_readonly;'
+
+q "CREATE DATABASE mcdb_latin1 WITH TEMPLATE template0 ENCODING 'LATIN1' LC_COLLATE 'C' LC_CTYPE 'C';"
+docker exec -u postgres -e "MCDB_BUNDLE_ROOT=${BUNDLE_PARENT}/${BUNDLE_NAME}" "$CONTAINER" sh -ceu '
+  cd "$MCDB_BUNDLE_ROOT"
+  if make enable DB=mcdb_latin1 MIGRATION_ROLE=app_migrations READ_ROLE=dbeaver_readonly >/tmp/mcdb-latin1.out 2>&1; then
+    echo "LATIN1 enable unexpectedly succeeded" >&2
+    exit 1
+  fi
+  grep -F "requires UTF8" /tmp/mcdb-latin1.out
+'
+q "CREATE DATABASE mcdb_other_schema WITH TEMPLATE template0 ENCODING 'UTF8';"
+docker exec "$CONTAINER" psql -X -U postgres -d mcdb_other_schema -v ON_ERROR_STOP=1 -c 'CREATE SCHEMA wrong_schema; CREATE EXTENSION multi_compress WITH SCHEMA wrong_schema;' >/dev/null
+docker exec -u postgres -e "MCDB_BUNDLE_ROOT=${BUNDLE_PARENT}/${BUNDLE_NAME}" "$CONTAINER" sh -ceu '
+  cd "$MCDB_BUNDLE_ROOT"
+  if make enable DB=mcdb_other_schema SCHEMA=multi_compress MIGRATION_ROLE=app_migrations READ_ROLE=dbeaver_readonly >/tmp/mcdb-schema.out 2>&1; then
+    echo "mismatched extension schema unexpectedly succeeded" >&2
+    exit 1
+  fi
+  grep -F "already installed in schema wrong_schema" /tmp/mcdb-schema.out
+'
+
+fails=0
+check() {
+  if [ "$2" = "$3" ]; then echo "  PASS  $1"; else echo "  FAIL  $1 (got [$2] want [$3])"; fails=$((fails + 1)); fi
+}
+check_err() {
+  if qfail "$2"; then echo "  PASS  $1 (rejected)"; else echo "  FAIL  $1 (should have errored)"; fails=$((fails + 1)); fi
+}
+
+check "UTF8 database" "$(q 'SHOW server_encoding;' | tr -d '\r\n')" "UTF8"
+check "deployment bundle version() smoke" "$(q 'SELECT strpos(multi_compress.multi_compress_db_version(), chr(77) || chr(67) || chr(68) || chr(66) || chr(49)) > 0;' | tr -d '\r\n')" "t"
+check "PostgreSQL reader uses vendored zstd" "$(q "SELECT strpos(multi_compress.multi_compress_db_version(), 'zstd 1.5.7') > 0;" | tr -d '\r\n')" "t"
+check "decode roundtrip" "$(q 'SELECT multi_compress.multi_compress_db_decompress(payload_compressed) FROM app.events WHERE id=1;' | tr -d '\r')" "$TEXT"
+check "NULL -> NULL" "$(q 'SELECT multi_compress.multi_compress_db_decompress(payload_compressed) IS NULL FROM app.events WHERE id=2;' | tr -d '\r\n')" "t"
+check "big (>255, >input)" "$(q 'SELECT octet_length(multi_compress.multi_compress_db_decompress(payload_compressed)) FROM app.events WHERE id=3;' | tr -d '\r\n')" "300"
+check "generated readable view" "$(q 'SELECT count(*) FROM admin.events_readable WHERE id IN (1, 4);' | tr -d '\r\n')" "2"
+check "read role reads generated Unicode view" "$(q_read 'SELECT payload FROM admin.events_readable WHERE id=1;' | tr -d '\r')" "$TEXT"
+if q_read_fail 'SELECT payload_compressed FROM app.events WHERE id=1;'; then
+  echo "  PASS  read role cannot read source table"
+else
+  echo "  FAIL  read role unexpectedly read source table"
+  fails=$((fails + 1))
+fi
+RUNTIME_MAJOR="$(docker exec "$CONTAINER" "$RUNTIME_PG_CONFIG" --version | awk '{print $2}' | cut -d. -f1 | tr -d '\r\n')"
+SERVER_MAJOR="$(q 'SHOW server_version;' | cut -d. -f1 | tr -d '\r\n')"
+check "connected server major matches PG_CONFIG" "$SERVER_MAJOR" "$RUNTIME_MAJOR"
+check "is_valid true" "$(q 'SELECT multi_compress.multi_compress_db_is_valid(payload_compressed) FROM app.events WHERE id=1;' | tr -d '\r\n')" "t"
+check "is_valid on NULL" "$(q 'SELECT multi_compress.multi_compress_db_is_valid(payload_compressed) IS NULL FROM app.events WHERE id=2;' | tr -d '\r\n')" "t"
+
+for name in corrupt_magic corrupt_payload corrupt_crc invalid_utf8 nul_text trailing_skippable trailing_frame; do
+  hex=$(fixture_hex "test/fixtures/database_v1/${name}.mcdb")
+  check_err "$name errors" "SELECT multi_compress.multi_compress_db_decompress(decode('$hex', 'hex'));"
+done
+check "is_valid false (crc)" "$(q "SELECT multi_compress.multi_compress_db_is_valid(decode('$(fixture_hex test/fixtures/database_v1/corrupt_crc.mcdb)', 'hex'));" | tr -d '\r\n')" "f"
+
+q 'DROP VIEW admin.events_readable; DROP EXTENSION multi_compress;'
+docker exec "$CONTAINER" psql -X -U postgres -d mcdb_other_schema -v ON_ERROR_STOP=1 -c 'DROP EXTENSION multi_compress;' >/dev/null
+docker exec -u 0 -e "MCDB_BUNDLE_ROOT=${BUNDLE_PARENT}/${BUNDLE_NAME}" -e "MCDB_RUNTIME_PG_CONFIG=$RUNTIME_PG_CONFIG" "$CONTAINER" sh -ceu '
+  cd "$MCDB_BUNDLE_ROOT"
+  if make uninstall RUNTIME_PG_CONFIG="$MCDB_RUNTIME_PG_CONFIG" >/dev/null 2>&1; then
+    echo "uninstall succeeded without CONFIRM" >&2
+    exit 1
+  fi
+  make uninstall CONFIRM=REMOVE_MULTI_COMPRESS RUNTIME_PG_CONFIG="$MCDB_RUNTIME_PG_CONFIG"
+'
+check_err "uninstall removes functions" "SELECT multi_compress.multi_compress_db_version();"
+check_err "uninstall removes extension files" "CREATE EXTENSION multi_compress;"
+
+if [ "$fails" -ne 0 ]; then echo "E2E FAILED ($fails)"; exit 1; fi
+echo "E2E OK"