SeaORM Connection Pool (seaorm-pool)

A robust and easy-to-use utility for creating a sea-orm connection pool from a configuration file. Designed for async Rust applications connecting to MySQL-compatible databases like TiDB.

Overview

seaorm-pool eliminates the boilerplate of setting up a database connection. It provides a clean, configuration-driven function that creates a fully configured sea-orm connection pool, ready to use in your application.

It is built on top of industry-standard crates to ensure reliability and performance:

• SeaORM: The core async ORM for Rust.
• Serde: For effortless serialization and deserialization of your configuration.
• Tokio: As the underlying async runtime.
• Tracing: For structured, context-aware logging.

✨ Key Features

• Configuration-Driven: Define your entire database setup in a single TOML file.
• Robust Connection Pooling: Fine-tune the connection pool with options for max_connections, min_connections, idle_timeout, max_lifetime, and more.
• Async Ready: A single async function call is all you need.
• Secure by Default: Easily configure SSL/TLS for encrypted database connections.
• Structured Logging: Integrated with tracing to provide clear insight into the connection lifecycle.

🚀 Installation

Add seaorm-pool and its required peer dependencies to your Cargo.toml:

## ⚙️ Usage Quick Start

### 1. Create a Configuration File

Create a `Settings.toml` file in your project's root directory. **Note that the configuration must be under a `[database]` table** to match the crate's `AppConfig` struct.

```toml
# Settings.toml

# The `[database]` table is required.
[database]
host = "gateway01.eu-central-1.prod.aws.tidbcloud.com"
port = 4000
username = "your_username"
password = "your_password"
databaseName = "your_db"
# Optional: Path to your SSL CA certificate for secure connections.
# sslCa = "/path/to/your/ca.pem"

# Nested table for connection pool options.
[database.poolOptions]
maxConnections = 10
minConnections = 5
acquireTimeout = "30s"
idleTimeout = "10m"
maxLifetime = "30m"
isLazy = true

2. Connect in Your Application

Use the create_connection_pool function to establish the database connection.

// src/main.rs

use sea_orm::{DatabaseConnection, Statement, DatabaseBackend};
use seaorm_pool::{config::AppConfig, create_connection_pool};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Load configuration using the `config` crate.
    let settings = config::Config::builder()
        .add_source(config::File::with_name("Settings"))
        .build()?;

    let app_config: AppConfig = settings.try_deserialize()?;

    // 2. Create the database connection pool from the config.
    println!("Establishing connection pool...");
    let pool: DatabaseConnection = create_connection_pool(app_config.database).await?;
    println!("Connection pool established successfully!");

    // 3. Use the pool to execute a query.
    let result = pool.execute(Statement::from_string(
        DatabaseBackend::MySql,
        "SELECT 'Connection successful!' as message;".to_string(),
    )).await?;

    println!("Query executed. Rows affected: {}", result.rows_affected());

    Ok(())
}

📋 Configuration Details

The crate is configured through the AppConfig struct, which contains a database field of type DatabaseConfig.

Main Settings ([database])

Pool Options ([database.poolOptions])

License

This project is licensed under either of:

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request for any improvements or bug fixes.