mysql-handler 0.1.0

Rust bindings for the MySQL handler
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

<h1 align="center">Rusty MySQL Handler</h1>
<p align="center">Build MySQL storage engine plugins in Rust.</p>


> [!WARNING]
> This project is currently experimental. APIs are unstable, behaviour may change between releases, and it is not yet ready for production use.

## đŸ“Ļ Installation

```bash
cargo add mysql-handler
```

Or in `Cargo.toml`:

```toml
[dependencies]
mysql-handler = "0.1"
```

## 🚀 Usage

Implement the `StorageEngine` trait in a `cdylib` crate, then `INSTALL PLUGIN` it into a running `mysql:8.4` server.

#### Prerequisites

- Rust 1.85+
- `mysql:8.4` (any install method — local, Homebrew, Docker, RDS)

#### 1. New cdylib crate

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

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

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

#### 2. Implement StorageEngine

```rust
use mysql_handler::engine::{EngineError, EngineResult, StorageEngine};
use std::ffi::CStr;

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, _i: u32, _p: u32, _all: bool) -> u32 { 0 }

    fn create(&mut self, _name: &str) -> EngineResult { Ok(()) }
    fn open(&mut self, _name: &str, _mode: i32) -> 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 position(&mut self, _record: &[u8], _ref_out: &mut [u8]) {}
    fn rnd_pos(&mut self, _buf: &mut [u8], _pos: &[u8]) -> EngineResult { Ok(()) }

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

Plugin manifest macro: copy from [`examples/engine/src/lib.rs`](./examples/engine/src/lib.rs).

#### 3. Build

```bash
MYSQL_HANDLER_FROM_SOURCE=1 cargo build --release
# or
MYSQL_HANDLER_ARCHIVE=/path/to/libha_rusty_shim.a.gz cargo build --release
```

#### 4. Install

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

## 📊 Performance

Per-callback FFI overhead, callback profile, and OLTP throughput live in [`tests/sysbench/RESULTS.md`](./tests/sysbench/RESULTS.md).

## ❗ Issue

If you have any questions or suggestions, please open an [issue](https://github.com/ren-yamanashi/rusty_mysql_handler/issues).

## Šī¸ License

[GPL-2.0](./LICENSE)