Coffy: The Swiss Army Knife of Embedded Python Databases

Sometimes you just need a simple, embedded database for your Python project. You don't want the overhead of a full client-server system, but you also don't want to be locked into a single data model. What if you could query your data with SQL one day, traverse it as a graph the next, and access it as a simple document store whenever you felt like it? That's the intriguing promise of Coffy.

It's an open-source, lightweight embedded database engine written in pure Python. In a world of specialized tools, Coffy tries to be a generalist, giving you multiple ways to interact with your data without leaving the comfort of your Python runtime.

What It Does

Coffy is a local, file-based database engine that supports three core data models through a unified interface:

• NoSQL/Document Store: Store and retrieve Python dict-like objects.
• SQL: Run SQL queries (with some limitations) over your tabular data.
• Graph: Model your data as nodes and edges and perform graph traversals.

All of this happens without an external server. Your database is just a file (or files) on disk, making it incredibly portable and easy to integrate.

Why It's Cool

The cool factor here is the polyglot approach. Most embedded databases force you to choose a lane: you pick SQLite for relational data, TinyDB for documents, or something like NetworkX for in-memory graphs. Coffy attempts to unify these concepts.

Need a quick configuration store? Use it as a key-value store. Building a feature that requires complex joins? Switch to SQL mode. Suddenly realize your data has inherent relationships? Traverse it as a graph without migrating to a new system.

It's built in pure Python, which means zero dependencies and no compilation steps—just pip install and go. This makes it an excellent candidate for prototypes, embedded systems, desktop applications, or any situation where simplicity and flexibility are more critical than massive scale.

How to Try It

Getting started is straightforward. Install it from PyPI:

pip install coffy-db

Here's a quick taste of using its different personalities:

import coffy

# Create a database (it's just a directory)
db = coffy.Database('my_data')

# 1. NoSQL style: Work with a 'collection' of documents
users = db.collection('users')
users.insert({'name': 'Alice', 'level': 5})
print(users.find_one({'level': 5}))

# 2. SQL style: Query a collection as a table
result = db.sql.query("SELECT name FROM users WHERE level > 3")
for row in result:
    print(row['name'])

# 3. Graph style: Link records and traverse
alice = users.get(1)  # get record by ID
bob = users.insert({'name': 'Bob', 'level': 3})
db.graph.link(alice, bob, relation='knows')

for path in db.graph.traverse(alice, max_depth=2):
    print(path)

Check out the GitHub repository for more detailed examples and the API reference.

Final Thoughts

Coffy feels like a bold experiment in database design. It's probably not the tool you'd choose for a high-traffic web service, but it shines as an embedded engine for tools, applications, and prototyping. The ability to pivot between data models as your understanding of the problem evolves is a powerful concept.

If you're building a desktop app, a CLI tool that needs persistent state, or just want a simple way to play with different query paradigms, Coffy is definitely worth a look. It's the kind of project that makes you think, "Huh, why can't a database work like this?"

Follow us for more interesting projects: @githubprojects