Skip to content


The TinyDBRepository is the implementation of the repository pattern for the local NoSQL TinyDB database. You can use it in the early stages of the project where the data schema is yet unstable and you don't have enough entities to have performance issues.

It stores the persisted Entities into a json file.

Load it with:

from repository_orm import load_repository

repo = load_repository('tinydb://path/to/database.db')


Follow the overview example to see how to use each method.

Appends the Entity object to the default table by translating its attributes to a valid json row. If it already exists, it uses the upsert statement to update it's attributes in the table.
Deletes the Entity object from the collection by searching the row that matches the object ID.
Obtain an Entity by extracting the row that matches the ID and build the Entity object with that data.
Persist the changes into the database.
Obtain all the entities of type Entity. Similar to the get method but for all entities.
Obtain the entities whose attributes match one or multiple conditions. We create a query with all the desired criteria and then build the entities with the obtained data.
We don't yet support migrations on the schema, so the models should be flexible enough to absorb the changes, or you can code your migrations in your program, or even better, help us solve #27.

Internal workings

This section is meant for the people that you to expand the functionality of the TinyDBRepository. It explains how it works under the hood.

Once the object is initialized with the database url with the format tinydb:///path_to_database_file, an TinyDB object is created in the db_ attribute, the path to the database is saved in database_file and a empty dictionary of staged changes is created in staged.

Saving entities

All entities are saved in the same default table _default, to avoid id_ collision, before storing the objects, an model_type_ attribute is appended with the lowercase name of the entity class. When retrieving objects with get and all, the attribute is deleted.


TinyDB doesn't have the concept of transactions, the tinyrecord plugin does, but you need to run everything in the same context manager, which doesn't suit our case. So whenever we add or remove an entity from the repository, they are stored in the staged attribute, and once commit is called, they are persisted into the database.


Last update: 2022-08-12