ribbitxdb 1.0.0

A secure and lightweight database engine with BLAKE2 hashing and LZMA compression for Python applications

RibbitXDB

RibbitXDB is a secure and lightweight database engine for Python applications, designed as an enhanced alternative to SQLite3. It combines the simplicity of SQLite3 with advanced security features (BLAKE2 hashing) and LZMA compression for optimal storage efficiency.

Features

• SQLite3-Compatible API: Drop-in replacement with familiar interface
• BLAKE2 Hashing: Built-in data integrity verification for every row
• LZMA Compression: Automatic compression reduces database file size by up to 70%
• B-tree Indexing: Fast query performance with efficient indexing
• ACID Transactions: Full transaction support with commit/rollback
• Page-Based Storage: Efficient memory management with configurable caching
• Zero Dependencies: Built entirely on Python standard library
• Lightweight: Ideal for embedded applications and microservices

Installation

pip install ribbitxdb

Quick Start

import ribbitxdb

# Create/connect to database
conn = ribbitxdb.connect('myapp.rbx')
cursor = conn.cursor()

# Create 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', '[e-mail]')")
cursor.execute("INSERT INTO users VALUES (2, 'Bob', '[e-mail]')")
conn.commit()

# Query data
cursor.execute("SELECT * FROM users WHERE id = 1")
print(cursor.fetchall())

# Close connection
conn.close()

Advanced Usage

Context Manager

import ribbitxdb

with ribbitxdb.connect('myapp.rbx') as conn:
    cursor = conn.cursor()
    cursor.execute("SELECT * FROM users")
    for row in cursor:
        print(row)

Custom Compression Level

# Higher compression (slower, smaller files)
conn = ribbitxdb.connect('myapp.rbx', compression_level=9)

# Lower compression (faster, larger files)
conn = ribbitxdb.connect('myapp.rbx', compression_level=3)

Transactions

conn = ribbitxdb.connect('myapp.rbx')

try:
    cursor = conn.cursor()
    cursor.execute("INSERT INTO users VALUES (3, 'Charlie', '[e-mail]')")
    cursor.execute("INSERT INTO users VALUES (4, 'Diana', '[e-mail]')")
    conn.commit()
except Exception as e:
    conn.rollback()
    print(f"Transaction failed: {e}")
finally:
    conn.close()

Supported SQL Operations

• CREATE TABLE: Define table schemas with constraints
• DROP TABLE: Remove tables
• INSERT: Add new records
• SELECT: Query data with WHERE clauses
• UPDATE: Modify existing records
• DELETE: Remove records

Data Types

• INTEGER: Whole numbers
• REAL: Floating-point numbers
• TEXT: String data
• BLOB: Binary data
• NULL: Null values

Constraints

• PRIMARY KEY: Unique identifier
• NOT NULL: Required field
• UNIQUE: Unique values

Performance

RibbitXDB is optimized for:

• Fast Reads: B-tree indexes enable O(log n) lookups
• Efficient Storage: LZMA compression reduces file size significantly
• Low Memory: Page-based caching minimizes RAM usage
• Data Integrity: BLAKE2 hashing ensures data authenticity

Benchmarks

Operation	RibbitXDB	SQLite3
Insert 10K rows	0.8s	0.6s
Select with index	0.002s	0.001s
File size (10K rows)	45 KB	140 KB

Security

Every row in RibbitXDB is protected with BLAKE2 hashing:

• Data Integrity: Automatic verification on read
• Tamper Detection: Detects unauthorized modifications
• Cryptographic Strength: BLAKE2b with 32-byte digests

Use Cases

RibbitXDB is ideal for:

• Python Applications: Embedded database for desktop/mobile apps
• Microservices: Lightweight data storage
• IoT Devices: Minimal footprint with compression
• Data Archival: Secure, compressed long-term storage
• Prototyping: Quick database setup without external dependencies

API Reference

Connection

conn = ribbitxdb.connect(database, compression_level=6)

• database: Path to database file
• compression_level: LZMA compression level (0-9, default: 6)

Cursor Methods

• execute(sql, parameters=None): Execute SQL statement
• executemany(sql, seq_of_parameters): Execute SQL with multiple parameter sets
• fetchone(): Fetch next row
• fetchmany(size=None): Fetch multiple rows
• fetchall(): Fetch all remaining rows

Connection Methods

• cursor(): Create new cursor
• commit(): Commit current transaction
• rollback(): Rollback current transaction
• close(): Close database connection

Development

Running Tests

pip install pytest pytest-cov
pytest tests/

Building from Source

git clone https://github.com/ribbitx/ribbitxdb.git
cd ribbitxdb
pip install -e .

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Support

• Issues: GitHub Issues
• Documentation: GitHub README

Roadmap

• Query optimizer
• Connection pooling
• Full-text search
• Replication support
• Encryption at rest

---

Made with ❤️ by the RibbitX Team