FlashSQL 0.3.4

A lightweight key-value database using SQLite and APSW.

FlashSQL

FlashSQL is a high-performance key-value store built on SQLite with support for optional expiration. It offers a simple and efficient interface for storing, retrieving, and managing key-value pairs with additional features like pagination and database optimization.

Features

• SQLite-based: Utilizes SQLite for persistent storage.
• In-memory Option: Supports in-memory databases for transient data.
• Expiration Support: Allows setting an expiration time (TTL) for keys.
• Efficient Storage: Optimized with PRAGMA settings for performance.
• Flexible Key Management: Supports basic CRUD operations (Create, Read, Update, Delete) for keys.
• Pattern Matching: Allows retrieval of keys based on patterns using SQL LIKE queries.
• Pagination: Supports paginated retrieval of keys.
• Database Optimization: Includes methods to clean up expired keys and optimize database file size.
• Fast Access Times: Provides quick access to stored values with efficient querying and indexing.

Installation

You can install FlashSQL using pip:

pip install FlashSQL

Usage

Initialization

To initialize a new instance of FlashSQL Client, provide the file path to the SQLite database. Use ":memory:" for an in-memory database.

from FlashSQL import Client

# For a file-based database
db = Client('database.db')

# For an in-memory database
db = Client(':memory:')

Storing Values

Use the set method to store a value under a specific key. You can specify an expiration time (TTL) in seconds or leave it out for no expiration.

Without Expiration:

db.set('name', 'hexa')

With Expiration:

db.set('session', {'user': 'hexa'}, ttl=3600)  # Expires in 1 hour

Storing Multiple Values

Use the set_many method to store multiple key-value pairs with optional expiration times in one batch.

items = {
    'session1': ({'user': 'hexa1'}, 3600),  # Expires in 1 hour
    'session2': ({'user': 'hexa2'}, 7200),  # Expires in 2 hours
}
db.set_many(items)

Retrieving Values

Use the get method to retrieve the value associated with a key. If the key does not exist or has expired, None is returned.

Without Expiration:

value = db.get('name')
print(value)  # Output: 'hexa'

With Expiration:

value = db.get('session')
print(value)  # Output: {'user': 'hexa'} if within TTL

Retrieving Multiple Values

Use the get_many method to retrieve values for multiple keys in one batch.

keys = ['session1', 'session2']
values = db.get_many(keys)
print(values)  # Output: {'session1': {'user': 'hexa1'}, 'session2': {'user': 'hexa2'}}

Deleting Values

Use the delete method to remove a key-value pair from the database.

db.delete('name')

Deleting Multiple Values

Use the delete_many method to delete multiple key-value pairs in one batch.

keys_to_delete = ['session1', 'session2']
db.delete_many(keys_to_delete)

Checking Key Existence

Use the exists method to check if a key is present and not expired.

Without Expiration:

exists = db.exists('name')
print(exists)  # Output: False (if the key was deleted)

With Expiration:

exists = db.exists('session')
print(exists)  # Output: True if within TTL, False otherwise

Renaming Keys

Use the rename method to rename an existing key.

db.rename('old_key', 'new_key')

Retrieving Expiration Date

Use the get_expire method to get the expiration date of a key.

expire_date = db.get_expire('session')
print(expire_date)  # Output: ISO 8601 formatted expiration date or None

Setting Expiration Date

Use the set_expire method to set a new expiration time (TTL) for an existing key.

Without TTL:

db.set('session', {'user': 'hexa'})

With TTL:

db.set_expire('session', ttl=7200)  # Expires in 2 hours

Retrieving Keys

Use the keys method to retrieve a list of keys matching a specified pattern.

Example:

keys = db.keys('%')
print(keys)  # Output: List of all keys

Pagination

Use the paginate method to retrieve a paginated list of keys matching a pattern.

Example:

paged_keys = db.paginate(pattern='key%', page=1, page_size=2)
print(paged_keys)  # Output: List of keys for the specified page

Counting Keys

Use the count method to count the total number of keys in the database.

total_keys = db.count()
print(total_keys)  # Output: Total number of keys

Counting Expired Keys

Use the count_expired method to count the number of expired keys.

expired_keys_count = db.count_expired()
print(expired_keys_count)  # Output: Number of expired keys

Cleaning Up Expired Keys

Use the cleanup method to remove expired key-value pairs from the database. This is called automatically before any retrieval or key-checking operation.

db.cleanup()

Optimizing Database File

Use the vacuum method to optimize the database file and reduce its size.

db.vacuum()

Ensuring Changes Are Written to Disk

Use the flush method to ensure all changes are written to disk by performing a full checkpoint of the WAL (Write-Ahead Log).

db.flush()

Executing Raw SQL

Use the execute method to execute a raw SQL statement and return the result.

Example:

results = db.execute("SELECT key FROM FlashDB WHERE key LIKE ?", ('key%',))
print(results)  # Output: Results of the raw SQL query

Closing the Database

Use the close method to close the database connection.

db.close()

Full Example

from FlashSQL import Client

# Initialize the database
db = Client(':memory:')

# Store values
db.set('name', 'hexa', ttl=3600)  # Expires in 1 hour
db.set('age', 30)

# Store multiple values
items = {
    'session1': ({'user': 'hexa1'}, 3600),  # Expires in 1 hour
    'session2': ({'user': 'hexa2'}, 7200),  # Expires in 2 hours
}
db.set_many(items)

# Retrieve values
print(db.get('name'))  # Output: 'hexa' if within TTL
print(db.get('age'))   # Output: 30

# Retrieve multiple values
keys = ['session1', 'session2']
print(db.get_many(keys))  # Output: {'session1': {'user': 'hexa1'}, 'session2': {'user': 'hexa2'}}

# Check existence
print(db.exists('name'))  # Output: True if within TTL
print(db.exists('address'))  # Output: False (if the key does not exist)

# Retrieve keys with a pattern
print(db.keys('se%'))  # Output: ['session1', 'session2']

# Delete a key
db.delete('name')

# Delete multiple keys
keys_to_delete = ['session1', 'session2']
db.delete_many(keys_to_delete)

# Rename a key
db.set('old_key', 'value')
db.rename('old_key', 'new_key')

# Retrieve expiration date
expire_date = db.get_expire('new_key')
print(expire_date)  # Output: ISO 8601 formatted expiration date or None

# Set expiration date
db.set_expire('new_key', ttl=7200)  # Expires in 2 hours

# Clean up expired keys
db.cleanup()

# Optimize database file
db.vacuum()

# Ensure changes are written to disk
db.flush()

# Execute raw SQL
results = db.execute("SELECT key FROM FlashDB WHERE key LIKE ?", ('key%',))
print(results)  # Output: Results of the raw SQL query

# Close the database
db.close()

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please submit pull requests or open issues to improve the functionality and performance of FlashSQL.