Build a Simple NoSQL Database in Python – Hands‑On Tutorial

In recent years the term NoSQL has become ubiquitous, but what does it actually mean and why is it useful? This article answers those questions by implementing a tiny NoSQL database in pure Python, which we refer to as "lightly structured pseudo‑code".

OldSQL

SQL (Structured Query Language) is a language for retrieving data from relational database management systems (RDBMS) such as MySQL, MS SQL Server, and Oracle. In an RDBMS, data is organized into tables composed of rows and columns, and the table schema defines the data types of each column. For example, a Car table might have columns Make (string), Model (string), Year (integer), Color (string), and VIN (string) which serves as the primary key.

Querying

SQL queries retrieve information by expressing a structured request. For instance, to list all makes and models you would run:

SELECT Make, Model FROM Car;

To get the colors of cars registered in 1994:

SELECT Color FROM Car WHERE Year = 1994;

And to fetch a specific car by VIN:

SELECT * FROM Car WHERE VIN = '2134AFGER245267';

Relations

When tracking service history for cars, you would normally duplicate the vehicle information in each ServiceHistory row. A better design separates the immutable vehicle data into a Vehicle table and stores only service‑specific fields in ServiceHistory, linking the two tables via the VIN primary key.

Indexes

Without indexes a query must perform a full table scan, which is the slowest operation. Adding an index to a column (e.g., Price) allows the database to locate matching rows quickly, at the cost of extra memory for the index structure.

The Clear Box

A database can inspect a table’s schema, enabling advanced features such as indexes. When dealing with NoSQL databases, remember that the lack of a fixed schema makes query capabilities a crucial consideration.

Schemas

A schema describes column names, data types, nullability, uniqueness, and other constraints. Changing a schema (e.g., adding an Age column) requires careful planning and often a rollback strategy.

Key/Value Stores

Before NoSQL, key/value stores like memcached provided schema‑less storage using hash tables, similar to Python’s dict. Our simple NoSQL server will use a Python dictionary as the primary data store, supporting string keys and values of type integer, string, or list.

Commands Supported

PUT – parameters: Key, Value – insert a new entry.

GET – parameters: Key – retrieve a stored value.

PUTLIST – parameters: Key, Value – insert a list.

APPEND – parameters: Key, Value – append an element to an existing list.

INCREMENT – parameter: key – increment an integer value.

DELETE – parameter: key – delete an entry.

STATS – no parameters – return command execution statistics.

Message Structure

Request messages follow the format: COMMAND; [KEY]; [VALUE]; [VALUE TYPE] Examples:

PUT; foo; 1; INT

GET; foo;;

PUTLIST; bar; a,b,c ; LIST

APPEND; bar; d; STRING

STATS; ;;

Set Up

The server uses the standard library socket module to listen on a TCP/IP port. The core data store is a global dictionary DATA. Below is a condensed excerpt of the server code (full source on GitHub):

import socket
HOST = 'localhost'
PORT = 50505
SOCKET = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
STATS = {'PUT': {'success': 0, 'error': 0}, ...}
DATA = {}

def main():
    SOCKET.bind((HOST, PORT))
    SOCKET.listen(1)
    while True:
        connection, address = SOCKET.accept()
        data = connection.recv(4096).decode()
        command, key, value, value_type = parse_message(data)
        if command == 'STATS':
            response = handle_stats()
        elif command in ('GET', 'GETLIST', 'INCREMENT', 'DELETE'):
            response = COMMAND_HANDLERS[command](key)
        elif command in ('PUT', 'PUTLIST', 'APPEND'):
            response = COMMAND_HANDLERS[command](key, value)
        else:
            response = (False, f'Unknown command type {command}')
        connection.sendall(f"{response[0]}; {response[1]}".encode())
        connection.close()

Command Parser

The parse_message function splits the incoming string on semicolons, strips whitespace, and casts the value to the appropriate type (list, int, or string).

Command Handlers

Each handler returns a tuple (success, message). For example, handle_put stores the value in DATA[key] and returns a success message; handle_get checks for key existence and returns the stored value or an error.

How Is This a Database?

Although this implementation lacks persistence and advanced indexing, it demonstrates the essential operations of a NoSQL key/value store: simple schema‑less storage, basic CRUD commands, and a minimal protocol over TCP.

Querying Data

Storing a car record as a list (e.g., ['Lexus', 'RX350', 2013, 'Black']) loses column semantics, making queries like "find all 1994 cars" cumbersome because the server must scan every entry and interpret list positions.

Real‑world NoSQL systems mitigate this by using structured formats such as JSON and namespaces, allowing richer queries while preserving flexibility.

Summary

We have clarified the meaning of NoSQL, reviewed basic SQL concepts, built a toy NoSQL server in Python, and discussed the trade‑offs between queryability and simplicity. Even a simple key/value store introduces many database concepts that scale to more sophisticated systems.