ScoloDB

ScoloDB is an async-first SQLite key-value store for bots and small Python services. It stores JSON-compatible values locally, uses SQLite WAL mode, supports TTL, atomic counters, and transactions, and requires no database server.

Installation

pip install ScoloDB

Quick start

import asyncio
from scolodb import ScoloDB

async def main() -> None:
    async with ScoloDB('bot.sqlite3') as db:
        await db.set('users', '42', {'language': 'ru'})
        user = await db.get('users', '42')
        print(user['language'])

asyncio.run(main())

A namespace is required for every key. It keeps unrelated data separate without requiring multiple database files.

TTL cache

await db.set('cache', 'weather:moscow', {'temperature': 18}, ttl=300)
weather = await db.get('cache', 'weather:moscow')

Expired values behave as missing and are removed during reads, scans, or purge_expired().

Atomic counters

messages = await db.increment('metrics', 'messages')

increment() is serialised through the database lock, so concurrent asyncio tasks cannot lose updates.

Transactions

async with db.transaction() as transaction:
    await transaction.set('order', '42:status', 'paid')
    await transaction.set('order', '42:receipt_sent', True)

An exception inside the block rolls back every write from that transaction.

Logging

ScoloDB depends on ScoloLogger for optional structured operation events. It never configures logging automatically. Applications that need diagnostics can configure ScoloLogger themselves:

from scolologger import configure

configure(level='DEBUG')

Stored values and keys are not placed in log events.

Limits

ScoloDB 0.1.0 targets one process and a local SQLite file. It is not a replacement for PostgreSQL, Redis, or a distributed database. Values must be JSON-compatible.

License

MIT.