The Async Python ORM for Maximum Performance.

Stop choosing between ease of use and speed. KaironDB offers a fully asynchronous, declarative API powered by a Go core to run your database operations at unparalleled speed.

Get Started Download Release

The KaironDB Advantage

Engineered for modern, data-intensive applications.

Truly Concurrent

Built for `async/await`. Run hundreds of queries in parallel, drastically reducing the total time to complete I/O-bound workloads.

Declarative & Safe

Define your tables with intuitive Python classes and get automatic data validation before your data even hits the database.

Powerful Querying API

Forget writing long SQL strings. Build complex queries with `AND` & `OR` conditions programmatically using an elegant, ORM-like interface.

🏆 Performance Championship

Benchmark results: 1000 concurrent database operations

Tested on Windows 11, Intel i7-10700K, 32GB RAM

🥈
2nd

SQLAlchemy

0.0523s
Traditional ORM
+34% slower
WINNER
🏆
1st

KaironDB

0.0389s
Async + Go Backend
🚀 FASTEST
🥉
3rd

PyODBC

0.0685s
Sequential ODBC
+76% slower

📊 Detailed Performance Metrics

Library Avg Time Architecture Concurrency Performance
🏆 KaironDB 0.0389s Python + Go DLL ✅ Full Async BASELINE
🥈 SQLAlchemy 0.0523s Pure Python ORM ⚠️ Limited +34% slower
🥉 PyODBC 0.0685s ODBC Driver ❌ Sequential +76% slower
⚡
Async Advantage

KaironDB's async architecture allows true concurrency, executing multiple queries simultaneously instead of waiting for each one.

🔧
Go Backend

The Go DLL backend provides native performance with efficient memory management and optimized database drivers.

📈
Scalable

Performance advantage increases with workload size. More concurrent operations = bigger performance gains.

Installation

Get KaironDB up and running in seconds

📦 PyPI (Recommended)

# Basic installation
pip install kairondb

# With development dependencies
pip install kairondb[dev]

Perfect for production use and most development scenarios.

🔧 From Source

# Clone repository
git clone https://github.com/DanielGiansante/KaironDB.git
cd KaironDB

# Install in development mode
pip install -e .

# Install development dependencies
pip install -r requirements-dev.txt

For contributors and advanced users who need the latest features.

System Requirements

🐍 Python
  • • Python 3.8+
  • • Tested on 3.8-3.13
  • • Async/await support
💾 Databases
  • • PostgreSQL
  • • SQL Server
  • • MySQL
  • • SQLite
🖥️ OS Support
  • • Windows 10+
  • • Linux (Ubuntu 18.04+)
  • • macOS 10.14+

Getting Started

1. Connecting to Your Database

Click a tab below to see the connection example for your database.

from kairondb import SQLBridge
bridge = SQLBridge(
    driver="sqlserver",
    server="YOUR_SERVER_IP",
    db_name="YOUR_DATABASE",
    user="YOUR_USERNAME",
    password="YOUR_PASSWORD"
)
from kairondb import SQLBridge
bridge = SQLBridge(
    driver="postgres",
    server="localhost",
    db_name="mydb",
    user="user",
    password="pass"
)
from kairondb import SQLBridge
bridge = SQLBridge(
    driver="sqlite3",
    server="./my_local_app.db",
    db_name="", user="", password=""
)

2. Define Your Model

Describe your database table using declarative Python classes.

from kairondb import Model, IntegerField, StringField

class User(Model):
    _table_name = "users"
    id = IntegerField(primary_key=True)
    username = StringField(required=True)

3. Run Async Queries

All database operations are now asynchronous. Remember to associate your models with the bridge and run your code with `asyncio`.

import asyncio

async def main():
    # ... (Bridge connection code from step 1)
    Model.set_bridge(bridge)

    # Fetch users with status 'active' and ID > 100
    results = await User.select(where={
        'status': 'active',
        'id__gt': 100
    })
    print(results)
    
    await bridge.close()

if __name__ == "__main__":
    asyncio.run(main())

Advanced Usage

Complex Queries with `Q` Objects

Use `Q` objects to build complex `AND` (`&`) and `OR` (`|`) conditions programmatically.

from kairondb import Q

# Find active users who are either under 25 OR whose name starts with 'J'
query = Q(status='active') & (Q(age__lt=25) | Q(username__like='J%'))
results = await User.select(where=query)

Concurrent Queries

Run hundreds of queries in parallel using `asyncio.gather` for massive throughput improvements.

user_ids = range(1, 101)
tasks = [User.select(where={'id': uid}) for uid in user_ids]
all_users = await asyncio.gather(*tasks)

Project Statistics

KaironDB development progress and metrics

146
Tests Passing
100% Success Rate
6
Development Phases
All Completed
18+
Field Types
Advanced Validation
4
Database Drivers
Multi-Platform

🚀 Performance

  • • 2.33x faster than sequential
  • • Async/await architecture
  • • Connection pooling
  • • Query caching

🛡️ Reliability

  • • Comprehensive error handling
  • • Input validation
  • • Type safety
  • • Extensive testing

🔧 Developer Experience

  • • Declarative API
  • • Rich documentation
  • • Real-time monitoring
  • • Easy debugging

📚 Complete Documentation

Everything you need to master KaironDB

From basic concepts to advanced patterns

🎯 Core Concepts

🏗️
Architecture

KaironDB uses a hybrid Python-Go architecture for optimal performance:

  • • Python Layer: Provides the familiar async/await API and model definitions
  • • Go Backend: Handles database connections, query execution, and connection pooling
  • • DLL/SO Bridge: Enables seamless communication between Python and Go
⚡
Async Patterns

KaironDB is built from the ground up for async/await:

  • ✓ Non-blocking: Never blocks the event loop
  • ✓ Concurrent: Execute hundreds of queries simultaneously
  • ✓ Scalable: Performance improves with concurrent load

🏛️ Model System

Declarative Models

Define your database schema using Python classes:

class User(Model):
    _table_name = "users"
    
    id = IntegerField(primary_key=True)
    name = StringField(required=True)
    email = EmailField(unique=True)
    age = IntegerField(min_value=18)
Field Types

Rich set of field types with built-in validation:

StringField
IntegerField
EmailField
DateTimeField
FloatField
BooleanField
JSONField
URLField

🔍 Advanced Query System

Q Objects

Build complex queries programmatically:

from kairondb import Q

# Complex AND/OR conditions
query = Q(status='active') & (
    Q(age__gte=18) | 
    Q(role='admin')
)

users = await User.select(where=query)

Supports all SQL operators: gt, lt, gte, lte, like, in, not_in, etc.

Query Operators

Rich set of query operators:

field__gt Greater than
field__like SQL LIKE pattern
field__in IN list of values
field__isnull IS NULL check

🚀 Advanced Features

🏊
Connection Pooling

Automatic connection management with configurable pool sizes.

  • • Automatic connection reuse
  • • Configurable pool limits
  • • Health check monitoring
  • • Graceful connection cleanup
💾
Query Caching

Intelligent caching system for frequently accessed data.

  • • Automatic cache invalidation
  • • Configurable TTL
  • • Memory-efficient storage
  • • Cache hit/miss metrics
📊
Live Dashboard

Real-time monitoring and performance metrics.

  • • Query performance tracking
  • • Connection pool status
  • • Error rate monitoring
  • • System health scores
📚

API Reference

Complete reference for all classes, methods, and functions.

  • • SQLBridge class
  • • Model definitions
  • • Query objects (Q)
  • • Field types
  • • Exceptions
View API Docs →
⚙️

Installation Guide

Step-by-step installation for all platforms and databases.

  • • PyPI installation
  • • Source installation
  • • Database setup
  • • Troubleshooting
  • • Verification
View Guide →
🔧

Troubleshooting

Common issues and their solutions for smooth development.

  • • Connection issues
  • • DLL problems
  • • Validation errors
  • • Performance tips
  • • Debug tools
View Guide →
🚀

Advanced Features

Unlock the full power of KaironDB with advanced capabilities.

  • • Connection pooling
  • • Query caching
  • • Database migrations
  • • Performance profiling
  • • Real-time dashboard
View Features →
🏗️

Field Types

Comprehensive guide to all available field types and validators.

  • • Basic fields (String, Integer, etc.)
  • • Advanced fields (Email, URL, etc.)
  • • Custom validators
  • • Date/Time fields
  • • JSON and Array fields
View Examples →
💡

Best Practices

Learn how to write efficient and maintainable code with KaironDB.

  • • Async patterns
  • • Connection management
  • • Query optimization
  • • Error handling
  • • Testing strategies
View Examples →

Real-World Examples

See KaironDB in action with practical use cases

# Basic CRUD operations with KaironDB
import asyncio
from kairondb import SQLBridge, Model, StringField, IntegerField

class User(Model):
    _table_name = "users"
    id = IntegerField(primary_key=True)
    name = StringField(required=True)
    email = StringField(required=True)

async def main():
    # Connect to database
    bridge = SQLBridge(
        driver="sqlite3",
        server=":memory:",
        db_name="",
        user="",
        password=""
    )
    
    # Set bridge for models
    Model.set_bridge(bridge)
    
    # Create table
    await bridge.exec("""
        CREATE TABLE users (
            id INTEGER PRIMARY KEY,
            name TEXT NOT NULL,
            email TEXT NOT NULL
        )
    """)
    
    # CREATE - Insert new user
    user = User(name="John Smith", email="john@example.com")
    await user.save()
    
    # READ - Select users
    users = await User.select()
    print(users)
    
    # UPDATE - Update user
    user.name = "John Johnson"
    await user.save()
    
    # DELETE - Delete user
    await user.delete()
    
    await bridge.close()

if __name__ == "__main__":
    asyncio.run(main())
# Advanced features: Pooling, Caching, Profiling
import asyncio
from kairondb import SQLBridge

async def advanced_example():
    # Bridge with all advanced features
    bridge = SQLBridge(
        driver="postgres",
        server="localhost",
        db_name="mydb",
        user="user",
        password="pass",
        # Advanced features
        enable_advanced_pool=True,
        enable_query_cache=True,
        enable_profiling=True,
        enable_dashboard=True
    )
    
    # Start dashboard
    await bridge.start_dashboard()
    
    # Execute queries (will be cached and profiled)
    for i in range(100):
        result = await bridge.select("users", ["*"])
    
    # Get performance metrics
    metrics = bridge.get_performance_metrics()
    print(f"Average query time: {metrics['average_duration']:.4f}s")
    
    # Get dashboard summary
    summary = bridge.get_dashboard_summary()
    print(f"System score: {summary['score']}")
    
    await bridge.close()
# Performance: Concurrent queries with asyncio
import asyncio
import time
from kairondb import SQLBridge

async def performance_test():
    bridge = SQLBridge(
        driver="postgres",
        server="localhost",
        db_name="mydb",
        user="user",
        password="pass"
    )
    
    # Create 1000 concurrent queries
    start_time = time.time()
    
    tasks = [
        bridge.select("users", ["*"], {"id": i})
        for i in range(1000)
    ]
    
    # Execute all queries concurrently
    results = await asyncio.gather(*tasks)
    
    end_time = time.time()
    total_time = end_time - start_time
    
    print(f"Executed 1000 queries in {total_time:.4f} seconds")
    print(f"Average: {total_time/1000:.4f} seconds per query")
    
    await bridge.close()
# Advanced validation with custom fields
from kairondb import Model, EmailField, StringField, IntegerField

class User(Model):
    _table_name = "users"
    
    id = IntegerField(primary_key=True)
    name = StringField(
        required=True,
        max_length=100
    )
    email = EmailField(required=True)
    age = IntegerField(
        min_value=18,
        max_value=120
    )

# Valid user
try:
    user = User(
        name="John Smith",
        email="joao@example.com",
        age=30
    )
    print("✅ Valid user created")
except ValidationError as e:
    print(f"❌ Validation error: {e}")

# Invalid user (will raise ValidationError)
try:
    invalid_user = User(
        name="",  # Empty name
        email="invalid-email",  # Invalid email
        age=15  # Too young
    )
except ValidationError as e:
    print(f"❌ Validation error: {e}")