Database Module

The Database module provides various database implementations for data persistence, including filesystem, Redis, and SQLite storage options.

Filesystem Storage

File system-based database storage module.

This module provides a persistent storage implementation using the file system, with support for atomic operations and hierarchical key storage.

Classes:

FileSystemStorage: Main class implementing file system-based storage functionality.

Functions:

None (all functionality is encapsulated in classes)

Types:

None

Exceptions:

StorageError: See true_storage.exceptions.StorageError KeyError: Raised when accessing non-existent keys

Key Features:

• Persistent file system storage

• Atomic write operations

• Hierarchical key structure

• Thread-safe operations

• Temporary directory support

• Key prefix filtering

• Automatic directory management

• Secure path validation

class true_storage.database.filesystem.FileSystemStorage(base_dir=None)

Bases: BaseStorage

File system-based storage implementation.

__init__(base_dir=None)

Initialize the file system storage.

Parameters:

base_dir (Optional[str]) – Base directory for storage. If None, uses a temporary directory.

_get_path(key)

Get a full path for a key.

Parameters:

key (str) – Storage key, can include directory separators.

Return type:

Path

Returns:

Path object for the key.

clone()

Create a copy of the storage instance.

Return type:

BaseStorage

store(key, value)

Store a value with the given key.

Parameters:

• key (str) – Storage key

• value (Any) – Value to store

Return type:

None

retrieve(key)

Retrieve a value by key.

Parameters:

key (str) – Storage key

Return type:

Any

Returns:

Stored value

Raises:

• KeyError – If key doesn’t exist

• StorageError – If retrieval fails

delete(key)

Delete a value by key.

Parameters:

key (str) – Storage key

Return type:

None

clear()

Clear all stored values.

Return type:

None

exists(key)

Check if a key exists.

Parameters:

key (str) – Storage key

Return type:

bool

Returns:

True if key exists, False otherwise

list_keys(prefix='')

List all keys with given prefix.

Parameters:

prefix (str) – Key prefix to filter by

Return type:

list[str]

Returns:

List of matching keys

Redis Storage

Redis-based storage implementation.

class true_storage.database.redis_store.RedisStorage(host='localhost', port=6379, db=0, prefix='checkpoint:')

Bases: BaseStorage

Redis-based storage implementation.

__init__(host='localhost', port=6379, db=0, prefix='checkpoint:')

_get_key(key)

Get prefixed key for Redis.

Return type:

str

store(key, value)

Store a value with the given key.

Return type:

None

retrieve(key)

Retrieve a value by key.

Return type:

Any

delete(key)

Delete a value by key.

Return type:

None

clear()

Clear all stored values.

Return type:

None

clone()

Create a copy of the storage instance.

Return type:

RedisStorage

SQLite Storage

SQLite-based database storage module.

This module provides a persistent storage implementation using SQLite, offering ACID-compliant transactions and efficient data storage.

Classes:

SQLiteStorage: Main class implementing SQLite-based storage functionality.

Functions:

None (all functionality is encapsulated in classes)

Types:

None

Exceptions:

StorageError: See true_storage.exceptions.StorageError KeyError: Raised when accessing non-existent keys

Key Features:

• ACID-compliant transactions

• Thread-safe operations

• In-memory or file-based storage

• Binary data support

• Automatic connection management

• Connection pooling

• Resource cleanup

• SQL-based querying capabilities

class true_storage.database.sqlite.SQLiteStorage(db_path=None)

Bases: BaseStorage

SQLite-based storage implementation.

__init__(db_path=None)

Initialize SQLite storage.

Parameters:

db_path (Optional[str]) – Path to SQLite database file. If None, uses in-memory database.

_get_connection()

Get a SQLite connection, creating it if needed.

_init_db()

Initialize the database schema.

store(key, value)

Store a value in the database.

Return type:

None

retrieve(key)

Retrieve a value from the database.

Return type:

Any

delete(key)

Delete a value from the database.

Return type:

None

clear()

Clear all values from the database.

Return type:

None

close()

Close the database connection.

clone()

Create a copy of the storage instance.

Return type:

BaseStorage

__del__()

Ensure connection is closed on deletion.