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.

Proven Performance

See how KaironDB's async architecture outperforms traditional sequential execution.

benchmark.py

async def run_kairondb_benchmark():
    # Creates 1000 query tasks
    tasks = [User.select(where={'id': 6}) for _ in range(1000)]
    await asyncio.gather(*tasks)

def run_pyodbc_benchmark():
    # Opens one connection and runs 1000 queries sequentially
    for _ in range(1000):
        cursor.execute(sql_query, params)
        cursor.fetchall()

> python benchmark.py

==================================================

🏁 FINAL RESULTS 🏁

==================================================

KaironDB (Concurrent): 0.8432 seconds

pyodbc (Sequential): 1.9670 seconds

--------------------------------------------------

🏆 KaironDB was 2.33x faster at completing the total workload!

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

📚

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}")