upstream(tinydb): document ids are stringified before reaching storages #136

Tracks upstream friction in TinyDB. The explanation lives in the docs; this issue is the unit of work.

Explanation: Document ids are stringified before reaching storages — the limitation, why it matters to an ODM, the workaround tinydantic carries, and the change that would remove it. That section is written to be read standalone by an upstream maintainer, so it doubles as the ready-to-send proposal if we ever file this.

Reproduction

Upstream only — no tinydantic import.

from tinydb import TinyDB
from tinydb.storages import MemoryStorage


class Peek(MemoryStorage):
    def write(self, data):
        ids = list(data["_default"])
        print("storage sees ids:", ids)
        print("sorted:         ", sorted(ids))
        super().write(data)


db = TinyDB(storage=Peek)
db.insert_multiple([{"n": n} for n in range(1, 11)])

Run with python repro.py.

Actual output:

storage sees ids: ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10']
sorted:          ['1', '10', '2', '3', '4', '5', '6', '7', '8', '9']

The storage never sees the native int ids — Table._update_table() has already converted them to strings for JSONStorage's benefit. Any storage that sorts its keys therefore orders documents lexicographically, which is what makes human-readable output confusing.

Expected: stringification is JSONStorage's concern, or storages can opt into native id keys — either way a storage receives the ids TinyDB actually uses.

Environment: TinyDB 4.9.0, Python 3.10.20, macOS. Run 2026-08-13.

What tinydantic carries today

SortIntDocIDsMiddleware (src/tinydantic/tinydb/middlewares.py), which exists purely to undo the stringification for human-readable YAML/JSON output. It has to pass ints where the Storage protocol declares strings — an acknowledged hack.

Upstream status

Not filed here. Upstream discussion exists at msiemens/tinydb#466.

What would close this

Letting storages opt into native int id keys, or moving the stringification into JSONStorage so key formatting is a storage concern — or a maintainer decision to carry the workaround indefinitely.

Assisted-by: Claude:claude-opus-5