Warning

This is not authoritative documentation. It describes a plan of work that is not yet implemented and will change as it lands.

Task 3: plugin skeleton, metadata, and DDL

Repo: https://opendev.org/drizzle/drizzle, plugin/slatedb/. Depends on tasks 1 (shim) and 2 (codec). Delivers a loadable engine that owns its metadata: CREATE / DROP / RENAME / SHOW work; no row access yet (cursor methods return HA_ERR_WRONG_COMMAND).

Structure, mirroring plugin/wiredtiger:

  • plugin.ini: load_by_default=no; sources; ldflags=-lslatedb_capi. Inclusion is the explicit --with-slatedb build switch per the container-first policy — no plugin.ac detection probes; the builder image definitionally contains the shim.

  • slatedb_engine.{h,cc}, slatedb_to_drizzle_error.cc (the one status→``HA_ERR_*`` map), plus the task-2 codec and the capi header.

Engine init / shutdown

slatedb_init: read slatedb.url / slatedb.path / slatedb.settings-file / slatedb.await-durable options (registered through the standard plugin option machinery — note for the CLI11 migration: four options, no custom types), check SLATEDB_CAPI_VERSION, slatedb_open. On first open of an empty database, write the format-version meta key; on open of a populated one, verify it. Engine destructor closes the Db (flush-on-close is SlateDB’s own contract).

Flags at this stage: HTON_ALTER_NOT_SUPPORTED | HTON_TEMPORARY_NOT_SUPPORTED | HTON_NO_BLOBS | HTON_NULL_IN_KEY — no HTON_HAS_RECORDS, ever, per the spec’s statistics-honesty rule.

Metadata and DDL (all via short-lived shim transactions)

  • doGetTableDefinition: get 0x00 'p' <path>; parse proto; EEXIST / ENOENT.

  • doDoesTableExist: same key, existence only.

  • doGetTableIdentifiers: prefix scan 0x00 'p'; the CachedDirectory parameter is ignored (function_engine precedent).

  • doCreateTable: validate first, refuse loudly — every column type must be codec-supported (BLOB refused with a named error), a PRIMARY KEY must exist (v1: refuse hidden-PK tables rather than invent a rowid; recorded as a possible later task), all index columns codec-supported. Then one transaction: read+bump 0x00 'c', write id mapping and proto, commit. A commit CONFLICT (concurrent DDL) maps to a retryable error.

  • doDropTable: one transaction deleting proto + id mapping and — v1 — foreground prefix delete of data keys in batched chunks inside the same transaction if small, or successive transactions if large (chunk size a constant, noted for task 7 to obsolete).

  • doRenameTable: rewrite the two meta keys in one transaction; data untouched (keys carry only the table id).

  • validateCreateTableOption: nothing engine-specific accepted in v1 (refuse unknown options by returning false, the honest default).

Tests

drizzle-test cases: create/show/drop/rename round trips; refusal messages for BLOB columns, missing PK, unsupported types (result files assert the specific error text); DATA_DICTIONARY.TABLES shows the engine; restart persistence (create, restart server, table still there) — the first end-to-end proof that state lives in the bucket (file:// object store in CI).

Verification

  • Build green with --with-slatedb on and off (both switch states).

  • drizzle-test green including the new cases, in the vouched pipeline using the composed builder image from task 1.