multi_compress 0.3.5 → 0.6.0

data/docs/database-envelope-v2.md

@@ -0,0 +1,147 @@
+# MCDB2 database envelope (dictionary-backed, version 2)
+
+MCDB2 is an opt-in, dictionary-backed companion to [MCDB1](database-envelope-v1.md).
+It exists for a **single homogeneous database column** whose values share a stable
+text/JSON shape. Every MCDB2 value requires the exact immutable dictionary version
+recorded with it. MCDB1 remains the default for dictionary-free, heterogeneous, or
+large values.
+
+MCDB2 is compression, not encryption. Its CRC-32 detects accidental corruption; it
+does not authenticate data.
+
+## Wire format
+
+All integer fields are little-endian.
+
+| Offset | Size | Field | Required value |
+|---:|---:|---|---|
+| 0 | 4 | magic | ASCII `MCDB` |
+| 4 | 1 | format version | `0x02` |
+| 5 | 1 | codec | `0x01` (zstd) |
+| 6 | 1 | reserved flags | `0x00` |
+| 7 | 8 | original UTF-8 byte size | `0..16 MiB` |
+| 15 | 4 | CRC-32 | IEEE/zlib CRC of plaintext |
+| 19 | 8 | `dictionary_ref` | application registry id, `1..INT64_MAX` |
+| 27 | ... | zstd frame | exactly one frame with a non-zero zstd DictID |
+
+The maximum stored envelope is 16,842,779 bytes (`27 + ZSTD_compressBound(16 MiB)`).
+
+`dictionary_ref` is **not** the zstd DictID. It is a signed-bigint-compatible,
+application-level immutable primary key. The zstd frame contains the zstd DictID;
+readers require that it equals `ZSTD_getDictID_fromDict(dictionary_bytes)`.
+
+## Writer requirements
+
+A writer MUST:
+
+1. accept only valid UTF-8 text without NUL bytes and at most 16 MiB;
+2. use a conformant zstd dictionary no larger than 256 KiB with non-zero DictID;
+3. use a positive registry id at most `INT64_MAX`;
+4. emit a zstd frame through a prepared CDict so its DictID and content size are set;
+5. emit the 27-byte MCDB2 header followed by exactly that frame.
+
+Ruby API:
+
+```ruby
+samples = historical_payloads
+
+dictionary = MultiCompress::Database::Dictionary.train(
+  samples,
+  id: 42,
+  size: 32 * 1024
+)
+
+blob = MultiCompress::Database.compress(payload_json, dictionary: dictionary)
+```
+
+## Reader requirements
+
+The supported SQL ABI has four arguments:
+
+```sql
+multi_compress_db_decompress_dict(
+  blob,
+  dictionary_id,
+  dictionary_sha256,
+  dictionary_bytes
+)
+```
+
+The reader rejects any value unless all checks hold:
+
+1. the MCDB2 header is valid and `header.dictionary_ref == dictionary_id`;
+2. `dictionary_sha256` is 32 bytes and equals SHA-256 of `dictionary_bytes`;
+3. dictionary bytes are a conformant zstd dictionary with a non-zero DictID;
+4. the frame has exactly one zstd frame and its DictID equals the supplied dictionary's zstd DictID;
+5. the frame content size equals the header size; decompression, CRC-32 and UTF-8/NUL checks pass.
+
+`multi_compress_db_is_valid_dict(...)` returns false/0 rather than raising for an
+invalid non-NULL input. PostgreSQL `decompress_dict` raises a SQL error; MySQL 5.7
+returns SQL `NULL`, matching the MCDB1 UDF policy.
+
+## Dictionary registry
+
+Dictionary bytes are **application data**, not part of the DBA reader bundle.
+Store them in an append-only registry table in the application database. A rotation
+creates a new version row and changes only a movable `dictionary_heads` pointer;
+old rows and old payloads continue to reference their original version.
+
+Generate starter DDL:
+
+```bash
+multi_compress db registry postgres \
+  --schema app --owner mcdb_dictionary_owner \
+  --migration-role app_migrations \
+  --payload-table events --payload-column payload_compressed \
+  --payload-dictionary-id-column payload_dictionary_id \
+  > db/mcdb_dictionary_registry.sql
+
+multi_compress db registry mysql --database app \
+  --payload-table events --payload-column payload_compressed \
+  --payload-dictionary-id-column payload_dictionary_id \
+  > db/mcdb_dictionary_registry.sql
+```
+
+The registry DDL validates id/hash/zstd-ID/size at insert time and rejects updates
+and deletes. When the three `--payload-*` options are supplied, it also creates the
+payload FK and a trigger requiring `header.dictionary_ref == payload_dictionary_id`.
+For PostgreSQL it grants `USAGE` on the application schema to the dedicated NOLOGIN
+registry owner: internal FK checks run with relation-owner privileges and require
+that schema privilege. Backups, replication and restores therefore carry dictionaries
+with the compressed rows that require them.
+
+## Readable views
+
+Generate an MCDB2 view with an INNER JOIN. MySQL 5.7 output uses a source-first
+`STRAIGHT_JOIN` internally so an indexed source predicate does not begin from the
+registry. A MySQL 5.7 `EXPLAIN` may still report `Using temporary; Using filesort`
+for an outer `ORDER BY` over the joined projection; this is sorting, not view
+materialization. The view must expose no raw compressed column or dictionary bytes
+to DBeaver users:
+
+```bash
+multi_compress db view postgres \
+  --table app.events --column payload_compressed \
+  --dictionary-table app.mcdb_dictionary_versions \
+  --dictionary-id-column payload_dictionary_id \
+  --view admin.events_readable --columns id,created_at,status --as payload
+```
+
+For MySQL 5.7 the generator emits `ALGORITHM=MERGE SQL SECURITY DEFINER`. Do not
+add `DISTINCT`, aggregates, `GROUP BY`, `UNION`, subqueries, or an inner `LIMIT` to
+the generated view; they can force materialization and make decoding happen before
+an outer filter/limit.
+
+Filter and order only by ordinary indexed columns. Keep decoding in the SELECT list.
+Use `EXPLAIN` for production query shapes such as `WHERE id >= ... ORDER BY id LIMIT 100`.
+
+## Rollout and rollback
+
+1. Install 0.6 readers on every DB reader host before writing an MCDB2 row.
+2. PostgreSQL: run `ALTER EXTENSION multi_compress UPDATE`; MySQL: use the bundle's
+   controlled UDF upgrade flow, which preserves both MCDB1 and MCDB2 functions.
+3. Create registry, registry validation/freeze triggers, source FK, and readable view.
+4. Train/register a dictionary and enable the MCDB2 writer for its new column.
+
+After the first MCDB2 write, a reader at 0.5.x cannot read that row. Roll back the
+application writer first; retain 0.6 readers until all MCDB2 values are retired.

data/docs/rfcs/0002-mcdb2-dictionaries.md

@@ -0,0 +1,75 @@
+# RFC 0002: MCDB2 dictionary-backed SQL-readable database envelopes
+
+**Status:** accepted for MultiCompress 0.6.0
+
+## Decision
+
+Introduce MCDB2 as an opt-in storage format for columns containing many small,
+homogeneous UTF-8 documents. MCDB2 uses a zstd dictionary and remains readable from
+Ruby, PostgreSQL and MySQL 5.7. MCDB1 is unchanged and remains dictionary-free.
+
+## Non-goals
+
+- No adaptive mixing of MCDB1 and MCDB2 inside one newly designed column.
+- No dictionary files in `db package` archives.
+- No session registration, global process registry, filesystem lookup, SPI lookup,
+  or implicit dictionary lookup inside the native reader.
+- No content search on decoded payloads.
+
+## Design
+
+MCDB2 uses the 27-byte format specified in `database-envelope-v2.md`. Its registry
+is application-owned, append-only data. Payload rows hold a NOT NULL FK to one
+registry version, and a generated trigger rejects a row unless its MCDB2 header
+`dictionary_ref` equals that FK. Generated views JOIN that version and pass all four
+dictionary arguments to a pure native decoder.
+
+```sql
+SELECT e.id,
+       multi_compress_db_decompress_dict(
+         e.payload_compressed, e.payload_dictionary_id, d.sha256, d.bytes
+       ) AS payload
+FROM app.events e
+JOIN app.mcdb_dictionary_versions d ON d.id = e.payload_dictionary_id;
+```
+
+The function cache is a bounded LRU implementation detail, not a source of data.
+Its key is `dictionary_id + dictionary_sha256`; cache hits also compare canonical
+stored bytes before reuse. This preserves result correctness for direct calls with
+arbitrary SQL arguments.
+
+## Access model
+
+The view owner has access to the source table and dictionary registry. DBeaver users
+receive only `SELECT` on the view, never source-table or registry-table access.
+
+PostgreSQL needs `EXECUTE` on decoder functions for a role selecting the view; grant
+that deliberately to the read role, revoke from PUBLIC, and do not treat the SQL ABI
+as a public arbitrary-dictionary API. MySQL views use a stable `SQL SECURITY DEFINER`
+account; include that account in backup/restore checks.
+
+## Registry invariants
+
+- version rows are INSERT-only under a dedicated NOLOGIN owner in PostgreSQL;
+- `id > 0`, `id <= INT64_MAX` for cross-DB compatibility;
+- SHA-256 matches bytes on INSERT;
+- zstd DictID is non-zero and matches bytes on INSERT;
+- dictionary bytes are at most 256 KiB;
+- payload FK deletion is restricted; dictionary bytes are never updated in place.
+
+## Performance contract
+
+The decoder is intentionally in the projection, after a selective indexed predicate.
+CI validates PostgreSQL and MySQL query plans for `WHERE id >= ... ORDER BY id LIMIT
+10/100/500`. MySQL's generated MCDB2 view uses a source-first `STRAIGHT_JOIN`; the
+plan must remain MERGE-able and read the source through a selective range/ref access
+before dictionary lookup, with no warning or `<derived>` row. MySQL 5.7 may use a
+temporary/filesort implementation for the outer `ORDER BY` over a joined projection;
+that does not mean the view itself was materialized. Benchmark acceptance is separate
+from timing-sensitive CI: it uses a time-split corpus, warm/cold runs, and concurrent
+sessions.
+
+An optional `multi_compress_db_original_size(blob)` helper can support size-aware
+administrative queries. PostgreSQL may use it in a stored generated column; MySQL
+5.7 must use an ordinary maintained column because loadable UDFs are not supported
+in generated columns.

data/exe/multi_compress

@@ -0,0 +1,228 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require "securerandom"
+
+if ARGV.first == "db"
+  require "multi_compress/db_deployment"
+  exit MultiCompress::DBDeployment::CLI.run(ARGV.drop(1))
+end
+
+require "multi_compress"
+
+module MultiCompress
+  class CLI
+    EXT          = { zstd: ".zst", lz4: ".mclz4", brotli: ".br" }.freeze
+    KNOWN_EXT    = { ".zst" => :zstd, ".zstd" => :zstd, ".mclz4" => :lz4, ".br" => :brotli }.freeze
+    NAMED_LEVELS = %w[fastest default best].freeze
+    READ_CHUNK   = 256 * 1024
+    MAX_OUTPUT_LIMIT = (2**(1.size * 8 - 1)) - 1
+
+    def self.run(argv)
+      new.run(argv)
+    end
+
+    def run(argv)
+      opts  = parse(argv)
+      files = opts.delete(:files)
+
+      validate_invocation!(files, opts)
+
+      if files.empty?
+        process_stream($stdin, $stdout, opts)
+      else
+        files.each { |path| process_file(path, opts) }
+      end
+      0
+    rescue OptionParser::ParseError => e
+      warn "multi_compress: #{e.message}"
+      2
+    rescue MultiCompress::Error, SystemCallError, IOError, ArgumentError, RangeError => e
+      warn "multi_compress: #{e.message}"
+      1
+    end
+
+    private
+
+    def parse(argv)
+      o = { decompress: false, keep: false, force: false, stdout: false, quiet: false }
+
+      @parser = OptionParser.new do |p|
+        p.banner = "Usage: multi_compress [OPTIONS] [FILE...]"
+        p.separator ""
+        p.on("-a", "--algo NAME", %w[zstd lz4 brotli], "zstd | lz4 | brotli (default: by extension, else zstd)") { |v| o[:algo] = v.to_sym }
+        p.on("-l", "--level LEVEL", "number, or: fastest | default | best") { |v| o[:level] = parse_level(v) }
+        p.on("-d", "--decompress", "decompress instead of compress") { o[:decompress] = true }
+        p.on("-o", "--output PATH", "write result to PATH (single input only)") { |v| o[:output] = v }
+        p.on("-c", "--stdout", "write to stdout, keep input") { o[:stdout] = true }
+        p.on("-k", "--keep", "keep input file (default: remove on success)") { o[:keep] = true }
+        p.on("-f", "--force", "overwrite existing output") { o[:force] = true }
+        p.on("-q", "--quiet", "no progress line") { o[:quiet] = true }
+        p.on("--max-output SIZE", "cap decompressed size, e.g. 64MB") { |v| o[:max_output_size] = parse_size(v) }
+        p.on("--version", "print gem + library versions") do
+          puts "multi_compress #{MultiCompress::VERSION} (zstd #{MultiCompress.version(:zstd)}, " \
+               "lz4 #{MultiCompress.version(:lz4)}, brotli #{MultiCompress.version(:brotli)})"
+          exit 0
+        end
+        p.on("-h", "--help") { puts p; exit 0 }
+      end
+
+      o[:files] = @parser.parse(argv)
+      o
+    end
+
+    def parse_level(v)
+      return v.to_sym if NAMED_LEVELS.include?(v)
+      Integer(v)
+    rescue ArgumentError
+      raise OptionParser::InvalidArgument, "invalid level: #{v}"
+    end
+
+    def parse_size(v)
+      m = v.strip.match(/\A(\d+)\s*([kmg]?)b?\z/i) or
+        raise OptionParser::InvalidArgument, "invalid size: #{v}"
+      mult = { "" => 1, "k" => 1024, "m" => 1024**2, "g" => 1024**3 }
+      bytes = m[1].to_i * mult[m[2].downcase]
+      if bytes <= 0
+        raise OptionParser::InvalidArgument, "max-output must be greater than zero: #{v}"
+      end
+      if bytes > MAX_OUTPUT_LIMIT
+        raise OptionParser::InvalidArgument, "max-output too large (limit #{MAX_OUTPUT_LIMIT} bytes): #{v}"
+      end
+      bytes
+    end
+
+    def validate_invocation!(files, opts)
+      return if opts[:output].nil?
+
+      if opts[:stdout]
+        raise OptionParser::InvalidOption, "-o and -c are mutually exclusive"
+      end
+      if files.size > 1
+        raise ArgumentError, "-o cannot be used with multiple input files (would overwrite the same output)"
+      end
+    end
+
+    def process_file(path, opts)
+      raise Errno::ENOENT, path unless File.exist?(path)
+
+      if opts[:stdout]
+        File.open(path, "rb") { |input| run_pipeline(input, $stdout, resolve_algo(path, opts), opts) }
+        return
+      end
+
+      out_path = opts[:output] || default_out_path(path, opts)
+      guard_paths!(path, out_path, opts)
+
+      in_size = File.size(path)
+      started = Time.now
+      write_atomically(out_path) do |tmp|
+        File.open(path, "rb") { |input| run_pipeline(input, tmp, resolve_algo(path, opts), opts) }
+      end
+
+      report(path, out_path, in_size, File.size(out_path), started, opts)
+      File.delete(path) unless opts[:keep]
+    end
+
+    def process_stream(input, output, opts)
+      run_pipeline(input, output, opts[:algo] || :zstd, opts)
+    end
+
+    def run_pipeline(input, output, algo, opts)
+      if opts[:decompress]
+        reader_opts = {}
+        reader_opts[:max_output_size] = opts[:max_output_size] if opts[:max_output_size]
+        reader = MultiCompress::Reader.new(input, algo: algo, **reader_opts)
+        while (chunk = reader.read(READ_CHUNK))
+          output.write(chunk)
+        end
+        reader.close
+      else
+        writer = MultiCompress::Writer.new(output, algo: algo, level: opts[:level])
+        while (chunk = input.read(READ_CHUNK))
+          writer.write(chunk)
+        end
+        writer.close
+      end
+    end
+
+    def write_atomically(dst)
+      dir  = File.dirname(dst)
+      tmp  = unique_temp(dir)
+      file = File.open(tmp, File::WRONLY | File::CREAT | File::EXCL | File::BINARY, 0o644)
+      begin
+        yield file
+        file.flush
+        file.fsync
+        file.close
+        File.rename(tmp, dst)
+        fsync_dir(dir)
+      rescue StandardError
+        file.close unless file.closed?
+        File.delete(tmp) if File.exist?(tmp)
+        raise
+      end
+    end
+
+    def unique_temp(dir)
+      loop do
+        candidate = File.join(dir, ".multi_compress.#{Process.pid}.#{SecureRandom.hex(8)}.tmp")
+        return candidate unless File.exist?(candidate)
+      end
+    end
+
+    def fsync_dir(dir)
+      d = File.open(dir)
+      begin
+        d.fsync
+      rescue NotImplementedError, Errno::EINVAL, Errno::EACCES
+        # some platforms/filesystems can't fsync a directory; best-effort
+      ensure
+        d.close
+      end
+    end
+
+    def guard_paths!(src, dst, opts)
+      if same_file?(src, dst)
+        raise ArgumentError, "input and output are the same file: #{src}"
+      end
+      if File.exist?(dst) && !opts[:force]
+        raise ArgumentError, "#{dst} already exists (use -f to overwrite)"
+      end
+    end
+
+    def same_file?(a, b)
+      return true if File.expand_path(a) == File.expand_path(b)
+      File.exist?(a) && File.exist?(b) && File.identical?(a, b)
+    end
+
+    def resolve_algo(path, opts)
+      opts[:algo] || KNOWN_EXT[File.extname(path).downcase] || :zstd
+    end
+
+    def default_out_path(path, opts)
+      if opts[:decompress]
+        stripped = strip_known_ext(path)
+        stripped == path ? "#{path}.out" : stripped
+      else
+        "#{path}#{EXT.fetch(resolve_algo(path, opts))}"
+      end
+    end
+
+    def strip_known_ext(path)
+      ext = File.extname(path).downcase
+      KNOWN_EXT.key?(ext) ? path[0...-ext.length] : path
+    end
+
+    def report(src, dst, in_size, out_size, started, opts)
+      return if opts[:quiet]
+      pct = in_size.zero? ? 0 : (100.0 * out_size / in_size)
+      dir = opts[:decompress] ? "expanded" : "reduced"
+      warn format("%s -> %s  %d -> %d bytes (%s to %.1f%%, %.2fs)",
+                  src, dst, in_size, out_size, dir, pct, Time.now - started)
+    end
+  end
+end
+
+exit MultiCompress::CLI.run(ARGV)

data/ext/multi_compress/extconf.rb

@@ -253,6 +253,10 @@ end
 $CFLAGS += " -O3"
 $CFLAGS += " -DXXH_NAMESPACE=MULTICOMPRESS_"
 
+if RUBY_PLATFORM.include?("darwin") && try_cflags("-Wno-default-const-init-field-unsafe")
+  $CFLAGS += " -Wno-default-const-init-field-unsafe"
+end
+
 case RUBY_PLATFORM
 when /x86_64|amd64|aarch64|arm64/
   $CFLAGS += " -DBROTLI_BUILD_LITTLE_ENDIAN"

data/ext/multi_compress/multi_compress.c

@@ -1560,6 +1560,49 @@ static VALUE compress_compress(int argc, VALUE *argv, VALUE self) {
     return Qnil;
 }
 
+static VALUE zstd_frame_dictionary_id(VALUE self, VALUE data) {
+    (void)self;
+    StringValue(data);
+
+    const void *src = RSTRING_PTR(data);
+    size_t src_len = (size_t)RSTRING_LEN(data);
+    size_t frame_size = ZSTD_findFrameCompressedSize(src, src_len);
+    if (ZSTD_isError(frame_size) || frame_size != src_len)
+        rb_raise(eDataError, "zstd: expected exactly one valid frame with no trailing bytes");
+
+    RB_GC_GUARD(data);
+    return UINT2NUM(ZSTD_getDictID_fromFrame(src, src_len));
+}
+
+static VALUE zstd_single_frame_info(VALUE self, VALUE data) {
+    (void)self;
+    StringValue(data);
+
+    const void *src = RSTRING_PTR(data);
+    size_t src_len = (size_t)RSTRING_LEN(data);
+    size_t frame_size = ZSTD_findFrameCompressedSize(src, src_len);
+    if (ZSTD_isError(frame_size)) {
+        rb_raise(eDataError, "zstd: invalid frame: %s", ZSTD_getErrorName(frame_size));
+    }
+    if (frame_size != src_len) {
+        rb_raise(eDataError, "zstd: expected exactly one frame with no trailing bytes");
+    }
+
+    unsigned long long content_size = ZSTD_getFrameContentSize(src, src_len);
+    if (content_size == ZSTD_CONTENTSIZE_ERROR) {
+        rb_raise(eDataError, "zstd: invalid frame content size");
+    }
+    if (content_size == ZSTD_CONTENTSIZE_UNKNOWN) {
+        rb_raise(eDataError, "zstd: frame must declare content size");
+    }
+
+    VALUE result = rb_ary_new_capa(2);
+    rb_ary_push(result, SIZET2NUM(frame_size));
+    rb_ary_push(result, ULL2NUM(content_size));
+    RB_GC_GUARD(data);
+    return result;
+}
+
 static VALUE compress_decompress(int argc, VALUE *argv, VALUE self) {
     VALUE data, opts;
     scan_one_required_keywords(argc, argv, &data, &opts);
@@ -3442,6 +3485,20 @@ static VALUE dict_algo(VALUE self) {
     return algo_to_sym(d->algo);
 }
 
+static VALUE dict_bytes(VALUE self) {
+    dictionary_t *d;
+    TypedData_Get_Struct(self, dictionary_t, &dictionary_type, d);
+    return rb_binary_str_new((const char *)d->data, (long)d->size);
+}
+
+static VALUE dict_zstd_id(VALUE self) {
+    dictionary_t *d;
+    TypedData_Get_Struct(self, dictionary_t, &dictionary_type, d);
+    if (d->algo != ALGO_ZSTD)
+        rb_raise(eUnsupportedError, "zstd_id is available only for zstd dictionaries");
+    return UINT2NUM(ZSTD_getDictID_fromDict(d->data, d->size));
+}
+
 static VALUE dict_size(VALUE self) {
     dictionary_t *d;
     TypedData_Get_Struct(self, dictionary_t, &dictionary_type, d);
@@ -3478,6 +3535,9 @@ void Init_multi_compress(void) {
 
     rb_define_module_function(mMultiCompress, "compress", compress_compress, -1);
     rb_define_module_function(mMultiCompress, "decompress", compress_decompress, -1);
+    rb_define_module_function(mMultiCompress, "zstd_single_frame_info", zstd_single_frame_info, 1);
+    rb_define_module_function(mMultiCompress, "zstd_frame_dictionary_id", zstd_frame_dictionary_id,
+                              1);
     rb_define_module_function(mMultiCompress, "crc32", compress_crc32, -1);
     rb_define_module_function(mMultiCompress, "adler32", compress_adler32, -1);
     rb_define_module_function(mMultiCompress, "algorithms", compress_algorithms, 0);
@@ -3512,6 +3572,8 @@ void Init_multi_compress(void) {
     rb_define_singleton_method(cDictionary, "load", dict_load, -1);
     rb_define_method(cDictionary, "save", dict_save, 1);
     rb_define_method(cDictionary, "algo", dict_algo, 0);
+    rb_define_method(cDictionary, "bytes", dict_bytes, 0);
+    rb_define_method(cDictionary, "zstd_id", dict_zstd_id, 0);
     rb_define_method(cDictionary, "size", dict_size, 0);
     rb_define_singleton_method(mZstd, "train_dictionary", zstd_train_dictionary, -1);
     rb_define_singleton_method(mBrotli, "train_dictionary", brotli_train_dictionary, -1);

data/lib/multi_compress/active_record.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "multi_compress/codec"
+
+begin
+  require "active_model/type"
+rescue LoadError => e
+  raise LoadError, "multi_compress/active_record requires activemodel (#{e.message}). " \
+                   "Add activerecord/activemodel to your bundle, or use MultiCompress::Codec directly."
+end
+
+module MultiCompress
+  module ActiveRecordSupport
+    class Type < ActiveModel::Type::Value
+      def initialize(mutable: false, **codec_opts)
+        @codec   = MultiCompress::Codec.new(**codec_opts)
+        @mutable = mutable
+        super()
+      end
+
+      def type
+        :multi_compress
+      end
+
+      # user assignment -> in-memory value (no compression here)
+      def cast(value)
+        value
+      end
+
+      # DB -> in-memory (unwrap)
+      def deserialize(value)
+        @codec.load(value)
+      end
+
+      # in-memory -> DB (compress)
+      def serialize(value)
+        @codec.dump(value)
+      end
+
+      def changed_in_place?(raw_old_value, new_value)
+        return false unless @mutable
+
+        deserialize(raw_old_value) != new_value
+      end
+    end
+
+    class Coder
+      def initialize(**codec_opts)
+        @codec = MultiCompress::Codec.new(**codec_opts)
+      end
+
+      def dump(value)
+        @codec.dump(value)
+      end
+
+      def load(value)
+        @codec.load(value)
+      end
+    end
+  end
+end