PickleDB: Lightweight Python Database for Key-Value…

Introduction

PickleDB is a lightweight key-value database written in pure Python with no external servers or dependencies required. This library provides a simple solution for storing small amounts of data in JSON format, making it an ideal choice for quick prototypes, CLI utilities, configuration files, and micro-projects.

The main advantage of PickleDB is its ease of use while retaining enough functionality to handle a wide range of data storage tasks. The library supports various data types: strings, numbers, lists, dictionaries, and boolean values.

What is PickleDB and Where Is It Used?

PickleDB is a NoSQL database that stores data as key-value pairs in a JSON file. It was created as an alternative for cases where using full-fledged database systems like PostgreSQL or MySQL is overkill.

Common use cases for PickleDB include:

Storing user settings and configurations
Caching intermediate computation results
Saving authentication tokens and API keys
Maintaining simple logs and counters
Building quick prototypes with data persistence
Developing CLI applications with local storage

Installation and Initial Setup

Install PickleDB using the standard Python package manager:

pip install pickledb

Once installed, the library is ready to use with no additional configuration:

import pickledb

# Create or connect to a database
db = pickledb.load('database.db', auto_dump=True)

The auto_dump=True parameter ensures all changes are automatically saved to the file, guaranteeing data integrity even if the program terminates unexpectedly.

Architecture and How It Works

Data Storage Structure

PickleDB uses JSON as its storage format, ensuring data readability and portability across different systems. The database file is a standard JSON document with the following structure:

{
  "simple_key": "string value",
  "numeric_key": 42,
  "boolean_key": true,
  "list_key": ["item1", "item2", "item3"],
  "dict_key": {
    "nested_field": "nested value",
    "nested_number": 100
  }
}

Save Mechanism

When working with PickleDB, all data is loaded into memory when the database is initialized. Changes are applied to the in-memory object and then, depending on settings, saved to the file:

With auto_dump=True — saving occurs after every write operation
With auto_dump=False — you need to manually call the dump() method

Complete PickleDB Methods and Functions Reference

Core Data Methods

Method	Description	Example Usage
`set(key, value)`	Saves a value by key	`db.set('name', 'John')`
`get(key)`	Retrieves a value by key	`name = db.get('name')`
`exists(key)`	Checks if a key exists	`if db.exists('name'):`
`rem(key)`	Deletes a key and its value	`db.rem('name')`
`getall()`	Returns all keys	`keys = db.getall()`
`totalkeys()`	Returns the total number of keys	`count = db.totalkeys`