innodb-utils 5.0.0

InnoDB file analysis toolkit
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
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163

//! InnoDB file analysis toolkit.
//!
//! The `innodb-utils` crate (library name `idb`) provides Rust types and
//! functions for parsing, inspecting, and manipulating InnoDB tablespace
//! files (`.ibd`), redo log files, system tablespace data (`ibdata1`), and
//! MySQL binary log files.
//!
//! # CLI Reference
//!
//! Install the `inno` binary and use its subcommands to work with InnoDB
//! files from the command line.
//!
//! ## Installation
//!
//! ```text
//! cargo install innodb-utils          # crates.io
//! brew install ringo380/tap/inno      # Homebrew (macOS/Linux)
//! ```
//!
//! Pre-built binaries for Linux and macOS (x86_64 + aarch64) are available
//! on the [GitHub releases page](https://github.com/ringo380/idb-utils/releases).
//!
//! ## Subcommands
//!
//! | Command | Purpose |
//! |---------|---------|
//! | [`inno parse`](cli::app::Commands::Parse) | Parse `.ibd` file and display page summary |
//! | [`inno pages`](cli::app::Commands::Pages) | Detailed page structure analysis (INDEX, UNDO, LOB, SDI) |
//! | [`inno dump`](cli::app::Commands::Dump) | Hex dump of raw page bytes |
//! | [`inno checksum`](cli::app::Commands::Checksum) | Validate page checksums (CRC-32C, legacy, MariaDB full\_crc32) |
//! | [`inno diff`](cli::app::Commands::Diff) | Compare two tablespace files page-by-page |
//! | [`inno watch`](cli::app::Commands::Watch) | Monitor a tablespace file for page-level changes |
//! | [`inno corrupt`](cli::app::Commands::Corrupt) | Intentionally corrupt pages for testing |
//! | [`inno recover`](cli::app::Commands::Recover) | Assess page-level recoverability and count salvageable records |
//! | [`inno find`](cli::app::Commands::Find) | Search data directory for pages by number |
//! | [`inno tsid`](cli::app::Commands::Tsid) | List or find tablespace IDs |
//! | [`inno sdi`](cli::app::Commands::Sdi) | Extract SDI metadata (MySQL 8.0+) |
//! | [`inno schema`](cli::app::Commands::Schema) | Extract schema and reconstruct DDL from SDI |
//! | [`inno log`](cli::app::Commands::Log) | Analyze InnoDB redo log files |
//! | [`inno info`](cli::app::Commands::Info) | Inspect ibdata1, compare LSNs, query MySQL |
//!
//! ## Global options
//!
//! All subcommands accept `--color <auto|always|never>` and `--output <file>`.
//! Most subcommands also accept `--json` for machine-readable output and
//! `--page-size` to override auto-detection.
//!
//! See the [`cli`] module for full details.
//!
//! # Library API
//!
//! Add `idb` as a dependency to use the parsing library directly:
//!
//! ```toml
//! [dependencies]
//! idb = { package = "innodb-utils", version = "1" }
//! ```
//!
//! ## Quick example
//!
//! ```no_run
//! use idb::innodb::tablespace::Tablespace;
//! use idb::innodb::checksum::validate_checksum;
//! use idb::innodb::page::FilHeader;
//!
//! // Open a tablespace (page size is auto-detected from page 0)
//! let mut ts = Tablespace::open("table.ibd").unwrap();
//!
//! // Read and inspect a page
//! let page = ts.read_page(0).unwrap();
//! let header = FilHeader::parse(&page).unwrap();
//! println!("Page type: {}", header.page_type);
//!
//! // Validate the page checksum
//! let result = validate_checksum(&page, ts.page_size(), None);
//! println!("Checksum valid: {}", result.valid);
//! ```
//!
//! ## Key entry points
//!
//! | Type / Function | Purpose |
//! |-----------------|---------|
//! | [`Tablespace`](innodb::tablespace::Tablespace) | Open `.ibd` files, read pages, iterate |
//! | [`FilHeader`](innodb::page::FilHeader) | Parse the 38-byte header on every InnoDB page |
//! | [`PageType`](innodb::page_types::PageType) | Map page type codes to names and descriptions |
//! | [`validate_checksum`](innodb::checksum::validate_checksum) | CRC-32C, legacy, and MariaDB full\_crc32 validation |
//! | [`extract_sdi_from_pages`](innodb::sdi::extract_sdi_from_pages) | SDI metadata extraction (MySQL 8.0+) |
//! | [`LogFile`](innodb::log::LogFile) | Read and inspect redo log files |
//! | [`VendorInfo`](innodb::vendor::VendorInfo) | Detected vendor (MySQL / Percona / MariaDB) and format details |
//! | [`BinlogFile`](binlog::BinlogFile) | Read and iterate MySQL binary log events |
//!
//! ## Module overview
//!
//! | Module | Purpose |
//! |--------|---------|
//! | [`innodb::tablespace`] | File I/O, page size detection, page iteration |
//! | [`innodb::page`] | FIL header/trailer, FSP header parsing |
//! | [`innodb::page_types`] | Page type enum with names and descriptions |
//! | [`innodb::checksum`] | CRC-32C and legacy InnoDB checksum algorithms |
//! | [`innodb::index`] | INDEX page internals (B+Tree header, FSEG) |
//! | [`innodb::record`] | Row-level record parsing (compact format) |
//! | [`innodb::sdi`] | SDI metadata extraction and decompression |
//! | [`innodb::log`] | Redo log file structure and block parsing |
//! | [`innodb::undo`] | UNDO log page structures |
//! | [`innodb::lob`] | Large object (BLOB/LOB) page headers |
//! | [`innodb::compression`] | Compression detection and decompression |
//! | [`innodb::encryption`] | Encryption detection and encryption info parsing |
//! | [`innodb::decryption`] | AES-256-CBC page decryption with keyring support |
//! | [`innodb::keyring`] | MySQL `keyring_file` plugin binary format reader |
//! | [`innodb::vendor`] | Vendor detection (MySQL, Percona, MariaDB) and format info |
//! | [`innodb::constants`] | InnoDB page/file structure constants |
//! | [`binlog`] | MySQL binary log file parsing, event types, and checksum validation |
//!
//! ## Feature flags
//!
//! | Feature | Default | Description |
//! |---------|---------|-------------|
//! | `mysql` | off | Enables live MySQL queries via `mysql_async` + `tokio` (used by `inno info`). |
//!
//! # WASM
//!
//! The library can be compiled to WebAssembly for browser-based InnoDB file analysis:
//!
//! ```bash
//! wasm-pack build --release --target web --no-default-features
//! ```
//!
//! The WASM API exposes JSON-returning functions for all core operations:
//! `get_tablespace_info`, `parse_tablespace`, `analyze_pages`,
//! `validate_checksums`, `extract_sdi`, `diff_tablespaces`, `hex_dump_page`,
//! `assess_recovery`, and `parse_redo_log`. Each function accepts raw file
//! bytes as a `Uint8Array` and returns a JSON string (or plain text for hex
//! dumps). See the [`wasm`] module documentation for details on individual
//! function signatures and return schemas.
//!
//! A live web analyzer built on these bindings is available at
//! <https://ringo380.github.io/idb-utils/>.

pub mod binlog;
#[cfg(feature = "cli")]
pub mod cli;
pub mod innodb;
pub mod util;
#[cfg(target_arch = "wasm32")]
pub mod wasm;

use thiserror::Error;

/// Errors returned by `idb` operations.
#[derive(Error, Debug)]
pub enum IdbError {
    /// An I/O error occurred (file open, read, seek, or write failure).
    #[error("I/O error: {0}")]
    Io(String),

    /// A parse error occurred (malformed binary data or unexpected values).
    #[error("Parse error: {0}")]
    Parse(String),

    /// An invalid argument was supplied (out-of-range page number, bad option, etc.).
    #[error("Invalid argument: {0}")]
    Argument(String),
}