This article will cover a guide on installing and using the “TinyDB” module that can be used to create and manage databases in JSON file format. Available as a third party module for Python programs, TinyDB is written in pure Python and it comes with many useful functions that can be used to query and modify database files. It doesn’t support SQL style queries but uses its own pythonic API for searching database files. TinyDB doesn’t require you to create a database server and everything can be directly accessed through files stored on a storage device without need of a server connection. Apart from documents or dictionary type Python objects, it also supports tables so that you can store data in multiple tables and keep each table independent of others.
Installing TinyDB in Linux
TinyDB is available in official Ubuntu repositories, so you can install it from the package manager using the following command:
You can install TinyDB in other Linux distributions from the package manager. An alternative method to install TinyDB in Ubuntu and other Linux distributions is to use the “pip” package manager.
You can install pip package manager in Ubuntu using the following command:
You can search for the pip package manager in official repositories of your Linux distribution and install it from there. You can also install pip package manager by following official installation instructions available here. Once pip package manager is installed on your Linux system, use the following command to install TinyDB module:
Basic Syntax and Usage
To create a new JSON database file supported by TinyDB, use the following Python statements:
db = TinyDB('db.json')
print (db)
The first statement imports the main TinyDB module so that its methods can be used in a Python program. Next, a new instance of TinyDB class is created by supplying a “.json” file as the main argument. This statement will create a new database or load an existing JSON database created by TinyDB.
After running the above code sample, you should get the following output:
Since a fresh database has been created, there are currently no documents or data tables in the database. To insert a new document (Python dictionary) in the table, use the following code:
db = TinyDB('db.json')
db.insert({'name': 'John', 'rank': 2})
db.insert({'name': 'Peter', 'rank': 1})
print (db)
The “insert” method can be used to insert documents or dictionaries in the database. You need to supply a dictionary as an argument with your required key-value pair. After running the above code sample, you should get the following output:
As you can see in the output, the database now contains two documents, assigned to the “_default” table. If you open the “db.json” file in a text editor, it should look like this:
To assign a document to a specific table you will need to create a new table first. You can create a new table by calling the “table” method. Here is a code sample:
db = TinyDB('db.json')
db.insert({'name': 'John', 'rank': 2})
db.insert({'name': 'Peter', 'rank': 1})
table = db.table('fruits')
table.insert({'apples': 50})
print (db)
As you can see in the code sample, the “table” method has been called to create a new table that will be stored in the database. You just need to supply a name for it as an argument. Once a new table is created, the rest of the procedure is the same. Instead of calling the “insert” method on the default database, you now call the insert method on the freshly created table.
After running the above code sample you should get the following output:
The database now contains two tables. If you open the database in a text editor, you should see new table added to the database:
Note that all the methods that can be called on the default database can be used with tables as well.
Querying Documents in the Database
To search documents in the database, you will need to import the “Query” class from the TinyDB module and use the “search” method. Here is a code sample:
db = TinyDB('db.json')
db.insert({'name': 'John', 'rank': 2})
db.insert({'name': 'Peter', 'rank': 1})
q = Query()
result = db.search(q.name == 'John')
print (result)
A new instance of the “Query” class is created and then a search method is called on the database. Using dot notation, you can select a document key or field and add your required search term on the right hand side. After running the above code sample, you should get the following output:
If there are no matches, an empty list will be returned. You can call the search method on a manually created table as well.
db = TinyDB('db.json')
db.insert({'name': 'John', 'rank': 2})
db.insert({'name': 'Peter', 'rank': 1})
table = db.table('fruits')
table.insert({'apples': 50})
q = Query()
result = table.search(q.apples < 100)
print (result)
The code sample shows usage of search method on a specific table. Notice in the code that a different comparison operator (‘<‘ sign) has been used to query the database. After running the above code sample, you should get the following output:
Updating and Removing Documents
To update an existing document in the database, you need to use the “update” method. Here is a code sample:
db = TinyDB('db.json')
db.insert({'name': 'John', 'rank': 2})
db.insert({'name': 'Peter', 'rank': 1})
q = Query()
db.update({'rank': 3}, q.name == 'John')
print (db.all())
Using the Query class explained above, you can update the value of an existing field in the database. Pass the value to be modified as the first argument to the update method and then pass the query as the second argument. The “all” method can be used to fetch all documents available in the database. After running the above code sample, you should get the following output where rank of “John” has been updated to 3 from 2:
To remove a document, you will need to use the “remove” method and the query syntax explained above. Here is a code sample:
db = TinyDB('db.json')
db.insert({'name': 'John', 'rank': 2})
db.insert({'name': 'Peter', 'rank': 1})
q = Query()
db.remove(q.name == 'John')
print (db.all())
You need to pass a query to the remove method so that associated documents can be matched and removed from the database. After running the above code sample, you should get the following output:
Conclusion
TinyDB provides numerous convenience and helper functions to create and manage JSON based databases. While you can handle JSON files using the “json” module in Python, TinyDB is much more than that and includes a comprehensive query system that can be used to fetch results quickly with simple one liner statements.
