Introduction

Welcome to the official documentation for RibbitXDB, the secure, lightweight, and high-performance database engine for Python applications.

RibbitXDB is designed to be a modern alternative to SQLite for specific use cases requiring enhanced security and storage efficiency. It embeds cryptographic verification and compression directly into the core engine.

Key Features

• Secure by Design: Every row is cryptographically hashed with BLAKE2b for tamper-proof data integrity.
• Lightweight Storage: Native LZMA compression reduces database size by up to 70% without sacrificing speed.
• High Performance: B-tree indexing and optimized page caching ensure O(log n) query performance.
• Pure Python: Zero external dependencies. Drop-in replacement for SQLite3 workflows.

Installation

RibbitXDB is available on PyPI and can be installed using pip:

pip install ribbitxdb

Requirements: Python 3.8+

Quick Start

RibbitXDB follows the Python DB-API 2.0 standard (like SQLite3), making it incredibly easy to use.

import ribbitxdb

# Connect to database (creates it if it doesn't exist)
conn = ribbitxdb.connect('myapp.rbx')
cursor = conn.cursor()

# Create a table
cursor.execute('''
    CREATE TABLE users (
        id INTEGER PRIMARY KEY,
        name TEXT NOT NULL,
        email TEXT UNIQUE
    )
''')

# Insert data
cursor.execute("INSERT INTO users VALUES (1, 'Alice', 'alice@ribbitx.com')")
conn.commit()

# Query data
cursor.execute("SELECT * FROM users")
print(cursor.fetchall())
# Output: [(1, 'Alice', 'alice@ribbitx.com')]

conn.close()

Architecture

RibbitXDB is built on a sophisticated page-based storage engine designed for reliability and performance.

• Page Structure: 4KB fixed-size pages with header tracking free space and type.
• Storage Engine: Manages page allocation, reading/writing, and caching (default 2000 pages).
• B-Tree Indexing: Uses Order-128 B-Trees for efficient primary key lookups and range scans.

Security (BLAKE2)

RibbitXDB takes unique approach to data integrity by embedding cryptographic verification into the storage layer.

When a row is inserted, a BLAKE2b hash (32-byte digest) is computed from the binary data. This hash is stored alongside the record. Upon retrieval, the engine re-computes the hash and verifies it against the stored signature, ensuring that data hasn't been modified on disk by external processes.

Compression (LZMA)

RibbitXDB integrates LZMA (Lempel-Ziv-Markov chain algorithm) compression transparency into the paging system.

Connection

The connect() function is the entry point to the database.

ribbitxdb.connect(database, **kwargs)

Opens a connection to the SQLite database file database. Returns a Connection object.

• database: Path to the database file.
• compression_level: Integer 0-9 (default 6).

Cursor & Queries

Cursors allow you to execute SQL statements and fetch results.

execute(sql, parameters=())

Executes a SQL statement. Parameters can be provided as a tuple.

fetchone() / fetchall()

Retrieves the next row or all remaining rows of a query result.

Transactions

RibbitXDB supports ACID transactions with commit and rollback functionality.

try:
    with ribbitxdb.connect('bank.rbx') as conn:
        cursor = conn.cursor()
        cursor.execute("UPDATE accounts SET balance = balance - 100 WHERE id = 1")
        cursor.execute("UPDATE accounts SET balance = balance + 100 WHERE id = 2")
        # Implicit commit on exit
except Exception:
    # Implicit rollback on error
    print("Transaction cancelled")

Benchmarks

Performance metrics compared to standard file I/O and other embedded solutions.

Write Performance

Approx 12,500 inserts/sec with compression enabled (Level 6).

Read Performance

Approx 45,000 selects/sec using primary key indexing.

Storage Efficiency

Reduces storage footprint by approximately 30-70% compared to uncompressed raw data, depending on data entropy.

Examples

Storing Binary Data (BLOBs)

conn = ribbitxdb.connect('images.rbx', compression_level=9)
cursor = conn.cursor()
cursor.execute("CREATE TABLE images (id INTEGER PRIMARY KEY, data BLOB)")

with open('photo.jpg', 'rb') as f:
    blob = f.read()

cursor.execute("INSERT INTO images VALUES (1, ?)", (blob,))
conn.commit()

Changelog

v1.0.0 Latest

• Initial Release
• Core storage engine with LZMA compression.
• BLAKE2b hashing for row-level security.
• B-Tree indexing implementation.
• Basic SQL support (CREATE, INSERT, SELECT, UPDATE, DELETE).