<div align="center">
# 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.
[](https://pypi.org/project/flashsql/)
[](https://pypi.org/project/flashsql/)
[](https://opensource.org/licenses/MIT)
</div>
## 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:
```bash
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.
```python
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:**
```python
db.set('name', 'hexa')
```
**With Expiration:**
```python
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.
```python
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.
```python
value = db.get('name')
print(value) # Output: 'hexa'
```
**With Expiration:**
```python
value = db.get('session')
print(value) # Output: {'user': 'hexa'} if within TTL
```
### Deleting Values
Use the `delete` method to remove a key-value pair from the database.
```python
db.delete('name')
```
### Deleting Multiple Values
Use the `delete_many` method to delete multiple key-value pairs in one batch.
```python
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.
```python
exists = db.exists('name')
print(exists) # Output: False (if the key was deleted)
```
### Renaming Keys
Use the `rename` method to rename an existing key.
```python
db.rename('old_key', 'new_key')
```
### Retrieving Expiration Date
Use the `get_expire` method to get the expiration date of a key.
```python
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.
```python
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.
```python
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.
```python
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.
```python
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.
```python
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.
```python
db.cleanup()
```
### Optimizing Database File
Use the `vacuum` method to optimize the database file and reduce its size.
```python
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).
```python
db.flush()
```
### Executing Raw SQL
Use the `execute` method to execute a raw SQL statement and return the result.
**Example:**
```python
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.
```python
db.close()
```
### Popping Values
Use the `pop` method to retrieve and remove the value associated with a key.
```python
value = db.pop('session')
print(value) # Output: {'user': 'hexa'} if within TTL and removed from the database
```
### Moving Values
Use the `move` method to move a value from one key to another.
```python
db.move('old_key', 'new_key')
```
### Updating Values
Use the `update` method to update the value of an existing key without changing its expiration.
```python
db.update('name', 'new_value')
```
## Full Example
```python
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
# Pop a value (retrieve and delete)
popped_value = db.pop('age')
print(popped_value) # Output: 30
# Move a value from one key to another
db.move('new_key', 'moved_key')
# Update a value without changing its expiration
db.update('moved_key', 'updated_value')
# Clean up expired keys
db.cleanup()
# Optimize database file
db.vacuum()
# Ensure changes are written to disk
db.flush()
# Close the database
db.close()
```
Raw data
{
"_id": null,
"home_page": "https://github.com/superhexa/FlashSQL",
"name": "FlashSQL",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "database key-value sqlite apsw peformance",
"author": "Hexa",
"author_email": "shexa.developer@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b7/71/07f7ed2d0eb7daa80094454280e412578696329b621f3d2438441eb1467e/flashsql-0.3.6.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n# FlashSQL\n\n**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.\n\n[](https://pypi.org/project/flashsql/)\n[](https://pypi.org/project/flashsql/)\n[](https://opensource.org/licenses/MIT)\n\n</div>\n\n## Features\n\n- **SQLite-based**: Utilizes SQLite for persistent storage.\n- **In-memory Option**: Supports in-memory databases for transient data.\n- **Expiration Support**: Allows setting an expiration time (TTL) for keys.\n- **Efficient Storage**: Optimized with PRAGMA settings for performance.\n- **Flexible Key Management**: Supports basic CRUD operations (Create, Read, Update, Delete) for keys.\n- **Pattern Matching**: Allows retrieval of keys based on patterns using SQL LIKE queries.\n- **Pagination**: Supports paginated retrieval of keys.\n- **Database Optimization**: Includes methods to clean up expired keys and optimize database file size.\n- **Fast Access Times**: Provides quick access to stored values with efficient querying and indexing.\n\n## Installation\n\nYou can install FlashSQL using pip:\n\n```bash\npip install FlashSQL\n```\n\n## Usage\n\n### Initialization\n\nTo initialize a new instance of FlashSQL Client, provide the file path to the SQLite database. Use `\":memory:\"` for an in-memory database.\n\n```python\nfrom FlashSQL import Client\n\n# For a file-based database\ndb = Client('database.db')\n\n# For an in-memory database\ndb = Client(':memory:')\n```\n\n### Storing Values\n\nUse 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.\n\n**Without Expiration:**\n\n```python\ndb.set('name', 'hexa')\n```\n\n**With Expiration:**\n\n```python\ndb.set('session', {'user': 'hexa'}, ttl=3600) # Expires in 1 hour\n```\n\n### Storing Multiple Values\n\nUse the `set_many` method to store multiple key-value pairs with optional expiration times in one batch.\n\n```python\nitems = {\n 'session1': ({'user': 'hexa1'}, 3600), # Expires in 1 hour\n 'session2': ({'user': 'hexa2'}, 7200), # Expires in 2 hours\n}\ndb.set_many(items)\n```\n\n### Retrieving Values\n\nUse the `get` method to retrieve the value associated with a key. If the key does not exist or has expired, `None` is returned.\n\n```python\nvalue = db.get('name')\nprint(value) # Output: 'hexa'\n```\n\n**With Expiration:**\n\n```python\nvalue = db.get('session')\nprint(value) # Output: {'user': 'hexa'} if within TTL\n```\n\n### Deleting Values\n\nUse the `delete` method to remove a key-value pair from the database.\n\n```python\ndb.delete('name')\n```\n\n### Deleting Multiple Values\n\nUse the `delete_many` method to delete multiple key-value pairs in one batch.\n\n```python\nkeys_to_delete = ['session1', 'session2']\ndb.delete_many(keys_to_delete)\n```\n\n### Checking Key Existence\n\nUse the `exists` method to check if a key is present and not expired.\n\n```python\nexists = db.exists('name')\nprint(exists) # Output: False (if the key was deleted)\n```\n\n### Renaming Keys\n\nUse the `rename` method to rename an existing key.\n\n```python\ndb.rename('old_key', 'new_key')\n```\n\n### Retrieving Expiration Date\n\nUse the `get_expire` method to get the expiration date of a key.\n\n```python\nexpire_date = db.get_expire('session')\nprint(expire_date) # Output: ISO 8601 formatted expiration date or None\n```\n\n### Setting Expiration Date\n\nUse the `set_expire` method to set a new expiration time (TTL) for an existing key.\n\n```python\ndb.set_expire('session', ttl=7200) # Expires in 2 hours\n```\n\n### Retrieving Keys\n\nUse the `keys` method to retrieve a list of keys matching a specified pattern.\n\n```python\nkeys = db.keys('%')\nprint(keys) # Output: List of all keys\n```\n\n### Pagination\n\nUse the `paginate` method to retrieve a paginated list of keys matching a pattern.\n\n```python\npaged_keys = db.paginate(pattern='key%', page=1, page_size=2)\nprint(paged_keys) # Output: List of keys for the specified page\n```\n\n### Counting Keys\n\nUse the `count` method to count the total number of keys in the database.\n\n```python\ntotal_keys = db.count()\nprint(total_keys) # Output: Total number of keys\n```\n\n### Counting Expired Keys\n\nUse the `count_expired` method to count the number of expired keys.\n\n```python\nexpired_keys_count = db.count_expired()\nprint(expired_keys_count) # Output: Number of expired keys\n```\n\n### Cleaning Up Expired Keys\n\nUse the `cleanup` method to remove expired key-value pairs from the database. This is called automatically before any retrieval or key-checking operation.\n\n```python\ndb.cleanup()\n```\n\n### Optimizing Database File\n\nUse the `vacuum` method to optimize the database file and reduce its size.\n\n```python\ndb.vacuum()\n```\n\n### Ensuring Changes Are Written to Disk\n\nUse the `flush` method to ensure all changes are written to disk by performing a full checkpoint of the WAL (Write-Ahead Log).\n\n```python\ndb.flush()\n```\n\n### Executing Raw SQL\n\nUse the `execute` method to execute a raw SQL statement and return the result.\n\n**Example:**\n\n```python\nresults = db.execute(\"SELECT key FROM FlashDB WHERE key LIKE ?\", ('key%',))\nprint(results) # Output: Results of the raw SQL query\n```\n\n### Closing the Database\n\nUse the `close` method to close the database connection.\n\n```python\ndb.close()\n```\n\n### Popping Values\n\nUse the `pop` method to retrieve and remove the value associated with a key.\n\n```python\nvalue = db.pop('session')\nprint(value) # Output: {'user': 'hexa'} if within TTL and removed from the database\n```\n\n### Moving Values\n\nUse the `move` method to move a value from one key to another.\n\n```python\ndb.move('old_key', 'new_key')\n```\n\n### Updating Values\n\nUse the `update` method to update the value of an existing key without changing its expiration.\n\n```python\ndb.update('name', 'new_value')\n```\n\n## Full Example\n\n```python\nfrom FlashSQL import Client\n\n# Initialize the database\ndb = Client(':memory:')\n\n# Store values\ndb.set('name', 'hexa', ttl=3600) # Expires in 1 hour\ndb.set('age', 30)\n\n# Store multiple values\nitems = {\n 'session1': ({'user': 'hexa1'}, 3600), # Expires in 1 hour\n 'session2': ({'user': 'hexa2'}, 7200), # Expires in 2 hours\n}\ndb.set_many(items)\n\n# Retrieve values\nprint(db.get('name')) # Output: 'hexa' if within TTL\nprint(db.get('age')) # Output: 30\n\n# Retrieve multiple values\nkeys = ['session1', 'session2']\nprint(db.get_many(keys)) # Output: {'session1': {'user': 'hexa1'}, 'session2': {'user': 'hexa2'}}\n\n# Check existence\nprint(db.exists('name')) # Output: True if within TTL\nprint(db.exists('address')) # Output: False (if the key does not exist)\n\n# Retrieve keys with a pattern\nprint(db.keys('se%')) # Output: ['session1', 'session2']\n\n# Delete a key\ndb.delete('name')\n\n# Delete multiple keys\nkeys_to_delete = ['session1', 'session2']\ndb.delete_many(keys_to_delete)\n\n# Rename a key\ndb.set('old_key', 'value')\ndb.rename('old_key', 'new_key')\n\n# Retrieve expiration date\nexpire_date = db.get_expire('new_key')\nprint(expire_date) # Output: ISO 8601 formatted expiration date or None\n\n# Set expiration date\ndb.set_expire('new_key', ttl=7200) # Expires in 2 hours\n\n# Pop a value (retrieve and delete)\npopped_value = db.pop('age')\nprint(popped_value) # Output: 30\n\n# Move a value from one key to another\ndb.move('new_key', 'moved_key')\n\n# Update a value without changing its expiration\ndb.update('moved_key', 'updated_value')\n\n# Clean up expired keys\ndb.cleanup()\n\n# Optimize database file\ndb.vacuum()\n\n# Ensure changes are written to disk\ndb.flush()\n\n# Close the database\ndb.close()\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A lightweight key-value database using SQLite and APSW.",
"version": "0.3.6",
"project_urls": {
"Documentation": "https://github.com/superhexa/FlashSQL#readme",
"Homepage": "https://github.com/superhexa/FlashSQL",
"Source": "https://github.com/superhexa/FlashSQL",
"Tracker": "https://github.com/superhexa/FlashSQL/issues"
},
"split_keywords": [
"database",
"key-value",
"sqlite",
"apsw",
"peformance"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a4e6b7c51e20357b349e18705c6305e5b9d6e61cf877d50275793f0b6488200c",
"md5": "5b28792cad3f2cc8c9ade8ede34ebe8c",
"sha256": "80bdc84f56df89266d49ffb60eee780ed0e5caaeaea43e6afde75c427b238c65"
},
"downloads": -1,
"filename": "FlashSQL-0.3.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5b28792cad3f2cc8c9ade8ede34ebe8c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 8222,
"upload_time": "2024-09-12T23:09:44",
"upload_time_iso_8601": "2024-09-12T23:09:44.418608Z",
"url": "https://files.pythonhosted.org/packages/a4/e6/b7c51e20357b349e18705c6305e5b9d6e61cf877d50275793f0b6488200c/FlashSQL-0.3.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b77107f7ed2d0eb7daa80094454280e412578696329b621f3d2438441eb1467e",
"md5": "9fe58aa1d8d191d8c92cfd422beaa496",
"sha256": "ed6c0650a7c18b38a788f9df77ada7901b08b529547cfea7c38de804b1c8f547"
},
"downloads": -1,
"filename": "flashsql-0.3.6.tar.gz",
"has_sig": false,
"md5_digest": "9fe58aa1d8d191d8c92cfd422beaa496",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 7512,
"upload_time": "2024-09-12T23:09:46",
"upload_time_iso_8601": "2024-09-12T23:09:46.006786Z",
"url": "https://files.pythonhosted.org/packages/b7/71/07f7ed2d0eb7daa80094454280e412578696329b621f3d2438441eb1467e/flashsql-0.3.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-12 23:09:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "superhexa",
"github_project": "FlashSQL",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "flashsql"
}
JSON
