Skip to main content

Crate ethereum_mysql

Crate ethereum_mysql 

Source
Expand description

§ethereum-mysql

Type-safe, ergonomic wrappers for Ethereum types — the missing bridge between Rust application code and SQL databases for Web3 developers.

§Why this crate?

While alloy provides the foundational Ethereum types, writing production Web3 backend code still requires tedious boilerplate:

// Without ethereum-mysql: manual conversions everywhere
let balance: U256 = row.get::<String, _>("balance").parse()?;
let new_balance = balance + U256::from(100u64);  // verbose, no primitive ops
let fee = balance * U256::from(25) / U256::from(10000);  // unreadable

With ethereum-mysql, it’s just:

let balance: SqlU256 = row.get("balance");
let new_balance = balance + 100u64;          // natural arithmetic
let fee = balance * 25u64 / 10000u64;        // clean & readable

This crate provides SQL-compatible wrappers for common Ethereum types (Address, U256, U128, FixedBytes, Bytes), designed for use with the async SQLx toolkit and relational databases (MySQL, PostgreSQL, SQLite).

§Supported Types

  • SqlAddress: Type-safe wrapper for alloy::primitives::Address (Ethereum address)
  • SqlU128: Wrapper for alloy::primitives::U128 (128-bit unsigned integer, common for Solidity uint128)
  • SqlU256: Wrapper for alloy::primitives::U256 (256-bit unsigned integer) with full arithmetic and conversion support
  • SqlFixedBytes<N>: Generic wrapper for fixed-size byte arrays (e.g. hashes, topics)
    • SqlHash/SqlTopicHash: Type aliases for SqlFixedBytes<32> (commonly used for hashes/topics)
  • SqlBytes: Wrapper for dynamic-length byte arrays

§Design Highlights

  • 🔥 Intuitive Arithmetic: Direct +, -, *, /, % between SqlU256/SqlU128 and Rust primitives — write balance * 25u64 / 10000u64 instead of balance * U256::from(25) / U256::from(10000).
  • 🚀 API-Ready: Use SqlAddress/SqlU256/SqlU128 directly in your #[derive(Serialize, Deserialize, FromRow)] request/response structs. Zero manual conversion in web handlers.
  • Binary storage: All types are stored as raw big-endian bytes (BINARY/BYTEA/BLOB) for optimal storage efficiency and performance. Follows the same approach as alloy-rs/core PR #970 and PR #1020.
  • Type safety: Compile-time and runtime validation for all Ethereum types.
  • Unified error handling: All conversion errors use the SqlTypeError enum — no more &'static str error messages.

§SQLx Integration

This crate implements the necessary SQLx traits (Type, Encode, Decode) for all wrappers, enabling direct use in queries and result sets without manual conversion.

  • Multi-database support: MySQL, PostgreSQL, SQLite (via SQLx)
  • Serde support: Optional JSON serialization for all wrappers (enable the serde feature)
  • Constants: Pre-defined constants like SqlAddress::ZERO, SqlU256::ZERO, SqlU256::ETHER
  • Compile-time macros: Create addresses at compile time with sqladdress!
TypeMySQLPostgreSQLSQLite
SqlAddressBINARY(20)BYTEABLOB
SqlU128BINARY(16)BYTEABLOB
SqlU256BINARY(32)BYTEABLOB
SqlFixedBytes<N>BINARY(N)BYTEABLOB
SqlBytesVARBINARYBYTEABLOB

§Example Usage

use ethereum_mysql::{SqlAddress, SqlU256, SqlU128, SqlHash, sqladdress};
use std::str::FromStr;

// Address usage
let zero = SqlAddress::ZERO;
let addr = sqladdress!("0x742d35Cc6635C0532925a3b8D42cC72b5c2A9A1d");

// U256 arithmetic — clean, intuitive, no manual conversions
let balance = SqlU256::from_str("1000000000000000000").unwrap(); // 1 ETH in wei
let doubled = balance * 2u64;
let fee = balance * 25u64 / 10000u64;  // 0.25% fee, pure readability

// U128 usage
let amount: SqlU128 = SqlU128::from(1000u64);
let half = amount / 2u64;

// Hash usage
let tx_hash = SqlHash::from_str("0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef").unwrap();

§Migration from v3.x (String Storage)

Starting from v4.0, all types are stored as binary (BINARY/BYTEA/BLOB) instead of hex strings (VARCHAR/TEXT). See the CHANGELOG for migration guidance.

Re-exports§

pub use error::SqlTypeError;

Modules§

error
Unified error type for ethereum-mysql type conversions.
sqlxsqlx
This module is only available when the sqlx feature is enabled. Support for the sqlx crate.
utils
Utilities for parsing and formatting SqlU256 with decimals (e.g. for ERC20/ETH amounts).

Macros§

sqladdress
Creates a SqlAddress from a hex string literal.
sqlhash
Macro to create a SqlFixedBytes<N> from a hex string literal at compile time.
sqlu256
Macro to create a SqlU256 from a literal (compile-time check for negative, only usable in runtime context).

Structs§

Address
An Ethereum address, 20 bytes in length.
Bytes
Wrapper type around bytes::Bytes to support “0x” prefixed hex strings.
FixedBytes
A byte array of fixed length ([u8; N]).
SqlAddress
SQL-compatible wrapper for Ethereum Address.
SqlBytes
A wrapper around Bytes to represent SQL byte arrays.
SqlFixedBytes
A wrapper around FixedBytes that provides a SQL-compatible type for fixed-size byte arrays.
SqlUint
A SQL-compatible wrapper for fixed-width unsigned integers.

Type Aliases§

SqlHash
A type alias for a 32-byte fixed-size byte array, commonly used for hashes.
SqlTopicHash
A type alias for a 32-byte fixed-size byte array, commonly used for topic hashes.
SqlU128
A type alias for a 128-bit unsigned integer, commonly used for Solidity uint128 values.
SqlU256
A type alias for a 256-bit unsigned integer, commonly used for Ethereum values.
U128
128-bit unsigned integer type, consisting of 2, 64-bit limbs.
U256
256-bit unsigned integer type, consisting of 4, 64-bit limbs.