# IgnisDB: A Teaching Database Built on Python asyncio, Not a Production Store

> IgnisDB is a single-threaded, in-memory key-value store written in Python's asyncio, aimed at developers who want to learn how databases work. It offers RESP-like protocol, snapshots, AOF, transactions, and replication, but it is a learning project, not a deployment target.

**buraksocial/IgnisDB** — An asynchronous, single-threaded, in-memory Key-Value store built on Python's asyncio event loop. Implements a non-blocking TCP server and a RESP-like protocol.

- Repository: https://github.com/buraksocial/IgnisDB
- Stars: 53 · Forks: 4
- Language: Python
- License: MIT
- Published: 2026-08-21 · Updated: 2026-08-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/buraksocial-ignisdb

## What IgnisDB Actually Solves

IgnisDB is not a product. The README is explicit: it is a hands-on guide to building a database from scratch using Python and asyncio. The problem it addresses is educational. Developers who use Redis or Memcached every day often have no idea what happens inside a TCP server or how a persistence file is written. IgnisDB gives them a small, readable codebase that demonstrates those mechanics. It is for the developer who wants to learn network programming, asyncio's event loop, and data structures by building rather than by reading documentation. The project does not claim to be fast or production-ready. Its goal is to demystify how a key-value store works, one component at a time.

## The Architecture: Three Pieces and a Lock

The README describes a clean separation of concerns. A TCP server listens for connections and spawns a dedicated task per client, so no client blocks another. The protocol parser translates raw bytes into commands like GET my_key. The storage engine executes those commands on in-memory data structures. The response is formatted back through the parser and sent over the wire. The storage engine uses an asyncio.Lock to serialize write operations, enforcing a one-at-a-time rule. That lock is the core concurrency mechanism. Because the server is single-threaded, the lock does not protect against multi-threaded races; it protects against interleaving between coroutines. This is a key point for readers: asyncio gives concurrency without parallelism, and the lock is there to keep the event loop sane, not to enable multi-core scaling.

## Starting the Server and Talking to It

Getting IgnisDB running takes three commands. Clone the repository, optionally create a virtual environment, and run python main.py. The README notes that no external libraries are needed, only Python 3.9 or newer. To start on a different port, for example when running a replica, use python main.py --port 6381. To interact with the server, open a second terminal and connect with telnet 127.0.0.1 6381. That gives you a direct line to the server, where you can type commands. The README does not list the exact commands beyond GET, but it mentions support for Strings, Lists, and Hashes, plus MULTI and EXEC for transactions. If you want to test replication, you would start a second instance on another port, but the README does not explain how to wire replicas to a master. That gap is worth noting before you try.

## Persistence: Snapshots and Append-Only File

IgnisDB implements two persistence strategies, both described in the README. Snapshotting periodically saves a full copy of the data to a file, like taking a photograph. The Append-Only File (AOF) logs every write command, giving finer-grained durability. The trade-off is standard: snapshots are cheap to write but lose changes made after the last snapshot, while AOF can replay every command but grows large. The README does not specify how to configure the snapshot interval or whether AOF is on by default. It also does not say how recovery works on startup. Those details matter if you plan to use the project beyond a tutorial. Without them, you cannot know whether a crash mid-write corrupts the AOF or whether the snapshot is atomic. The code may be clear, but the documentation leaves those questions open.

## Transactions and Replication: Promises Without Depth

The feature list includes atomic transactions via MULTI and EXEC, and master-slave replication. The README explains that MULTI and EXEC group commands into an all-or-nothing operation, which is a useful teaching point. Replication is described as a master handling writes and propagating them to read-only slaves. That is a common pattern, but the README does not specify the replication protocol, whether it is asynchronous or synchronous, or how a slave handles a disconnection. For a learning project, these details may be left as exercises. For a user evaluating the project, the lack of documentation on replication is a limitation. You can run a second server on port 6381, but you will not find instructions on how to make it a replica. That is a gap between the feature list and the practical guide.

## Key Limitations: Single Thread, In-Memory, No Recovery Docs

The most obvious limitation is that IgnisDB is single-threaded and in-memory. All data lives in RAM, so a restart loses everything unless a snapshot or AOF file is loaded. The README does not describe the load-on-startup behavior, so you cannot assume data survives a restart. The single-threaded design also caps throughput. asyncio handles many connections, but all work happens on one event loop, so CPU-bound operations will block everything. The project is not designed for high write concurrency or large datasets. It is also not a drop-in replacement for Redis, because the protocol is RESP-like, not full RESP. Clients that speak real RESP may not work without changes. These are not flaws in a teaching tool, but they are deal-breakers for production use.

## Alternative: Redis vs. IgnisDB

The obvious alternative to IgnisDB is Redis. Redis is a multi-threaded, in-memory store with a full RESP protocol, built-in persistence (RDB snapshots and AOF), replication, and a mature ecosystem. Redis is written in C, so it is far faster than any Python implementation. The difference in approach is fundamental: Redis is a production system optimized for performance and reliability, while IgnisDB is a Python codebase optimized for readability and learning. If you need a key-value store for a real application, Redis is the right choice. If you want to understand how such a store works, reading IgnisDB's code is easier than reading Redis's C source. The trade-off is between speed and clarity. IgnisDB trades everything for clarity, and that is fine as long as you know what you are getting.

## Maintenance and License: What You Need to Know

IgnisDB is licensed under the MIT License, which permits free use, modification, and distribution, with attribution. The README does not mention a contribution guide or a release history, and no recent releases were retrieved. The repository is not archived, but there is no evidence of active maintenance. That means you should expect to maintain it yourself if you adopt it. The code is small enough that a motivated developer could fix bugs, but there is no promise of upstream support. The lack of a documented upgrade path is another concern. If you build on IgnisDB, you are on your own. The MIT license gives you freedom, but that freedom comes with responsibility. For a learning project, this is acceptable. For a dependency, it is a risk.

## Conclusion

Adopt IgnisDB if you are a developer who wants to understand network servers, asyncio, and persistence by reading and modifying a small codebase. Do not use it for production workloads, because it is single-threaded, in-memory, and lacks the maturity of established stores. Before relying on it, verify that the replication and AOF recovery paths handle crashes correctly, since the README does not document failure modes. If you need a production key-value store, choose Redis or Memcached instead. IgnisDB is a teaching tool, and its value is in the code you read, not the service you run.

## FAQ

### What is IgnisDB in this repository?

It is an asynchronous, single-threaded, in-memory key-value store built on Python's asyncio event loop, with a non-blocking TCP server and a RESP-like protocol. The README frames it as a hands-on guide to building a database from scratch rather than as a product.

### How do I run IgnisDB?

Clone the repository, optionally create and activate a virtual environment, then run `python main.py`, or `python main.py --port 6381` for a different port such as a replica's. Talk to it from another terminal with `telnet 127.0.0.1 6381`.

### What data types and persistence modes does IgnisDB support?

Strings, lists and hashes, all held in memory. Persistence comes in two modes: snapshotting, which periodically writes all the data to a file, and an append-only file that logs every write command for finer-grained durability. Atomic transactions are available through MULTI and EXEC.

### How does IgnisDB stay safe under concurrent requests?

Each client connection gets its own task from the TCP server, and write operations are serialised with an asyncio.Lock so two requests for the same item cannot collide. Reads scale through master-slave replication, where the master propagates writes to read-only replicas.

## Sources

- [Official README](https://github.com/buraksocial/IgnisDB#readme)
- [Project repository](https://github.com/buraksocial/IgnisDB)
- [README](https://github.com/buraksocial/IgnisDB/blob/main/README.md)
- [Releases](https://github.com/buraksocial/IgnisDB/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/buraksocial-ignisdb