Get Ready to Explore TinyDB

TinyDB is a standalone library, meaning it doesn’t rely on any other libraries to work. You’ll need to install it, though.

You’ll also use thepprint module to formatdictionary documents for easier reading, and Python’scsv module to work withCSV files. You don’t need to install either of these because they’re included in Python’sstandard library.

So to follow along, you only need to install the TinyDB library in your environment. First,create and activate a virtual environment, then install the library usingpip:

(venv)$python-mpipinstalltinydb

Alternatively, you could set up a smallpyproject.toml file andmanage your dependencies usinguv.

When you add documents to your database, you often do so manually by creating Python dictionaries. In this tutorial, you’ll do this, and also learn how to work with documents already stored in aJSON file. You’ll even learn how to add documents from data stored in a CSV file.

These files will be highlighted as needed and are available in this tutorial’s downloads. You might want to download them to your program folder before you start to keep them handy:

Regardless of the files you use or the documents you create manually, they all rely on the same world population data. Each document will contain up to six fields, which become the dictionary keys used when the associated values are added to your database:

As mentioned earlier, the four primary database operations areCreate,Read,Update, andDelete—collectively known as theCRUD operations. In the next section, you’ll learn how you can perform each of them.

To begin with, you’ll explore theC in CRUD. It’s time to get creative.

Create Your Database and Documents

The first thing you’ll do iscreate a new database and add some documents to it. To do this, you create aTinyDB()object that includes the name of a JSON file to store your data. Any documents you add to the database are then saved in that file.

Documents in TinyDB are stored in tables. Although it’s not necessary to create a table manually, doing so can help you organize your documents, especially when working with multiple tables.

To start, you create a script namedcreate_db.py that initializes your first database and adds documents in several different ways. The first part of your script looks like this:

 1fromcsvimportDictReader 2 3fromtinydbimportTinyDB 4 5withTinyDB("countries.json",indent=4)ascountries_db: 6countries_table=countries_db.table(name="countries")

YouimportDictReader from Python’s built-incsv module. This allows you to read a CSV file and parse its header row and data rows into a Pythondictionary. You also import theTinyDBclass to enable you to create a database.

Then you create a database and a table. To create the database, you make aTinyDBinstance in line 6 of your code. To do this, you provide the name of the file,countries.json, where the database will store its documents, and an optionalindent parameter of4. When you save your data, it’s stored as JSON. By passingindent=4, the JSON file will be indented within the file, making it more readable.

In line 6, you create the database and reference it using thecountries_db variable. You do this within acontext manager. This means your database remains open while the indented code below thewith keyword runs and then automatically closes afterward. Had you not used the context manager, you’d need to callcountries_db.close() to close the database manually.

You then create the table in line 7 of your code using the.table()method of your database. In this example, you’ve chosencountries as the table’s name andcountries_table as its reference variable. At this point, you have your database with one empty table.

Next, you’ll investigate three ways to add documents. First up is how to add a single document:

 8countries_table.insert( 9{"location":"Vatican City","population":501}10)

Starting at line 8, you use the.insert() method to insert a single document intocountries_table. Documents are formed from Python dictionaries. In this case, you create a document containing two fields:location andpopulation, along with their associated values. Now, suppose you want to add multiple documents at once:

12countries_table.insert_multiple(13[14{"location":"India","population":1_417_492_000},15{"location":"China","population":1_408_280_000},16]17)

You can add multiple documents by passing aPython list of them to your table’s.insert_multiple() method. In this case, your list contains two dictionaries, each representing a separate document. As before, each document contains bothlocation andpopulation information.

Sometimes, you may need to add a larger number of documents. For example, you might want to create documents from a file of data extracted from another system. While this feature isn’t supported natively by TinyDB, you can use your existing Python skills to read this file into your database.

In this example, you add the three documents stored in yourcountries_file.csv file:

location,population,continentArgentina,45929925,South AmericaSwitzerland,8990428,EuropeMozambique,36147236,Africa

Thecountries_file.csv file’s first row defines thelocation,population, andcontinent fields, which will form the dictionary keys, while the three additional rows define the values. Notice that thecontinent field wasn’t included in the previous documents you added. This is fine because documents in a document-oriented database don’t all need to have the same fields.

To add these documents to your database, you convert them into Python dictionary format and insert them as before. You continue your script as follows:

19withopen("countries_file.csv","r")ascsv_source:20reader=DictReader(csv_source)2122forrowinreader:23row["population"]=int(row["population"])24countries_table.insert(row)

In line 19, you use anothercontext manager, this time to opencountries_file.csv for reading. You then pass the file, which you refer to ascsv_source, to a newDictReader() object namedreader. TheDictReader() parses the information in each row of yourcountries_file.csv file into a series of Python dictionaries, with keys from the first row and values from the remaining rows.

YourDictReader(), in line 20, is aniterable, meaning that it can be used in afor loop. You use thefor loop in line 22 to read each of the dictionaries from yourDictReader(), and then pass them into your database table using the.insert() method as before. Just before you do so, you cast thepopulation values to integers sinceDictReader reads them as strings.

With your database creation script now complete, all you need to do to create your database isrun the script:

(venv)$pythoncreate_db.py

If you want to quickly check that all of the added documents are present in your database, along with their ID values, feel free to open thecountries.json file and take a look. There should be six documents stored in it.

Now that you know how to create databases and add documents, it’s time to move on to theR in CRUD and learn how to read documents from your database.

Read Documents From Your Database

Once your documents are safely stored in the database, you’ll likely want toread some or all of them. To do this, you construct a query. As you’ll see in this section, you can query your database in several different ways.

You’ll use theten_countries.json file available in your downloadables. It contains population details for the ten countries with the largest populations at the time of writing. Each document includes five of the fields explained in the table at the start of this tutorial. If you’d like to open the file in your favorite JSON or text editor, you’ll see its content.

To search for specific documents in your database, you need both aQuery instance to define the information you need and a reference to theTable instance to search.

To allow you to write various ad hoc queries, you decide to use thePython REPL as follows:

>>>frompprintimportpprint>>>fromtinydbimportQuery,TinyDB>>>countries_db=TinyDB("ten_countries.json")>>>countries_table=countries_db.table(name="countries")

Your first step is to set up a database with the existing documents fromten_countries.json. You importTinyDB, but this time also theQuery class. You’ll use this to define what you’re looking for. You also importpprint to format query results.

You then create a database that contains the existing documents. To do this, you use the same syntax you used previously when you created a new database, but this time you reference an existing file. This opens the database and populates it with existing data.

This time, because you’ve opened the database outside of a context manager, you’ll need to remember to close it manually after you’ve finished with it. You again create a reference to an existing table using the same approach as before. In this example, you usecountries_db.table() and specify the existingcountries table name.

Next, you write a query to view some documents. Suppose you wanted to see the details of those documents withpopulation field values between 220 million and 250 million:

>>>query=Query()>>>query_def=(query.population>220_000_000)&(...query.population<250_000_000...)

You call theQuery() constructor and assign the new object to thequery variable. Then, you use it to construct aquery definition that specifies the information you want to extract from your database. The object thatquery references contains a set of instance attributes that mirror the fields in the table you’re querying, or more precisely, match the keys of the dictionary it’ll query.

Since you want to see documents withpopulation values between 220 million and 250 million, you define the query as(query.population > 220_000_000) & (query.population < 250_000_000). In this case, you’ve used the.populationattribute to query against this field. To make sure both clauses are included, you use the bitwise& operator, as well as the> and< comparison operators.

With the query defined, run it to see the documents. To do this, you pass your query definition,query_def, into the table’s.search() method. This will run your query. To display the results neatly, you use thepprint()function:

>>>pprint(countries_table.search(query_def))[{'% of world': 2.9,  'date': '1 Mar 2023',  'location': 'Pakistan',  'population': 241499431,  'source': '2023 Census result'}, {'% of world': 2.7,  'date': '1 Jul 2023',  'location': 'Nigeria',  'population': 223800000,  'source': 'Official projection'}]

As you can see, two documents match your criteria and are neatly displayed.

Now, suppose you want to see documents whose share of the global population is at least 17%. You might try to construct another query definition based on the% of world field. However,% of world can’t form an instance attribute of your query because it’s an invalid variable name. This would only produce a syntax error instead of the results you want.

Fortunately, there’s another way. You can use dictionary notation to reference a field instead:

>>>pprint(countries_table.search(query["% of world"]>=17))[{'% of world': 17.3,  'date': '1 Jul 2025',  'location': 'India',  'population': 1417492000,  'source': 'Official projection'}, {'% of world': 17.2,  'date': '31 Dec 2024',  'location': 'China',  'population': 1408280000,  'source': 'Official estimate'}]

This time, you use Python dictionary notation ([]) to reference a field in your query. Thepprint() function prints the search results on screen.

You’ve already seen that each document in a TinyDB database gets assigned a unique identifier within its table. The first document added is assigned ID1, the second2, and so on. To read a document from a table by its identifier value, you can use the table’s.get() method.

Here, you decide to look at the documents whose IDs are9 and10, so you pass these values as a Python list to.get() using itsdoc_ids parameter. Had you wanted to see a single document, you’d have passed its ID using the singularly nameddoc_id parameter:

>>>pprint(countries_table.get(doc_ids=[9,10]))[{'% of world': 1.8,  'date': '1 Jan 2025',  'location': 'Russia',  'population': 146028325,  'source': '???'}, {'% of world': 1.6,  'date': '30 Jun 2025',  'location': 'Mexico',  'population': 0,  'source': '???'}]

As you can see, two documents have been returned. If you look carefully, you’ll notice something wrong with thesource fields in each, and Mexico appears to be devoid of people. Don’t worry, you’ll fix these in the next section.

You’ve finished with this database, so to ensure all documents are safely saved, you must close it. You need to close the database manually because you didn’t use a context manager when you opened it:

>>>countries_db.close()

Now that you know how to find documents, next you’ll learn about theU in CRUD. It’s time to learn how to update documents.

Update Documents in Your Database

Sometimes, the documents in your database become outdated or contain errors. To fix this, you need toupdate them. In this section, you’ll use the.update() and.update_multiple() methods on yourTable to make changes to some existing documents.

As you’ve seen, it seems no one lives in Mexico, and the source of this information is unclear. After conducting some research, you find that the most recent national quarterly estimate reports that Mexico has a population of 130,575,786. You decide to update your database to reflect this corrected information. Because you have multiple changes to make, you again decide to create a script.

As before, you create the references to the existing database table:

 1fromtinydbimportTinyDB,where 2 3withTinyDB("ten_countries.json")ascountries_db: 4countries_table=countries_db.table(name="countries")

To begin, you import the libraries you’ll need, this time including thewhere() function. You’ll usewhere() to find the documents you want to update and, again, to verify that your updates have worked. Because you choose to usewhere(), there’s no need to importQuery.

As before, you open theten_countries.json file as a TinyDB instance and set thecountries_table variable to reference thecountries table.

Now that you can access the database, you can update it:

 6countries_table.update( 7{"population":130_575_786},where("location")=="Mexico" 8) 910countries_table.update(11{"source":"National quarterly update"},12where("location")=="Mexico",13)

To update theMexico document, you pass twoarguments to the.update() method ofcountries_table. First, you pass a dictionary representing the part of the document you want to update, and second, you passwhere("location") == "Mexico" to reference the document to update.

You then use the same technique to update thesource field of the same document. To apply the updates, run the script:

(venv)$pythonupdate_db.py

Finally, to make sure the updates have worked as you expect, you run a quick query in theREPL:

>>>frompprintimportpprint>>>fromtinydbimportTinyDB,where>>>withTinyDB("ten_countries.json")ascountries_db:...countries_table=countries_db.table(name="countries")...pprint(countries_table.search(where("location")=="Mexico"))[{'% of world': 1.6,  'date': '30 Jun 2025',  'location': 'Mexico',  'population': 130575786,  'source': 'National quarterly update'}]

As you can see, the updates were successful!

Earlier, you saw how.insert_multiple() allows you to perform multiple inserts. You can update multiple documents at the same time with.update_multiple(). The previous code could also have been written like this:

fromtinydbimportTinyDB,wherewithTinyDB("ten_countries.json")ascountries_db:countries_table=countries_db.table(name="countries")countries_table.update_multiple([({"population":130_575_786},where("location")=="Mexico",),({"source":"National quarterly update"},where("location")=="Mexico",),])

This time, instead of passing in the dictionary and document information into.update() twice, you pass them in as a list ofPython tuples to.update_multiple(). This code applies the same updates as before.

In the previous example, only theMexico document was updated. This is because there was only one document with thatlocation value. Had there been more, you’d have updated them as well.

Suppose you now want to update a single document, but one that can’t be uniquely identified by a field. The solution is to update specific documents based on their document ID values.

If you look at theten_countries.json file, you’ll see that thesource fields of documents7 and9 contain no meaningful information. Perhaps you want to update those fields to show that the populations are official estimates. The code below shows you how:

fromtinydbimportTinyDBwithTinyDB("ten_countries.json")ascountries_db:countries_table=countries_db.table(name="countries")countries_table.update({"source":"Official estimate"},doc_ids=[7,9])

To update documents by their unique document IDs, you again use.update(). As before, you pass in the update as a dictionary, but instead of identifying the document to be updated by a potentially duplicate field value, you use thedoc_ids parameter and assign it a list of the document IDs you want to update.

As with the.get() method you used earlier, you can also usedoc_id with.update() to update a single document. This is useful when documents can’t be uniquely identified by a field name.

Go ahead and run this code, then use the techniques you learned earlier to verify that the updates work as expected.

Finally, you’ll move on to theD in CRUD. It’s time to learn how to clear out unwantedcrud by deleting documents and tables from your database.

Delete Documents From Your Database

There may be times when you no longer need some documents in your database. To keep file size small and search performance efficient, it’s a good idea todelete any obsolete documents. In this section, you’ll learn how to remove unwanted documents using the.remove() and.truncate() table methods. You’ll also learn how to remove entire tables using the database’s.drop_table() and.drop_tables() methods.

Suppose you decide that you no longer need the documents with ID values of3,5, and7 stored inten_countries.json.

To begin with, your database still contains all ten documents. You can verify this by passing a table reference to the Pythonlen() function:

>>>fromtinydbimportTinyDB,where>>>countries_db=TinyDB("ten_countries.json")>>>countries_table=countries_db.table(name="countries")>>>len(countries_table)10

Sincelen(countries_table) returns10, you’ve confirmed that ten documents are indeed present.

To remove documents, use the.remove() method ofcountries_table. You do this by passing a Python list of document IDs you want to remove to itsdoc_ids parameter:

>>>countries_table.remove(doc_ids=[3,5,7])[3, 5, 7]>>>len(countries_table)7

You can see from the returned list[3, 5, 7] that these three documents have been removed, leaving seven remaining. Your second call tolen() again confirms this.

Sometimes, you might want to remove a group of documents from your database based on their data. For example, suppose you want to remove documents with apopulation of fewer than 300 million. To do this, you once more use the.remove() method:

>>>countries_table.remove(where("population")<300_000_000)[4, 6, 8, 9, 10]>>>len(countries_table)2

To specify the documents to be removed, you decide to use thewhere() function to identify documents whosepopulation field value meets a condition. You passwhere("population") < 300_000_000 into the.remove() method ofcountries_table to remove them. Now only two documents remain.

Feel free to write a query to find out what they are, or take a look directly at the now poorly namedten_countries.json file to see what’s left.

Suppose you want to remove all documents from thecountries table. You could do this by editing theten_countries.json file directly, but it’s probably cleaner to do it using code:

>>>countries_table.truncate()>>>len(countries_table)0

To remove all documents from a table in your database, you call.truncate() oncountries_table. This will remove all documents, but not the table itself. This means you can add more documents to it if you want. As you can see, thelen() function tells you there are no documents left. Feel free to look inside yourten_countries.json file, and you’ll see what an empty table looks like.

To delete the table, whether it’s empty or not, you can use the.drop_table() method on yourcountries_db database and pass in the table name:

>>>countries_db.tables(){'countries'}>>>countries_db.drop_table(name="countries")>>>countries_db.tables()

Before you drop a table, you decide to check to make sure you know its correct name. To do this, you call the.tables() method on your database. This returns aPython set containing the tables. In this case, there’s only one namedcountries.

To remove this table, you call.drop_table() on your database and pass itname="countries".

Finally, you check to see the updated list of tables. This time, an emptyset object was returned, indicating the database is now empty. If you check the JSON file, and yes, it still exists, you’ll see a somewhat boring empty pair of curly braces. You can now delete it if you wish.

Although TinyDB is an extremely useful tool, it’s important to be aware of its limitations to round off your learning experience.

Understand Limitations and Gotchas

Although TinyDB is lightweight and straightforward to use, its simplicity does come at a cost:

• Non-relational: It doesn’t provide full relational functionality or referential integrity, so if you want to link documents across multiple tables, you’ll need to write Python code to do so.
• Querying: TinyDB lacks projection capabilities. You’ve already seen a few of the techniques available to return entire documents. However, if you want to return partial documents—such as a list of values from a specific field—you need to write Python code to do this manually.
• Transactions: TinyDB doesn’t provideACID guarantees because it’s not designed for use in distributed or multi-user environments. For example, it doesn’t support multithreading orconcurrency, so it’s not suitable for multi-user web applications.
• Storage: Its default storage is JSON, so only JSON-serializable data types are supported. However, programmers can write extensions to support other storage formats such asYAML.

Also, make sure that the field names you use follow Python variable naming conventions to avoid limiting the options available to you when querying.

Conclusion

TinyDB provides a NoSQL, document-oriented database that supports the four CRUD operations found in larger database systems, but without their complex setup or configuration requirements. It’s written entirely in Python and requires no additional dependencies, which makes it easy to embed directly into your Python projects. With TinyDB, you can quickly persist documents in JSON format, query them, and update them through a clean, Pythonic API.

In this tutorial, you’ve learned how to:

• Create a database and tables for storing documents, and add documents to your database
• Write queries toview documents based on different criteria using multiple techniques
• Update single and multiple documents in your database
• Delete documents and tables from your database
• Understand theadvantages andlimitations of TinyDB

If TinyDB has grabbed your attention, then itsofficial documentation will show you even more of its capabilities. Happy databasing!

Frequently Asked Questions

Now that you’ve gained some experience with TinyDB in Python, you can use the questions and answers below to check your understanding and recap what you’ve learned.

These FAQs are related to the most important concepts you’ve covered in this tutorial. Click theShow/Hide toggle beside each question to reveal the answer.

Take the Quiz: Test your knowledge with our interactive “TinyDB: A Lightweight JSON Database for Small Projects” quiz. You’ll receive a score upon completion to help you track your learning progress:

---

Interactive Quiz

TinyDB: A Lightweight JSON Database for Small Projects

If you're looking for a JSON document-oriented database that requires no configuration for your Python project, TinyDB could be what you need.