ethereum_mysql/lib.rs
1#![cfg_attr(docsrs, feature(doc_cfg))]
2//! # ethereum-mysql
3//!
4//! Type-safe, ergonomic wrappers for Ethereum types with seamless SQLx database integration.
5//!
6//! This crate provides SQL-compatible wrappers for common Ethereum types (`Address`, `U256`, `FixedBytes`, `Bytes`),
7//! designed for use with the async SQLx toolkit and relational databases (MySQL, PostgreSQL, SQLite).
8//!
9//! ## Supported Types
10//!
11//! - **SqlAddress**: Type-safe wrapper for `alloy::primitives::Address` (Ethereum address)
12//! - **SqlU256**: Wrapper for `alloy::primitives::U256` (256-bit unsigned integer) with full arithmetic and conversion support
13//! - **`SqlFixedBytes<N>`**: Generic wrapper for fixed-size byte arrays (e.g. hashes, topics)
14//! - **SqlHash**/**SqlTopicHash**: Type aliases for `SqlFixedBytes<32>` (commonly used for hashes/topics)
15//! - **SqlBytes**: Wrapper for dynamic-length byte arrays
16//!
17//! ## Design Highlights
18//!
19//! - **String-based storage only**: All types are stored as lowercase hex strings (with `0x` prefix) in the database for maximum compatibility and easy inspection.
20//! - **Type safety**: Compile-time and runtime validation for all Ethereum types, eliminating manual string parsing and validation in business logic.
21//! - **API ergonomics**: Direct arithmetic, comparison, and conversion with Rust primitives for U256, and compile-time address macros for zero-cost, safe usage.
22//! - **No binary mode**: Binary column support and related feature flags have been removed for simplicity and reliability.
23//! - **Minimal, focused API**: Only the most practical and widely-used Ethereum types and operations are supported, with optional serde integration.
24//!
25//! ## SQLx Integration
26//!
27//! This crate implements the necessary SQLx traits (`Type`, `Encode`, `Decode`) for all wrappers, enabling direct use in queries and result sets without manual conversion.
28//!
29//! - **Multi-database support**: MySQL, PostgreSQL, SQLite (via SQLx)
30//! - **Serde support**: Optional JSON serialization for all wrappers (enable the `serde` feature)
31//! - **Constants**: Pre-defined constants like `SqlAddress::ZERO`, `SqlU256::ZERO`
32//! - **Compile-time macros**: Create addresses at compile time with `sqladdress!`
33//!
34//! ## Recommended Database Column Types
35//!
36//! | Type | Recommended Column Type |
37//! |--------------------|------------------------|
38//! | SqlAddress | VARCHAR(42) |
39//! | SqlU256 | VARCHAR(66) |
40//! | `SqlFixedBytes<N>` | VARCHAR(2+2*N) |
41//! | SqlBytes | TEXT |
42//!
43//! For PostgreSQL, use `TEXT` for all string types. For MySQL/SQLite, use `VARCHAR` as above.
44//!
45//! ## Example Usage
46//!
47//! ```rust
48//! use ethereum_mysql::{SqlAddress, SqlU256, SqlHash, sqladdress};
49//! use std::str::FromStr;
50//!
51//! // Address usage
52//! let zero = SqlAddress::ZERO;
53//! let addr = sqladdress!("0x742d35Cc6635C0532925a3b8D42cC72b5c2A9A1d");
54//! let addr2 = SqlAddress::from_str("0x742d35Cc6635C0532925a3b8D42cC72b5c2A9A1d").unwrap();
55//!
56//! // U256 usage with arithmetic
57//! let balance = SqlU256::from_str("1000000000000000000").unwrap(); // 1 ETH in wei
58//! let doubled = balance * 2;
59//!
60//! // Hash usage
61//! let tx_hash = SqlHash::from_str("0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef").unwrap();
62//! println!("Tx hash: {}", tx_hash);
63//! ```
64//!
65//! ## Migration Notes
66//!
67//! - All binary mode and related feature flags have been removed. Only string-based storage is supported.
68//! - Update your database schema to use string (hex) columns for all Ethereum types.
69//! - See README for more details and migration guidance.
70
71#![warn(missing_docs)]
72
73mod macros;
74mod sql_address;
75mod sql_bytes;
76mod sql_fixed_bytes;
77mod sql_uint;
78
79pub mod utils;
80
81pub use sql_address::{Address, SqlAddress};
82pub use sql_bytes::{Bytes, SqlBytes};
83pub use sql_fixed_bytes::{FixedBytes, SqlFixedBytes, SqlHash, SqlTopicHash};
84pub use sql_uint::{SqlU256, SqlUint, U256};
85
86#[cfg(feature = "sqlx")]
87pub mod sqlx;
88
89// Re-export alloy for macro usage
90#[doc(hidden)]
91pub use alloy;