Skip to content

Kirky-X/dbnexus

BranchesTags

Repository files navigation

DBNexus Logo

CI Status Version Documentation Downloads License Rust 1.85+

Enterprise-grade Database Abstraction Layer for Rust

✨ Features • 🚀 Quick Start • 📚 Documentation • 💻 Examples • 🤝 Contributing

🎯 A high-performance, secure, and feature-rich database access layer built on Sea-ORM

DBNexus provides a declarative database access approach:

✨ Type Safe 🔒 Permission Control 🏊 Smart Pooling 📊 Enterprise Monitoring
Compile-time checks Table-level RBAC RAII auto-management Prometheus metrics 
use dbnexus::{DbPool, DbEntity, db_crud, db_permission};
use sea_orm::entity::prelude::*;

#[derive(DbEntity, DeriveEntityModel, DeriveModel, DeriveActiveModel)]
#[sea_orm(table_name = "users")]
#[db_crud]
#[db_permission(roles = ["admin", "manager"], operations = ["SELECT", "INSERT"])]
pub struct User {
    #[sea_orm(primary_key)]
    pub id: i64,
    pub name: String,
    pub email: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let pool = DbPool::new("sqlite::memory:").await?;
    let session = pool.get_session("admin").await?;
    let user = User { id: 1, name: "Alice".to_string(), email: "alice@example.com".to_string() };
    User::insert(&session, user).await?;
    Ok(())
}

📋 Table of Contents

📑 Table of Contents (Click to expand)

✨ Features

🎯 Core Features ⚡ Enterprise Features
Always Available Optional

🎯 Core Features (Always Available)

Status Feature Description
✅ Connection Pooling RAII-style automatic connection lifecycle management
✅ Permission Control Role-based table-level access control (RBAC)
✅ Procedural Macros Auto-generate CRUD methods and permission checks
✅ SQL Parser Extract operation type and target table
✅ Transaction Support Complete transaction management
✅ Multi-Database Support SQLite, PostgreSQL, MySQL

⚡ Enterprise Features

Status Feature Description
🔍 Metrics Monitoring Prometheus metrics export (metrics feature)
📊 Distributed Tracing OpenTelemetry integration (tracing feature)
📝 Audit Logging Automatic audit for all operations (audit feature)
🗄️ Database Migration Automatic migration execution (migration feature)
🔀 Data Sharding Support for sharding strategies (sharding feature)
🌐 Global Index Cross-shard queries (global-index feature)
💾 Caching LRU cache support (cache feature)
🔐 Permission Engine Advanced permission system (permission-engine feature)

📦 Feature Presets

Preset Features Use Case
embedded runtime-tokio-rustls, sqlite, config-env Ultra-minimal for embedded/edge devices
microservice runtime-tokio-rustls, postgres, permission, sql-parser, config-env, observability Microservice deployment
monolith runtime-tokio-rustls, postgres, permission, sql-parser, config-yaml, data-management, security, observability Monolithic application
enterprise postgres, monolith, permission-engine, confers Full enterprise features
all-optional All optional features without database drivers All enterprise features (manual database selection)

🚀 Quick Start

📦 Installation

Add this to your Cargo.toml:

[dependencies]
dbnexus = "0.1.1"
tokio = { version = "1.42", features = ["rt-multi-thread", "macros"] }
sea-orm = { version = "2.0.0-rc.27", features = ["macros"] }

💡 Basic Usage

🎬 5-Minute Quick Start

Step 1: Define Entity

use dbnexus::{DbPool, DbEntity, db_crud};
use sea_orm::entity::prelude::*;

#[derive(DbEntity, DeriveEntityModel, DeriveModel, DeriveActiveModel)]
#[sea_orm(table_name = "users")]
#[db_crud]
pub struct User {
    #[sea_orm(primary_key)]
    pub id: i64,
    pub name: String,
    pub email: String,
}

Step 2: Create Connection Pool

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let pool = DbPool::new("sqlite::memory:").await?;
    let session = pool.get_session("admin").await?;
    Ok(())
}

Step 3: Insert Data

let user = User {
    id: 1,
    name: "Alice".to_string(),
    email: "alice@example.com".to_string(),
};
User::insert(&session, user).await?;

Step 4: Query Data

let users = User::find_all(&session).await?;
println!("Found {} users", users.len());

🔒 Permission Control

use dbnexus::{DbPool, DbEntity, db_crud, db_permission};
use sea_orm::entity::prelude::*;

#[derive(DbEntity, DeriveEntityModel, DeriveModel, DeriveActiveModel)]
#[sea_orm(table_name = "users")]
#[db_crud]
#[db_permission(roles = ["admin", "manager"], operations = ["SELECT", "INSERT"])]
pub struct User {
    #[sea_orm(primary_key)]
    pub id: i64,
    pub name: String,
}

// Admin can access
let session = pool.get_session("admin").await?;
User::find_all(&session).await?;

// Regular user will be denied
let session = pool.get_session("guest").await?;
User::find_all(&session).await?; // Error: Permission denied

🎨 Feature Flags

⚠️ BREAKING CHANGE in v0.2.0

All users must update their Cargo.toml:

Version 0.1.x → 0.2.0 is a breaking change. The cache feature is no longer enabled by default, and several features now explicitly require cache to be enabled.

Database Drivers (choose one)

# SQLite
dbnexus = { version = "0.2", features = ["sqlite"] }

# PostgreSQL
dbnexus = { version = "0.2", features = ["postgres"] }

# MySQL
dbnexus = { version = "0.2", features = ["mysql"] }

Core Features

# Permission control (REQUIRES cache feature)
dbnexus = { version = "0.2", features = ["permission", "cache"] }

# SQL parsing (REQUIRES cache feature)
dbnexus = { version = "0.2", features = ["sql-parser", "cache"] }

# Procedural macros
dbnexus = { version = "0.2", features = ["macros"] }

# Caching (required by permission and sql-parser)
dbnexus = { version = "0.2", features = ["cache"] }

Using Presets (Recommended)

# Embedded/Edge devices (minimal)
dbnexus = { version = "0.2", features = ["embedded"] }

# Microservices
dbnexus = { version = "0.2", features = ["microservice"] }

# Monolithic applications
dbnexus = { version = "0.2", features = ["monolith"] }

# Enterprise (all features)
dbnexus = { version = "0.2", features = ["enterprise"] }

Optional Features

# Observability (metrics + tracing + health-check)
dbnexus = { version = "0.2", features = ["observability"] }

# Data management (migration + sharding + global-index)
dbnexus = { version = "0.2", features = ["data-management"] }

# Security (audit + permission-engine)
dbnexus = { version = "0.2", features = ["security"] }

# Individual features
dbnexus = { version = "0.2", features = [
    "metrics",         # Prometheus metrics
    "tracing",         # Distributed tracing
    "audit",           # Audit logging
    "migration",       # Database migration
    "sharding",        # Data sharding
    "permission-engine" # Advanced permission engine (requires cache)
] }

Configuration

dbnexus = { version = "0.2", features = [
    "config-yaml",     # YAML config support
    "config-toml",     # TOML config support
    "config-env",      # Environment variables
] }

📚 Documentation

📖 User Guide

Comprehensive guide
📘 API Reference

Complete API docs
💻 Examples

Code examples

📖 Additional Resources

Resource Description
📖 User Guide Comprehensive guide for using DBNexus
📘 API Reference Complete API documentation
🏗️ Architecture System architecture and design decisions
📦 Examples Working code examples

💻 Examples

💡 Real-world Examples

📝 Advanced Configuration

use dbnexus::{DbPool, config::DbConfigBuilder};

let config = DbConfigBuilder::new()
    .url("postgresql://user:pass@localhost/db")
    .max_connections(20)
    .min_connections(5)
    .idle_timeout(300)
    .acquire_timeout(5000)
    .build()?;

let pool = DbPool::with_config(config).await?;

🔧 Environment Variables

export DATABASE_URL="postgresql://user:pass@localhost/db"
export DB_MAX_CONNECTIONS=20
export DB_MIN_CONNECTIONS=5
export DB_ADMIN_ROLE=admin
let pool = DbPool::new().await?;

🔄 Transactions

let mut session = pool.get_session("admin").await?;

// Begin transaction
session.begin_transaction().await?;

// Multiple operations
User::insert(&session, user1).await?;
User::insert(&session, user2).await?;

// Commit
session.commit_transaction().await?;

📊 Monitoring

use dbnexus::{DbPool, metrics::MetricsCollector};

let pool = DbPool::new("postgresql://localhost/db").await?;

// Get pool status
let status = pool.status();
println!("Active: {}, Idle: {}", status.active, status.idle);

// Export Prometheus metrics
let metrics = MetricsCollector::new(&pool);
println!("{}", metrics.export_prometheus());

🏗️ Architecture

🏗️ System Architecture

graph TD
    A[Application Layer<br/>Your code using DbPool and Session] --> B[DBNexus API Layer<br/>DbPool, Session<br/>Permission checking<br/>Transaction management]
    B --> C[Feature Modules<br/>Config, Permission, Metrics<br/>Migration, Sharding, Audit]
    C --> D[Connection Pool<br/>Connection lifecycle management<br/>Health checking<br/>RAII guarantees]
    D --> E[Sea-ORM / SQLx<br/>Database drivers<br/>Query builder]
Loading

See ARCHITECTURE.md for detailed architecture documentation.

🔒 Security

🛡️ Security Features

DBNexus is built with security in mind:

  • No unsafe code - #![forbid(unsafe_code)] in all library code
  • Permission enforcement - Table-level access control with compile-time verification
  • SQL injection prevention - Parameterized queries by default
  • Config path validation - Protection against path traversal attacks
  • Rate limiting - Permission check rate limiting to prevent abuse

🧪 Testing

🎯 Run Tests

# SQLite tests
cargo test --features sqlite

# PostgreSQL tests
cargo test --features postgres

# MySQL tests
cargo test --features mysql

# All tests (requires Docker)
make test-all

Using Docker

# Start databases
make docker-up

# Run all tests
make test-all

# Stop databases
make docker-down

🤝 Contributing

Contributions are welcome! Please check the repository for contribution guidelines.

Development Setup

# Clone repository
git clone https://github.com/Kirky-X/dbnexus.git
cd dbnexus

# Install pre-commit hooks
./scripts/install-pre-commit.sh

# Run tests
cargo test --all-features

# Run linter
cargo clippy --all-features

📄 License

This project is licensed under MIT:

License: MIT

🙏 Acknowledgments

🌟 Built on Excellent Tools

  • Sea-ORM - The excellent ORM framework DBNexus is built on
  • SQLx - Async SQL toolkit
  • The Rust community for amazing tools and libraries

📞 Support

📋 Issues

Report bugs and issues
💬 Discussions

Ask questions and share ideas
🐙 GitHub

View source code

⭐ Star History

Star History Chart

💝 Support This Project

If you find this project useful, please consider giving it a ⭐️!

Built with ❤️ by Kirky.X

⬆ Back to Top

© 2026 Kirky.X. All rights reserved.

About

DBNexus is an enterprise level Rust database abstraction layer built on Sea ORM, providing high-performance and high security data access capabilities for applications.

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

1 fork
Report repository

Releases

2 tags

Packages

 
 
 

Contributors

Languages