PyLiteDB

PyLiteDB is a small, lightweight database engine written in Python. It stores data as JSON-like records. You can store, update, get, and delete records in tables. It also supports optional encryption to keep your data safe.

Features:

• Create tables and store JSON-like data

• Insert, update, delete, and fetch records by ID

• Get all records from a table

• Filter records using a key and value

• Optional AES-GCM encryption with SHA3-based keys

• A salt file (.salt) is used to help with encryption and decryption

• Write-Ahead Logging (WAL) for crash-safe operations

• Metadata stored in .meta.json files

• Includes an easy-to-use CLI mode for managing databases

Installation / Setup:

Ensure that Python 3.9 or newer is installed on your system.

1. Go to your project folder:

cd /path/to/your/project

2. Clone the PyLiteDB folder inside your project:

git clone https://github.com/s-r-e-e-r-a-j/PyLiteDB.git

3. Install the dependency for encryption:

pip3 install cryptography

Usage Example

from PyLiteDB import Database

# Create/open database with optional passphrase
db = Database("test.db", "mypassword")  # passphrase optional

# Create a table
db.create_table("users")

# Insert records
uid1 = db.insert("users", {"name": "Sreeraj", "age": 21})
uid2 = db.insert("users", {"name": "Sreereshmi", "age": 17})
uid3 = db.insert("users", {"name": "Alex", "age": 25})

# Fetch a record by ID
print("Single record:", db.get("users", uid1))

# Update a record (change name or other fields)
db.update("users", uid1, {"name": "Sreekuttan", "role": "developer"})

# Delete a record
db.delete("users", uid2)

# Fetch all records
print("All records:", db.find_all("users"))

# 🔍 Filter records by key/value
print("Filtered (name='Alex'):", db.find_by_filter("users", "name", "Alex"))

# Commit changes
db.commit()

File Structure:

test.db           # Stores the main database data
test.meta.json    # Stores table metadata
test.db.wal       # Write-Ahead Log for crash recovery
test.salt         # Stores the cryptographic salt used for encryption

Usage(CLI Mode)

You can start the interactive PyLiteDB shell using:

python3 -m PyLiteDB.cli

This command will open the PyLiteDB shell with a new or existing database named pylitedb.db (unencrypted by default).

If you want to use a specific database file with encryption enabled, provide a passphrase:

python3 -m PyLiteDB.cli mydatabase.db mysecret

If the database file (mydatabase.db) does not exist, it will be created automatically.

If the file already exists, the same passphrase used during creation must be provided to access it.

If no passphrase is provided, the database will operate in unencrypted mode.

Once started, you’ll see the prompt:

pylite>

Supported CLI Commands

Command	Description
CREATE TABLE <name>	Create a new table in the database.
INSERT INTO <table> VALUES <json>	Insert a JSON-formatted record into the specified table.
SELECT * FROM <table>	Display all records from the specified table.
UPDATE <table> <row_id> <json>	Update the record with the given row ID in the specified table.
DELETE <table> <row_id>	Delete the record with the given row ID from the specified table.
FILTER <table> <key>=<value>	Display records where the given key matches the specified value.
EXIT or QUIT	Exit the PyLiteDB interactive shell.

Example Session

pylite> CREATE TABLE users
Created table 'users'
pylite> INSERT INTO users VALUES{"name":"sreeraj","age":21}
Inserted row ID: c75ad045fbd449be9591ddab93fe204a
pylite> SELECT * FROM users
{'name': 'sreeraj', 'age': 21}
pylite> UPDATE users c75ad045fbd449be9591ddab93fe204a {"name":"sreereshmi","age":17}
Updated successfully
pylite> SELECT * FROM users
{'name': 'sreereshmi', 'age': 17}
pylite> UPDATE users c75ad045fbd449be9591ddab93fe204a {"name":"sreeraj","age":21,"role":"developer"}
Updated successfully
pylite> SELECT * FROM users
{'name': 'sreeraj', 'age': 21, 'role': 'developer'}
pylite> FILTER users name=sreeraj
{'name': 'sreeraj', 'age': 21, 'role': 'developer'}
pylite> DELETE users c75ad045fbd449be9591ddab93fe204a
Deleted successfully
pylite> SELECT * FROM users
pylite> EXIT

Using the CLI Programmatically (Inside a Python Script)

You can also run the PyLiteDB CLI directly from a Python file by importing it:

from PyLiteDB.cli import main

# Example 1: Run with the default database (unencrypted)
main([])

# Example 2: Run with a specific database file (unencrypted)
main(["mydatabase.db"])

# Example 3: Run with encryption using a passphrase
main(["mydatabase.db", "mysecret"])

This is useful when you want to embed the interactive PyLiteDB shell inside another Python-based project or provide a scripted interface for database management.

Notes:

• Always use the Database API; do not edit .db, .meta.json or .salt manually.

• Encryption works only if you provide a passphrase.

License

This project is licensed under the MIT License