mysql-handler 0.1.1

[!WARNING] Experimental. APIs are unstable and not yet production-ready.

📦 Installation

[dependencies]
mysql-handler = "0.1"

[build-dependencies]
mysql-handler-build = "0.1"

🚀 Usage

Decorate an engine struct with #[plugin(..)] in a cdylib crate, then INSTALL PLUGIN it into a running mysql:8.4 server.

Prerequisites

• Rust 1.85+
• mysql:8.4

1. New cdylib crate

[package]
name = "my-engine"
edition = "2024"

[lib]
crate-type = ["cdylib"]

[dependencies]
mysql-handler = "0.1"

[build-dependencies]
mysql-handler-build = "0.1"

// build.rs
fn main() {
    mysql_handler_build::configure();
}

2. Implement StorageEngine

use mysql_handler::prelude::*;
use std::ffi::CStr;

#[plugin(
    name = "MY_ENGINE",
    description = "Custom storage engine",
    version = 0x0001,
    license = License::Gpl,
    author = "you",
)]
#[derive(Debug, Default)]
pub struct MyEngine;

impl StorageEngine for MyEngine {
    fn table_type(&self) -> &'static CStr { c"MY_ENGINE" }
    fn table_flags(&self) -> u64 { 0 }
    fn index_flags(&self, _idx: u32, _part: u32, _all_parts: bool) -> u32 { 0 }

    fn create(&mut self, _name: &str, _td: Option<&mysql_handler::sys::DdTable>) -> EngineResult { Ok(()) }
    fn open(&mut self, _name: &str, _mode: i32, _td: Option<&mysql_handler::sys::DdTable>) -> EngineResult { Ok(()) }
    fn close(&mut self) -> EngineResult { Ok(()) }

    fn rnd_init(&mut self, _scan: bool) -> EngineResult { Ok(()) }
    fn rnd_next(&mut self, _buf: &mut [u8]) -> EngineResult { Err(EngineError::EndOfFile) }
    fn rnd_pos(&mut self, _buf: &mut [u8], _pos: &[u8]) -> EngineResult { Ok(()) }
    fn position(&mut self, _record: &[u8], _ref_out: &mut [u8]) {}

    fn info(&mut self, _flag: u32) -> EngineResult { Ok(()) }
}

A full reference engine lives in examples/engine/.

3. Build

build.rs needs the C++ shim staticlib (libha_rusty_shim.a):

MYSQL_HANDLER_FROM_SOURCE=1 cargo build --release   # cmake from mysql-server/ submodule
MYSQL_HANDLER_ARCHIVE=<path> cargo build --release  # prebuilt .a.gz

4. Install

INSTALL PLUGIN my_engine SONAME 'libmy_engine.so';
CREATE TABLE t (id INT) ENGINE=MY_ENGINE;

📊 Performance

tests/sysbench/RESULTS.md.

❗ Issue

Open an issue.

©️ License

GPL-2.0