multi_compress 0.3.5 → 0.6.0

data/db_deployment/mysql/bin/common

@@ -0,0 +1,212 @@
+#!/usr/bin/env bash
+
+MCDB_UDF_LIBRARY='multi_compress_mysql.so'
+MCDB_V1_UDF_NAMES=(
+  multi_compress_db_version
+  multi_compress_db_is_valid
+  multi_compress_db_decompress
+)
+MCDB_EMPTY_ENVELOPE_HEX='4d43444201010000000000000000000000000028b52ffd2000010000'
+MCDB_UDF_NAMES=(
+  multi_compress_db_version
+  multi_compress_db_is_valid
+  multi_compress_db_decompress
+  multi_compress_db_original_size
+  multi_compress_db_dictionary_ref
+  multi_compress_db_dictionary_zstd_id
+  multi_compress_db_dictionary_sha256
+  multi_compress_db_is_valid_dict
+  multi_compress_db_decompress_dict
+)
+
+mcdb_die() {
+  echo "multi_compress mysql: $*" >&2
+  exit 2
+}
+
+mcdb_resolve_mysql() {
+  if [[ "$MYSQL" == */* ]]; then
+    [ -x "$MYSQL" ] || mcdb_die "mysql client is not executable: $MYSQL"
+  else
+    MYSQL="$(command -v "$MYSQL" || true)"
+    [ -n "$MYSQL" ] || mcdb_die "mysql client was not found"
+  fi
+}
+
+mcdb_mysql_args() {
+  MYSQL_ARGS=(--batch --skip-column-names --raw --max_allowed_packet=32M --protocol=SOCKET)
+  if [ -n "$DEFAULTS_FILE" ]; then
+    [ -f "$DEFAULTS_FILE" ] || mcdb_die "defaults file does not exist: $DEFAULTS_FILE"
+    MYSQL_ARGS=("--defaults-extra-file=$DEFAULTS_FILE" "${MYSQL_ARGS[@]}")
+  fi
+  if [ -n "${MYSQL_SOCKET:-}" ]; then
+    MYSQL_ARGS+=("--socket=$MYSQL_SOCKET")
+  fi
+}
+
+mcdb_query() {
+  "$MYSQL" "${MYSQL_ARGS[@]}" -e "$1"
+}
+
+mcdb_server_version() {
+  mcdb_query 'SELECT VERSION();' | tr -d '\r\n'
+}
+
+mcdb_require_mysql57() {
+  local version
+  version="$(mcdb_server_version)"
+  case "$version" in
+    5.7.*) ;;
+    *) mcdb_die "this bundle targets MySQL 5.7; server reports $version" ;;
+  esac
+}
+
+mcdb_plugin_dir() {
+  mcdb_query 'SELECT @@plugin_dir;' | tr -d '\r\n'
+}
+
+mcdb_server_socket() {
+  mcdb_query 'SELECT @@socket;' | tr -d '\r\n'
+}
+
+mcdb_server_hostname() {
+  mcdb_query 'SELECT @@hostname;' | tr -d '\r\n'
+}
+
+mcdb_server_max_allowed_packet() {
+  mcdb_query 'SELECT @@GLOBAL.max_allowed_packet;' | tr -d '\r\n'
+}
+
+mcdb_require_expected_socket() {
+  local actual_socket
+  actual_socket="$(mcdb_server_socket)"
+  [ -n "$actual_socket" ] || mcdb_die 'MySQL returned an empty @@socket'
+  if [ -n "${MYSQL_SOCKET:-}" ] && [ "$MYSQL_SOCKET" != "$actual_socket" ]; then
+    mcdb_die "connected server socket $actual_socket does not match MYSQL_SOCKET $MYSQL_SOCKET"
+  fi
+}
+
+mcdb_read_udf_state() {
+  local rows name dl
+
+  MCDB_EXPECTED_OWNED=0
+  MCDB_FOREIGN_EXPECTED=0
+  MCDB_UNEXPECTED_LIBRARY=0
+  MCDB_REGISTERED_ROWS=()
+
+  local names_sql=""
+  local expected=()
+  for name in "${MCDB_UDF_NAMES[@]}"; do
+    expected+=("'${name}'")
+  done
+  names_sql="$(IFS=,; printf '%s' "${expected[*]}")"
+
+  rows="$(mcdb_query "SELECT name, dl FROM mysql.func WHERE dl = '${MCDB_UDF_LIBRARY}' OR name IN (${names_sql}) ORDER BY name;")"
+  while IFS=$'\t' read -r name dl; do
+    [ -n "$name" ] || continue
+    MCDB_REGISTERED_ROWS+=("$name"$'\t'"$dl")
+    local expected_name=0
+    local candidate
+    for candidate in "${MCDB_UDF_NAMES[@]}"; do
+      if [ "$candidate" = "$name" ]; then expected_name=1; break; fi
+    done
+    if [ "$expected_name" -eq 1 ]; then
+      if [ "$dl" = "$MCDB_UDF_LIBRARY" ]; then
+        MCDB_EXPECTED_OWNED=$((MCDB_EXPECTED_OWNED + 1))
+      else
+        MCDB_FOREIGN_EXPECTED=$((MCDB_FOREIGN_EXPECTED + 1))
+      fi
+    elif [ "$dl" = "$MCDB_UDF_LIBRARY" ]; then
+      MCDB_UNEXPECTED_LIBRARY=$((MCDB_UNEXPECTED_LIBRARY + 1))
+    fi
+  done <<< "$rows"
+}
+
+mcdb_state_is_clean_absent() {
+  [ "$MCDB_EXPECTED_OWNED" -eq 0 ] && [ "$MCDB_FOREIGN_EXPECTED" -eq 0 ] && [ "$MCDB_UNEXPECTED_LIBRARY" -eq 0 ]
+}
+
+mcdb_state_is_clean_enabled() {
+  [ "$MCDB_EXPECTED_OWNED" -eq "${#MCDB_UDF_NAMES[@]}" ] && [ "$MCDB_FOREIGN_EXPECTED" -eq 0 ] && [ "$MCDB_UNEXPECTED_LIBRARY" -eq 0 ]
+}
+
+mcdb_has_owned_registration() {
+  local target="$1" registration name dl
+  for registration in "${MCDB_REGISTERED_ROWS[@]}"; do
+    IFS=$'\t' read -r name dl <<< "$registration"
+    [ "$name" = "$target" ] && [ "$dl" = "$MCDB_UDF_LIBRARY" ] && return 0
+  done
+  return 1
+}
+
+# A 0.5.x host has only the three MCDB1 UDF registrations. It is a known,
+# upgradeable state, not a partial installation. The 0.6 upgrade replaces the
+# library using MySQL's required DROP -> replace -> CREATE order and registers
+# the full MCDB1/MCDB2 surface.
+mcdb_state_is_clean_v1_enabled() {
+  local name
+  [ "$MCDB_EXPECTED_OWNED" -eq "${#MCDB_V1_UDF_NAMES[@]}" ] || return 1
+  [ "$MCDB_FOREIGN_EXPECTED" -eq 0 ] || return 1
+  [ "$MCDB_UNEXPECTED_LIBRARY" -eq 0 ] || return 1
+  for name in "${MCDB_V1_UDF_NAMES[@]}"; do
+    mcdb_has_owned_registration "$name" || return 1
+  done
+  return 0
+}
+
+mcdb_require_clean_owned_state() {
+  if [ "$MCDB_FOREIGN_EXPECTED" -ne 0 ]; then
+    mcdb_die 'one or more expected UDF names are registered to a foreign SONAME; refusing to modify them'
+  fi
+  if [ "$MCDB_UNEXPECTED_LIBRARY" -ne 0 ]; then
+    mcdb_die "unexpected registrations reference ${MCDB_UDF_LIBRARY}; refusing to modify the shared library"
+  fi
+}
+
+mcdb_v1_smoke_check() {
+  local version decoded
+  version="$(mcdb_query 'SELECT multi_compress_db_version();' | tr -d '\r\n')"
+  case "$version" in
+    *'MCDB1'*) ;;
+    *) mcdb_die "MCDB1 version() smoke check failed: $version" ;;
+  esac
+  decoded="$(mcdb_query "SELECT multi_compress_db_decompress(UNHEX('${MCDB_EMPTY_ENVELOPE_HEX}')) = '';" | tr -d '\r\n')"
+  [ "$decoded" = '1' ] || mcdb_die 'decode smoke check failed'
+}
+
+mcdb_smoke_check() {
+  local version
+  mcdb_v1_smoke_check
+  version="$(mcdb_query 'SELECT multi_compress_db_version();' | tr -d '\r\n')"
+  case "$version" in
+    *'MCDB1'*'MCDB2'*) ;;
+    *) mcdb_die "MCDB1/MCDB2 version() smoke check failed: $version" ;;
+  esac
+}
+
+mcdb_drop_owned_udfs() {
+  mcdb_read_udf_state
+  mcdb_require_clean_owned_state
+  for name in "${MCDB_UDF_NAMES[@]}"; do
+    if mcdb_query "SELECT COUNT(*) FROM mysql.func WHERE name = '${name}' AND dl = '${MCDB_UDF_LIBRARY}';" | tr -d '\r\n' | grep -qx '1'; then
+      mcdb_query "DROP FUNCTION ${name};"
+    fi
+  done
+}
+
+mcdb_register_expected_udfs() {
+  "$MYSQL" "${MYSQL_ARGS[@]}" < "$ROOT/mysql_udf/sql/install.sql"
+}
+
+mcdb_library_checksum() {
+  local library="$1"
+  if [ ! -f "$library" ]; then
+    printf '%s\n' 'missing'
+  elif command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$library" | awk '{print $1}'
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$library" | awk '{print $1}'
+  else
+    printf '%s\n' 'unavailable (sha256sum or shasum is required)'
+  fi
+}

data/db_deployment/mysql/bin/disable

@@ -0,0 +1,40 @@
+#!/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/disable [--mysql PATH] [--defaults-extra-file PATH]
+
+Removes only MultiCompress-owned UDF registrations and leaves the native library in place.
+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 disable: 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_drop_owned_udfs
+
+echo 'MultiCompress MySQL UDFs are disabled.'

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,61 @@
+#!/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 MultiCompress MCDB1/MCDB2 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
+
+if mcdb_state_is_clean_v1_enabled; then
+  mcdb_die 'MCDB1-only UDF registrations were found; run make upgrade to install the MCDB2 reader surface'
+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,67 @@
+#!/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_v1_enabled; then
+  echo 'state: MCDB1-only; run make upgrade before writing MCDB2 values'
+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,127 @@
+#!/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
+LEGACY_MCDB1_ONLY=0
+if mcdb_state_is_clean_v1_enabled; then
+  LEGACY_MCDB1_ONLY=1
+elif ! mcdb_state_is_clean_enabled; then
+  mcdb_die 'upgrade requires either a complete MCDB1-only or MCDB1/MCDB2 owned UDF state'
+fi
+CAPTURED_REGISTRATIONS=("${MCDB_REGISTERED_ROWS[@]}")
+if [ "$LEGACY_MCDB1_ONLY" -eq 1 ]; then
+  # A genuine 0.5.x library does not advertise MCDB2 yet. Verify only its
+  # MCDB1 surface before the required DROP -> replace -> CREATE transition.
+  mcdb_v1_smoke_check
+else
+  mcdb_smoke_check
+fi
+
+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|multi_compress_db_dictionary_sha256|multi_compress_db_decompress_dict) returns='STRING' ;;
+      multi_compress_db_is_valid|multi_compress_db_original_size|multi_compress_db_dictionary_ref|multi_compress_db_dictionary_zstd_id|multi_compress_db_is_valid_dict) 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
+  mcdb_read_udf_state
+  mcdb_state_is_clean_enabled || mcdb_die 'upgrade did not register the complete MCDB1/MCDB2 UDF surface'
+  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