ribbitxdb 1.1.8

Drop-in SQLite alternative with async API, migrations, schema introspection, and 100% SQL compatibility

RibbitXDB

The Modern, Async-First Embedded Database for Python

---

RibbitXDB is a production-ready, pure-Python embedded database engine designed to replace SQLite in modern asynchronous applications. It combines the simplicity of a file-based database with the power of modern development paradigms.

🚀 Why RibbitXDB?

• ⚡ Async Native: Built-in async/await support for non-blocking I/O.
• 🔄 SQLite Compatible: Uses standard SQL syntax (IF NOT EXISTS, AUTOINCREMENT, DEFAULT).
• 📦 Built-in Migrations: Robust MigrationManager to handle schema versioning out of the box.
• 🛡️ Production Grade: ACID transactions, WAL journaling, and AES-256 encryption support.
• 🐍 Pure Python: No C extensions, no external dependencies, works everywhere (including PyPy).

---

📦 Installation

pip install ribbitxdb

🏎️ Quick Start

Modern Async API

Perfect for FastAPI, Sanic, or Discord bots.

import asyncio
from ribbitxdb import connect_async

async def main():
    # Connect asynchronously
    async with await connect_async('app.rbx') as conn:
        cursor = await conn.cursor()
        
        # Create table
        await cursor.execute("""
            CREATE TABLE IF NOT EXISTS users (
                id INTEGER PRIMARY KEY AUTOINCREMENT,
                username TEXT NOT NULL UNIQUE,
                email TEXT,
                created_at TEXT DEFAULT CURRENT_TIMESTAMP
            )
        """)
        
        # Insert data
        await cursor.execute(
            "INSERT INTO users (username, email) VALUES (?, ?)", 
            ('ribbit_fan', '[e-mail]')
        )
        
        # Query data
        await cursor.execute("SELECT * FROM users")
        row = await cursor.fetchone()
        print(f"User: {row['username']}")

asyncio.run(main())

Classic Synchronous API

Drop-in replacement for sqlite3.

import ribbitxdb

with ribbitxdb.connect('legacy.rbx') as conn:
    cursor = conn.cursor()
    cursor.execute("SELECT * FROM products WHERE price > ?", (100,))
    for row in cursor.fetchall():
        print(row)

🛠️ Integrated Migrations

Stop using external tools for simple schema changes. RibbitXDB has migration support built-in.

from ribbitxdb.migrations import MigrationManager

# Setup
conn = ribbitxdb.connect('app.rbx')
migrator = MigrationManager(conn)
migrator.set_migrations_directory('./migrations')

# Generate a new migration
# Creates: ./migrations/20251222_add_posts.sql
migrator.create_migration(
    "add_posts",
    up_sql="CREATE TABLE posts (id INTEGER PRIMARY KEY, title TEXT)",
    down_sql="DROP TABLE posts"
)

# Apply pending migrations
migrator.up()

# Revert last migration
migrator.down()

🔍 Deep Introspection

RibbitXDB exposes system tables for powerful debugging.

-- See your schema
SHOW TABLES;
DESCRIBE users;

-- Check indexes
SHOW INDEXES users;

-- Explain query plan
EXPLAIN SELECT * FROM users WHERE id = 1;

⚙️ Advanced Configuration

Connection Pooling

For high-concurrency environments.

from ribbitxdb import ConnectionPool

pool = ConnectionPool('app.rbx', min_connections=5, max_connections=20)
with pool.get_connection() as conn:
    # ... use connection

Encryption & Security

Protect sensitive data at rest.

# Enable AES-256 Encryption
conn = ribbitxdb.connect('secure.rbx', encryption_key=b'my_secret_32_byte_key...')

📊 Performance Benchmark

Operation	RibbitXDB v1.1.6	SQLite3 (Python)
Connection	0.05ms	0.08ms
Bulk Insert (10k)	0.28s	0.35s
Async Select	Native	Wrapper Overhead
Dependencies	0	0

🗺️ Roadmap & Ecosystem

RibbitXDB is constantly evolving. v1.1.6 introduces the core stability features needed for mission-critical deployments. Future updates will focus on:

• Remote Server Mode (TCP/TLS) improvements.
• Distributed Replication.
• JSON Document Store features.

🙏 Contributors

Special thanks to the following contributors who have helped improve RibbitXDB:

• Salmaan Nagoormira - Python 3.8 compatibility analysis and type hint fixes (v1.1.6.4)

---

Built with ❤️ for the Python Community
Documentation • Source Code • PyPI