zenithdb

ZenithDB

A high-performance document database built on SQLite with MongoDB-like syntax. ZenithDB combines the simplicity and reliability of SQLite with the flexibility of document databases.

What is ZenithDB?

ZenithDB is a powerful, lightweight document database that provides a MongoDB-like experience while leveraging SQLite as the storage engine. It's perfect for:

• Applications that need document database features without the complexity of a separate server
• Projects requiring embedded databases with rich querying capabilities
• Developers who enjoy MongoDB's API but need SQLite's portability and simplicity
• Situations where a full-scale NoSQL database would be overkill

🚀 Key Features

• Document Storage & Validation: Store and validate JSON-like documents with nested structures
• Advanced Querying: Full-text search, nested field queries, array operations
• Multiple Query Styles: Support for both MongoDB-style dict queries and fluent Query builder
• Indexing: Single, compound, and full-text search indexes for optimized performance
• Pattern Matching: Regex, starts/ends with, and advanced text search capabilities
• Advanced Aggregations: Group and aggregate with COUNT, AVG, SUM, MEDIAN, STDDEV, and more
• Bulk Operations: Efficient batch processing with transaction support
• Connection Pooling: Built-in connection pool for concurrent operations
• Migration Support: Versioned database migrations with up/down functions
• Backup & Restore: Simple database backup and restore operations
• Type Annotations: Full Python type hints for better IDE integration
• Performance Optimizations: Query plan analysis, index utilization, and connection pooling

📦 Installation

pip install zenithdb

🚀 Quick Start

from zenithdb import Database

# Initialize database
db = Database("myapp.db")
users = db.collection("users")

# Add document validation
def age_validator(doc):
    return isinstance(doc.get('age'), int) and doc['age'] >= 0
users.set_validator(age_validator)

# Insert documents
users.insert({
    "name": "John Doe",
    "age": 30,
    "tags": ["premium"],
    "profile": {"city": "New York"}
})

# Query documents
users.find({
    "age": {"$gt": 25},
    "tags": {"$contains": "premium"}
})

# Full-text search
users.find({"*": {"$contains": "John"}})

# Nested updates
users.update(
    {"name": "John Doe"},
    {"$set": {
        "profile.city": "Brooklyn",
        "tags.0": "vip"
    }}
)

# Aggregations
users.aggregate([{
    "group": {
        "field": "profile.city",
        "function": "COUNT",
        "alias": "count"
    }
}])

📚 Detailed Documentation

Collection Management

# List and count collections
db.list_collections()
db.count_collections()

# Drop collections
db.drop_collection("users")
db.drop_all_collections()

# Print collection contents
users.print_collection()
users.count()

Advanced Querying

ZenithDB supports two querying styles:

MongoDB Style (Dict-based)

# Find documents with comparison operators
users.find({
    "age": {"$gt": 25, "$lte": 50},
    "profile.city": "New York", 
    "tags": {"$contains": "premium"}
})

# Full-text search across all fields
results = users.find({"*": {"$contains": "search term"}})

# Pattern matching with regex, starts with, and ends with
users.find({
    "email": {"$regex": "^[a-z0-9]+@example\\.com$"},
    "name": {"$startsWith": "Jo"},
    "domain": {"$endsWith": ".org"}
})

Query Builder (Fluent API)

from zenithdb import Query

q = Query()
results = users.find(
    (q.age > 25) & 
    (q.age <= 50) &
    (q.profile.city == "New York") &
    q.tags.contains("premium")
)

# Pattern matching with Query builder
results = users.find(
    q.email.regex("^[a-z0-9]+@example\\.com$") &
    q.name.starts_with("Jo") &
    q.domain.ends_with(".org")
)

# With sorting and pagination
q = Query(collection="users", database=db)
q.sort("age", ascending=False)
q.limit(10).skip(20)  # Page 3 with 10 items per page
results = q.execute()

Indexing

# Create single field index
db.create_index("users", "email")

# Create compound index
db.create_index("users", ["profile.city", "age"])

# Create unique index
db.create_index("users", "username", unique=True)

# Create full-text search index for efficient text searching
db.create_index("users", ["name", "bio", "tags"], full_text=True)

# Perform efficient text search using the FTS index
users.search_text("python developer")

# Search specific fields only
users.search_text("developer", fields=["bio"])

# List indexes and drop index
db.list_indexes("users")
db.drop_index("idx_users_email")
db.drop_index("fts_users_name_bio_tags")  # Drop a full-text search index

Bulk Operations and Transactions

# Get bulk operations interface
bulk_ops = users.bulk_operations()

# Use transaction for atomic operations
with bulk_ops.transaction():
    # Bulk insert
    ids = bulk_ops.bulk_insert("users", [
        {"name": "User1", "age": 31},
        {"name": "User2", "age": 32}
    ])
    
    # Bulk update
    bulk_ops.bulk_update("users", [
        {"_id": ids[0], "status": "active"},
        {"_id": ids[1], "status": "inactive"}
    ])

Migrations

from zenithdb.migrations import MigrationManager

# Initialize migration manager
manager = MigrationManager(db)

# Create migration
migration = {
    'version': '001',
    'name': 'add_users',
    'up': lambda: db.collection('users').insert({'admin': True}),
    'down': lambda: db.collection('users').delete({})
}

# Apply migration
manager.apply_migration(migration)

# Get current version
current_version = manager.get_current_version()

Backup & Restore

# Backup the database to a file
db.backup("backup_2025_02_27.db")

# Restore from a backup file
db.restore("backup_2025_02_27.db")

Advanced Aggregations

ZenithDB 2.0 includes advanced aggregation functions beyond basic COUNT, SUM, and AVG:

from zenithdb import AggregateFunction

# Calculate median age by country
median_age = users.aggregate([{
    "group": {
        "field": "profile.location.country",
        "function": AggregateFunction.MEDIAN,
        "target": "age",
        "alias": "median_age"
    }
}])

# Calculate standard deviation of salaries
salary_stddev = users.aggregate([{
    "group": {
        "field": "department",
        "function": AggregateFunction.STDDEV,
        "target": "salary",
        "alias": "salary_stddev"
    }
}])

# Count distinct values
distinct_cities = users.aggregate([{
    "group": {
        "field": "profile.location.country",
        "function": AggregateFunction.COUNT_DISTINCT,
        "target": "profile.location.city",
        "alias": "unique_cities"
    }
}])

🔍 Performance Optimization

ZenithDB includes tools for monitoring and optimizing query performance:

# Initialize with debugging for query plan analysis
db = Database("myapp.db", debug=True)

# Create appropriate indexes
db.create_index("users", ["age", "status"])

# Run query to see if indexes are used
users.find({"age": {"$gt": 25}, "status": "active"})
# Output: ✓ Using index: idx_users_age_status

🧰 Development

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/
pytest tests/test_migrations.py
pytest --cov=zenithdb tests/

🔄 Migrating from v1.x to v2.0

Version 2.0 of ZenithDB introduces several improvements with minimal breaking changes:

New Features

• Advanced Querying: New regex, starts_with, and ends_with pattern matching
• Full-Text Search: Optimized full-text search with dedicated indexes
• Advanced Aggregations: MEDIAN, STDDEV, and COUNT_DISTINCT functions
• Backup & Restore: Database backup and restore capabilities
• Extended Database Tools: More utilities for managing SQLite databases

Improvements

• Connection Management: Improved connection pooling and cleanup
• Transaction Handling: Enhanced transaction support with better error recovery
• Query Performance: Optimized indexing and query planning
• Bug Fixes: Fixed issues with nested document updates and array operations

Migration Steps

To migrate from v1.x:

• Update your installation: pip install --upgrade zenithdb
• Review and update any custom bulk operations to use the transaction context
• No database schema changes required - existing databases will work with the new version
• Consider using new features like full-text indexes to improve search performance

📋 Comparison with Other Solutions

Feature	ZenithDB	SQLite	MongoDB	TinyDB
Document Storage	✅	❌ (requires JSON)	✅	✅
Nested Queries	✅	❌ (limited)	✅	✅
Full-text Search	✅	❌ (needs extension)	✅	❌
Indexing	✅	✅	✅	❌
Transactions	✅	✅	✅	❌
Zero Dependencies	✅	✅	❌	✅
Server Required	❌	❌	✅	❌
Embedded Use	✅	✅	❌	✅

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! For feature requests, bug reports, or code contributions, please open an issue or pull request on GitHub.

For complete examples of all features, check out usage.py.

Note: ZenithDB is primarily a learning and development tool. While it's suitable for small to medium applications, it's not recommended as a production database for high-traffic or mission-critical systems.