vsql_allow_preview_extensions = ON to install. See Preview Capabilities for how to enable the preview tier and register a capability.
Column storage lets an extension register a custom binary on-disk layout
directly with InnoDB for one of its custom types, instead of routing the
type’s bytes through the row’s VARBINARY payload. Use it when your type
needs an on-disk shape VARBINARY cannot express — for example, a packed
array of floats that must live in dedicated pages. This is a capability
feature: it enables new storage layouts, not a tuning knob for existing ones.
Declaring the Capabilities
Two preview capabilities work together:vsql::preview::storage— opens access to InnoDB storage infrastructure (mini-transactions, segments, pages). Declare aStorageCapabilityat file scope.vsql::preview::column_store— binds a per-type storage implementation to one of the extension’s custom types. Declare aColumnStoreCapabilityat file scope usingmake_column_store<Ctx>(TYPE).…build().
.with() on make_extension():
make_column_store<MyCtx>(MY_TYPE) ties the implementation to one custom
type registered on the same extension. All seven slots are required at
build() time because each maps to a distinct point in the column lifecycle
that InnoDB will reach during normal operation.
The Seven Storage Functions
Every function takesstorage::Column::StorageCtx<MyCtx>*, whose user()
accessor returns the extension’s per-column state and whose arena() provides
server-managed allocation for auxiliary objects. Every function returns false
on success and true on error, writing a message into error_msg (capacity
error_msg_len). The server writes that message to its error log; a failed create or insert
fails the statement with ERROR 3219 (HY000): InnoDB: Custom type operation failed. See server error log for details.
mark_delete and purge are distinct because InnoDB MVCC requires deleted
rows to remain readable by older snapshots until purge runs.
Per-Column Context and the Arena
The C++ SDK default-constructsMyCtx before calling either create or load —
ctx->user() is already populated when your function is entered. MyCtx must
be default-constructible; the C++ SDK calls T() with no arguments.
Use ctx->user() directly to initialize state. Do not call
ctx->arena().construct<MyCtx>() — that allocates a second, unused instance
and ctx->user() does not point to it.
load follows the same pattern — ctx->user() is pre-populated and
storage_ref carries the packed value stored by ctx->set_ref() in create:
ctx->arena() only to allocate auxiliary objects that are too large or
dynamic to embed directly in MyCtx. The C++ SDK destroys the arena — and calls
~MyCtx() — automatically after drop returns, regardless of whether drop
succeeds.
InnoDB Access Utilities
Include<villagesql/preview/storage_api.h> for the InnoDB primitives.
All page reads and writes must occur inside a mini-transaction:
create time — see the create and load
examples in Per-Column Context above for the complete setup pattern. During
DML operations, get a segment reference from the root page to allocate new
pages:
mtr_ref to write calls so InnoDB logs the change:
The page accessors reject an offset inside the header or trailer region: a release build
skips the read or write, and a build without
NDEBUG fails an assert. InnoDB uses those byte ranges for its own bookkeeping and checksum.