idb/
lib.rs

1//! InnoDB file analysis toolkit.
2//!
3//! The `innodb-utils` crate (library name `idb`) provides Rust types and
4//! functions for parsing, inspecting, and manipulating InnoDB tablespace
5//! files (`.ibd`), redo log files, and system tablespace data (`ibdata1`).
6//!
7//! # CLI Reference
8//!
9//! Install the `inno` binary and use its subcommands to work with InnoDB
10//! files from the command line.
11//!
12//! ## Installation
13//!
14//! ```text
15//! cargo install innodb-utils          # crates.io
16//! brew install ringo380/tap/inno      # Homebrew (macOS/Linux)
17//! ```
18//!
19//! Pre-built binaries for Linux and macOS (x86_64 + aarch64) are available
20//! on the [GitHub releases page](https://github.com/ringo380/idb-utils/releases).
21//!
22//! ## Subcommands
23//!
24//! | Command | Purpose |
25//! |---------|---------|
26//! | [`inno parse`](cli::app::Commands::Parse) | Parse `.ibd` file and display page summary |
27//! | [`inno pages`](cli::app::Commands::Pages) | Detailed page structure analysis (INDEX, UNDO, LOB, SDI) |
28//! | [`inno dump`](cli::app::Commands::Dump) | Hex dump of raw page bytes |
29//! | [`inno checksum`](cli::app::Commands::Checksum) | Validate page checksums (CRC-32C and legacy) |
30//! | [`inno corrupt`](cli::app::Commands::Corrupt) | Intentionally corrupt pages for testing |
31//! | [`inno recover`](cli::app::Commands::Recover) | Assess page-level recoverability and count salvageable records |
32//! | [`inno find`](cli::app::Commands::Find) | Search data directory for pages by number |
33//! | [`inno tsid`](cli::app::Commands::Tsid) | List or find tablespace IDs |
34//! | [`inno sdi`](cli::app::Commands::Sdi) | Extract SDI metadata (MySQL 8.0+) |
35//! | [`inno log`](cli::app::Commands::Log) | Analyze InnoDB redo log files |
36//! | [`inno info`](cli::app::Commands::Info) | Inspect ibdata1, compare LSNs, query MySQL |
37//!
38//! ## Global options
39//!
40//! All subcommands accept `--color <auto|always|never>` and `--output <file>`.
41//! Most subcommands also accept `--json` for machine-readable output and
42//! `--page-size` to override auto-detection.
43//!
44//! See the [`cli`] module for full details.
45//!
46//! # Library API
47//!
48//! Add `idb` as a dependency to use the parsing library directly:
49//!
50//! ```toml
51//! [dependencies]
52//! idb = { package = "innodb-utils", version = "1" }
53//! ```
54//!
55//! ## Quick example
56//!
57//! ```no_run
58//! use idb::innodb::tablespace::Tablespace;
59//! use idb::innodb::checksum::validate_checksum;
60//! use idb::innodb::page::FilHeader;
61//!
62//! // Open a tablespace (page size is auto-detected from page 0)
63//! let mut ts = Tablespace::open("table.ibd").unwrap();
64//!
65//! // Read and inspect a page
66//! let page = ts.read_page(0).unwrap();
67//! let header = FilHeader::parse(&page).unwrap();
68//! println!("Page type: {}", header.page_type);
69//!
70//! // Validate the page checksum
71//! let result = validate_checksum(&page, ts.page_size());
72//! println!("Checksum valid: {}", result.valid);
73//! ```
74//!
75//! ## Key entry points
76//!
77//! | Type / Function | Purpose |
78//! |-----------------|---------|
79//! | [`Tablespace`](innodb::tablespace::Tablespace) | Open `.ibd` files, read pages, iterate |
80//! | [`FilHeader`](innodb::page::FilHeader) | Parse the 38-byte header on every InnoDB page |
81//! | [`PageType`](innodb::page_types::PageType) | Map page type codes to names and descriptions |
82//! | [`validate_checksum`](innodb::checksum::validate_checksum) | CRC-32C and legacy checksum validation |
83//! | [`extract_sdi_from_pages`](innodb::sdi::extract_sdi_from_pages) | SDI metadata extraction (MySQL 8.0+) |
84//! | [`LogFile`](innodb::log::LogFile) | Read and inspect redo log files |
85//!
86//! ## Module overview
87//!
88//! | Module | Purpose |
89//! |--------|---------|
90//! | [`innodb::tablespace`] | File I/O, page size detection, page iteration |
91//! | [`innodb::page`] | FIL header/trailer, FSP header parsing |
92//! | [`innodb::page_types`] | Page type enum with names and descriptions |
93//! | [`innodb::checksum`] | CRC-32C and legacy InnoDB checksum algorithms |
94//! | [`innodb::index`] | INDEX page internals (B+Tree header, FSEG) |
95//! | [`innodb::record`] | Row-level record parsing (compact format) |
96//! | [`innodb::sdi`] | SDI metadata extraction and decompression |
97//! | [`innodb::log`] | Redo log file structure and block parsing |
98//! | [`innodb::undo`] | UNDO log page structures |
99//! | [`innodb::lob`] | Large object (BLOB/LOB) page headers |
100//! | [`innodb::compression`] | Compression detection and decompression |
101//! | [`innodb::encryption`] | Encryption detection from FSP flags |
102//! | [`innodb::constants`] | InnoDB page/file structure constants |
103//!
104//! ## Feature flags
105//!
106//! | Feature | Default | Description |
107//! |---------|---------|-------------|
108//! | `mysql` | off | Enables live MySQL queries via `mysql_async` + `tokio` (used by `inno info`). |
109
110pub mod cli;
111pub mod innodb;
112pub mod util;
113
114use thiserror::Error;
115
116/// Errors returned by `idb` operations.
117#[derive(Error, Debug)]
118pub enum IdbError {
119    /// An I/O error occurred (file open, read, seek, or write failure).
120    #[error("I/O error: {0}")]
121    Io(String),
122
123    /// A parse error occurred (malformed binary data or unexpected values).
124    #[error("Parse error: {0}")]
125    Parse(String),
126
127    /// An invalid argument was supplied (out-of-range page number, bad option, etc.).
128    #[error("Invalid argument: {0}")]
129    Argument(String),
130}
idb/lib.rs

idb/
lib.rs
