Crate toolkit_db 

ToolKit Database abstraction crate.

This crate provides a unified interface for working with different databases (SQLite, PostgreSQL, MySQL) through SQLx, with optional SeaORM integration. It emphasizes typed connection options over DSN string manipulation and implements strict security controls (e.g., SQLite PRAGMA whitelist).

Features

• pg, mysql, sqlite: enable SQLx backends
• sea-orm: add SeaORM integration for type-safe operations
• preview-outbox: enable the transactional outbox pipeline (experimental — API may change)

New Architecture

The crate now supports:

• Typed DbConnectOptions using sqlx ConnectOptions (no DSN string building)
• Per-gear database factories with configuration merging
• SQLite PRAGMA whitelist for security
• Environment variable expansion in passwords and DSNs

Example (DbManager API)

use toolkit_db::{DbManager, GlobalDatabaseConfig, DbConnConfig};
use figment::{Figment, providers::Serialized};
use std::path::PathBuf;
use std::sync::Arc;

// Create configuration using Figment
let figment = Figment::new()
    .merge(Serialized::defaults(serde_json::json!({
        "db": {
            "servers": {
                "main": {
                    "host": "localhost",
                    "port": 5432,
                    "user": "app",
                    "password": "${DB_PASSWORD}",
                    "dbname": "app_db"
                }
            }
        },
        "test_gear": {
            "database": {
                "server": "main",
                "dbname": "gear_db"
            }
        }
    })));

// Create DbManager
let home_dir = PathBuf::from("/app/data");
let db_manager = Arc::new(DbManager::from_figment(figment, home_dir).unwrap());

// Use in runtime with DbOptions::Manager(db_manager)
// Gears can then use: ctx.db_required_async().await?

Re-exports

pub use advisory_locks::DbLockGuard;

pub use advisory_locks::LockConfig;

pub use config::DbConnConfig;

pub use config::GlobalDatabaseConfig;

pub use config::PoolCfg;

pub use manager::DbManager;

pub use options::redact_credentials_in_dsn;

pub use secure::DEFAULT_TX_RETRY_ATTEMPTS;

pub use secure::Db;

pub use secure::DbConn;

pub use secure::DbTx;

pub use sea_orm_migration;

Modules

advisory_locks

Advisory locks implementation with namespacing and retry policies.

config

Database configuration types.

contention

Database contention detection utility.

manager

Database manager for per-gear database connections.

migration_runner

Migration runner for ToolKit gears.

odata

OData integration for SeaORM with security-scoped pagination.

options

Database connection options and configuration types.

outbox

Transactional outbox for reliable asynchronous message production.

secure

Secure ORM layer for scoped database access.

Structs

ConnectOpts

Connection options. Extended to cover common sqlx pool knobs; each driver applies the subset it supports.

DBProvider

Thin, reusable DB entrypoint for application services.

Enums

DbEngine

Supported engines.

DbError

Typed error for the DB handle and helpers.

Functions

build_db

Build a secure Db from config (no DbHandle exposure).

connect_db

Connect and return a secure Db (no DbHandle exposure).

Type Aliases

Result

Library-local result type.