Skip to main content
The capabilities on this page are in preview: their APIs are not stable, and an extension that declares one requires 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.
Column storage is a preview ABI — under active development and may change between releases. It currently covers row-level persistence only; a custom-stored column accepts only a custom index, and an ordinary index is refused with ERROR 3219 (HY000): InnoDB: Indexing for types with column storage is supported only with custom index.

Declaring the Capabilities

Two preview capabilities work together:
  • vsql::preview::storage — opens access to InnoDB storage infrastructure (mini-transactions, segments, pages). Declare a StorageCapability at file scope.
  • vsql::preview::column_store — binds a per-type storage implementation to one of the extension’s custom types. Declare a ColumnStoreCapability at file scope using make_column_store<Ctx>(TYPE).…build().
Both must be passed to .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 takes storage::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-constructs MyCtx 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:
Use 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:
Committing the mini-transaction releases page latches and writes the redo log records that make changes durable. Segments are reserved at 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:
Pages are read with a shared latch and written with an exclusive one. Pass mtr_ref to write calls so InnoDB logs the change:
Page layout constants: 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.