{"id":15050558,"url":"https://github.com/superhexa/flashsql","last_synced_at":"2025-07-21T04:07:34.588Z","repository":{"id":255452672,"uuid":"852802573","full_name":"superhexa/FlashSQL","owner":"superhexa","description":"A lightweight key-value database using SQLite and APSW.","archived":false,"fork":false,"pushed_at":"2025-02-06T10:27:14.000Z","size":100,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-10T02:17:52.648Z","etag":null,"topics":["key-value","kv","kv-store","package","python","sqlite"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/superhexa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-05T13:02:09.000Z","updated_at":"2025-02-06T10:27:18.000Z","dependencies_parsed_at":"2025-02-16T09:32:28.488Z","dependency_job_id":"5b7cff2c-4944-4288-830e-a3e51874fa9c","html_url":"https://github.com/superhexa/FlashSQL","commit_stats":null,"previous_names":["superhexa/flashsql"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/superhexa/FlashSQL","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superhexa%2FFlashSQL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superhexa%2FFlashSQL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superhexa%2FFlashSQL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superhexa%2FFlashSQL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/superhexa","download_url":"https://codeload.github.com/superhexa/FlashSQL/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superhexa%2FFlashSQL/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266236896,"owners_count":23897279,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["key-value","kv","kv-store","package","python","sqlite"],"created_at":"2024-09-24T21:27:19.281Z","updated_at":"2025-07-21T04:07:34.569Z","avatar_url":"https://github.com/superhexa.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\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[![PyPI Version](https://img.shields.io/pypi/v/flashsql?label=PyPI)](https://pypi.org/project/flashsql/)\n[![Python Version](https://img.shields.io/pypi/pyversions/flashsql?label=Python)](https://pypi.org/project/flashsql/)\n[![License](https://img.shields.io/pypi/l/flashsql?label=License)](https://opensource.org/licenses/MIT)\n\n\u003c/div\u003e\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### 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# Update a value\ndb.update('new_key', 'value2')\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```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuperhexa%2Fflashsql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsuperhexa%2Fflashsql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuperhexa%2Fflashsql/lists"}