Managing data on embedded and IoT devices presents a unique challenge. Computational resources, memory, and flash storage on boards like the Raspberry Pi are limited. In this context, using traditional databases, often designed for powerful servers, can lead to slowdowns, excessive resource consumption, and even premature wear of the storage medium. This is where tools like Colibri, a lightweight and persistent key-value database, become indispensable. It offers an optimized solution for these architectures, ensuring reliability and performance without overloading the system.
Colibri is a key-value database written in Python, ideal for projects on Raspberry Pi and other embedded systems. Its architecture is designed to be minimal, offering data persistence with a reduced memory footprint and a simple, intuitive API, similar to a Python dictionary. This makes it perfect for scenarios where lightness and fast data access are priorities, such as sensor applications, local logging, or configuration caching on edge devices.
Tested on: Raspberry Pi 4 (Raspberry Pi OS Bookworm) · Python 3.11.2 · September 2026
Prerequisites / Test Environment
To follow this guide, you will need:
- A Raspberry Pi (any model with Python 3 installed).
- Python 3.x (preferably 3.8 or higher).
- Access to a shell on the Raspberry Pi.
Ensure your system is up to date:
sudo apt update && sudo apt upgrade -yInstall Colibri-db using pip:
pip install colibri-db1. Introduction to Colibri
Colibri stands out for its simplicity and lightness. It is not a full relational database or a complex NoSQL solution; it’s a key-value implementation that acts like a persistent dictionary. This means you can associate a value with a key and retrieve it at any time, even after a system reboot. Its architecture is optimized to minimize I/O operations, a crucial aspect for extending the lifespan of SD cards, which are notoriously sensitive to continuous writes.
Architecture and Benefits
The core of Colibri is a compact binary file that stores data. Unlike SQLite, which is a relational database, Colibri focuses solely on key-value pairs, eliminating the overhead of schemas and complex queries. This translates to:
- Lower RAM and CPU consumption: Ideal for Raspberry Pi with 1GB or 2GB of RAM.
- Speed: Fast data access and modification.
- Simplicity: The API is almost identical to a standard Python dictionary, reducing the learning curve.
- Persistence: Data is saved to disk and remains available upon program or system restart.
2. Basic Operations with Colibri
Using Colibri is extremely straightforward. Let’s create a small Python script to explore its main functionalities.
Create a file colibri_test.py:
from colibri_db import ColibriDB
# 1. Initialize the database
# The database will be created if it doesn't exist, otherwise it will be opened.
db = ColibriDB('sensor_data.db')
print("--- Write Operations ---")
# 2. Write data (like a dictionary)
db['temperature'] = 25.5
db['humidity'] = 60.2
db['timestamp'] = '2026-09-13 10:30:00'
db['sensor_id'] = 'RPi_001'
# You can also save nested dictionaries or lists
db['recent_readings'] = [{'temp': 25.0, 'hum': 59.8}, {'temp': 25.1, 'hum': 60.0}]
print(f"Data saved: {list(db.keys())}")
# 3. Read data
print("\n--- Read Operations ---")
print(f"Temperature: {db['temperature']} °C")
print(f"Humidity: {db['humidity']} %")
print(f"Recent Readings: {db['recent_readings']}")
# 4. Check for key existence
if 'pressure' in db:
print(f"Pressure: {db['pressure']} hPa")
else:
print("Key 'pressure' not found.")
# 5. Delete data
del db['humidity']
print(f"\nKey 'humidity' deleted. New keys: {list(db.keys())}")
# 6. Iterate over keys (and values)
print("\n--- Iterating Over Data ---")
for key, value in db.items():
print(f"Key: {key}, Value: {value}")
# 7. Close the database (optional, automatically done on exit)
# It's good practice to explicitly close the db if no longer needed to free up resources.
db.close()
print("\nDatabase closed.")
# Reopen the database to verify persistence
db_reopen = ColibriDB('sensor_data.db')
print("\n--- Persistence Verification ---")
print(f"Temperature after reopening: {db_reopen['temperature']} °C")
db_reopen.close()Execute the script:
python colibri_test.pyRead also: Proxmox VE: Complete Installation & Configuration Guide 2026
3. Managing Multiple Databases and Advanced Scenarios
Colibri supports creating multiple databases, each with its own file. This is useful for logically separating data or managing different applications on the same Raspberry Pi.
from colibri_db import ColibriDB
db_config = ColibriDB('config.db')
db_logs = ColibriDB('logs.db')
db_config['wifi_ssid'] = 'MyHomeNetwork'
db_config['wifi_pass'] = 'SecurePassword123'
db_logs['event_001'] = 'System started'
db_logs['event_002'] = 'Sensor reading completed'
print(f"WiFi Configuration: {db_config['wifi_ssid']}")
print(f"Latest Log: {db_logs['event_002']}")
db_config.close()
db_logs.close()Custom Serialization
By default, Colibri uses pickle for data serialization. If you have specific needs or require greater compatibility with other languages, you can specify a different serializer, such as JSON, although this requires a bit more manual work for converting Python objects. Read also: JSON in Python: Practical Guide for Parsing and Generation
Common Errors and Troubleshooting
-
KeyError: This occurs when you try to access a key that does not exist in the database. Always check for a key’s existence withif 'key' in db:before accessing it. - Write Permissions: Ensure that the user running the Python script has write permissions in the directory where you are trying to create or open the
.dbfile. If you run asrootand then as a normal user, you might encounter permission issues. - Database Corruption: While Colibri is robust, sudden power outages or bugs in your code that directly manipulate the
.dbfile can corrupt it. Implement regular backups, especially in production environments.
FAQ — Frequently Asked Questions
Is Colibri suitable for large amounts of data?
No, Colibri is designed to be lightweight for manageable data loads on embedded devices. For databases with millions of records or complex queries, solutions like SQLite or more structured NoSQL databases would be more appropriate. Its strength lies in simplicity and efficiency for small to medium data quantities.
Can I access the Colibri database from multiple processes simultaneously?
Colibri is not designed for concurrent access from multiple processes or threads without explicit application-level lock management. If you need multi-process access, consider solutions that implement database-level locking mechanisms, such as SQLite.
How do I back up a Colibri database?
Since Colibri stores all data in a single .db file, backing it up is as simple as copying that file to another location. You can use shutil.copyfile() in Python or the cp command from the shell. Read also: Linux Performance Monitoring: 8 Essential Tools Compared
Is Colibri secure for sensitive data?
By default, Colibri does not implement data encryption. If you need to store sensitive information, it is your responsibility to encrypt the data before saving it and decrypt it after retrieval. You can use Python libraries like cryptography for this purpose.
Are there alternatives to Colibri for Raspberry Pi?
Yes, several. Common alternatives include SQLite (for relational data), TinyDB (another lightweight NoSQL database in Python), or simply saving data to JSON or CSV files. The choice depends on your project’s specific needs regarding data structure, performance, and persistence requirements.
Conclusions with Operational Takeaways
Colibri positions itself as an excellent choice for developers and system administrators working with Raspberry Pi and other edge devices. Its key-value nature and native Python integration make it extremely versatile for a variety of IoT applications. The key to its success lies in simplicity: less complexity means fewer bugs, less resource consumption, and greater reliability in critical environments.
If your project requires a lightweight, persistent, and easy-to-use database to manage small to medium amounts of data on limited hardware, Colibri is definitely worth evaluating. It allows you to focus on your application logic, without the overhead of a traditional database.
Sources
Updated: September 2026
