TinyStore for Python

A small storage runtime for applications. SQL, key-value state, durable jobs, files, metrics and logs in one directory, with one lifecycle, one memory budget and one backup.

Release candidates first. Until v0.1.0, the API may still change, and a file written by one release may not open in the next.

The SDK starts a small tinystore server next to your program, called the sidecar, and talks to it over a local connection. The server binary comes with the wheel, so there is nothing else to install. Go programs embed the same engines, and every client of one directory sees the same data.

import asyncio
import logging
from pathlib import Path

import tinystore


async def main() -> None:
    async with tinystore.open("./data") as store:
        db = await store.sql(
            "app", migrations={"0001_users.sql": "create table users (id integer primary key, name text)"}
        )
        await db.exec("insert into users (id, name) values (?, ?)", 42, "Ada")

        sessions = store.kv.bucket("sessions", str, sliding="30d")
        await sessions.of("42").set("token", "abc123")

        emails = store.jobs.queue("emails", dict[str, str])
        await emails.enqueue({"to": "ada@example.com"})

        files = store.blobs.bucket("files")
        await files.put("avatars/42.png", Path("avatar.png").read_bytes())

        logging.getLogger().addHandler(store.records.handler("api"))
        logging.info("user created", extra={"user_id": 42})

        store.metrics.counter("signups_total").inc()


asyncio.run(main())

pip install tinyshed-tinystore

It needs Python 3.12 or later and runs on asyncio. The package installs as tinyshed-tinystore and imports as tinystore.

Engines

Three ways to connect

async with tinystore.open("./data") as store:  # the directory's sidecar, shared with other processes
    ...
async with tinystore.open("./data", private=True) as store:  # a server for this process alone, for tests and scripts
    ...
async with tinystore.connect("tls://db.internal:7070", token=token) as store:
    ...

The sidecar and A remote server explain each one.

The command line

The wheel also installs the tinystore command. It shows what a store contains and follows its logs while your program runs. uvx runs it without installing anything:

uvx --from tinyshed-tinystore tinystore status ./data                          # each engine's size, and who serves the directory
tinystore logs ./data -f                                                       # the application's logs, as they arrive
claude mcp add tinystore -- uvx --from tinyshed-tinystore tinystore mcp ./data # read-only access for an AI agent

See The command line for every command.

Documentation

• Getting started: install it and write a first program
• A tour: every engine on one page
• The guides: a page per feature, each example in Bun, Python and Go
• Python API: every call, by engine

License

Apache-2.0.