# kiarina-lib-falkordb
A Python client library for [FalkorDB](https://falkordb.com/) with configuration management and connection pooling.
## Features
- **Configuration Management**: Use `pydantic-settings-manager` for flexible configuration
- **Connection Pooling**: Automatic connection caching and reuse
- **Retry Support**: Built-in retry mechanism for connection failures
- **Sync & Async**: Support for both synchronous and asynchronous operations
- **Type Safety**: Full type hints and Pydantic validation
## Installation
```bash
pip install kiarina-lib-falkordb
```
## Quick Start
### Basic Usage (Sync)
```python
from kiarina.lib.falkordb import get_falkordb
# Get a FalkorDB client with default settings
db = get_falkordb()
# Select a graph and run a query
graph = db.select_graph("social")
result = graph.query("CREATE (p:Person {name: 'Alice', age: 30}) RETURN p")
print(result.result_set)
```
### Async Usage
```python
from kiarina.lib.falkordb.asyncio import get_falkordb
async def main():
# Get an async FalkorDB client
db = get_falkordb()
# Select a graph and run a query
graph = db.select_graph("social")
result = await graph.query("CREATE (p:Person {name: 'Bob', age: 25}) RETURN p")
print(result.result_set)
```
## Configuration
This library uses [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) for flexible configuration management.
### Environment Variables
Configure the FalkorDB connection using environment variables:
```bash
# FalkorDB connection URL
export KIARINA_LIB_FALKORDB_URL="falkor://localhost:6379"
# Enable retry mechanism
export KIARINA_LIB_FALKORDB_USE_RETRY="true"
# Timeout settings
export KIARINA_LIB_FALKORDB_SOCKET_TIMEOUT="6.0"
export KIARINA_LIB_FALKORDB_SOCKET_CONNECT_TIMEOUT="3.0"
# Retry settings
export KIARINA_LIB_FALKORDB_RETRY_ATTEMPTS="3"
export KIARINA_LIB_FALKORDB_RETRY_DELAY="1.0"
```
### Programmatic Configuration
```python
from kiarina.lib.falkordb import settings_manager
# Configure for multiple environments
settings_manager.user_config = {
"development": {
"url": "falkor://localhost:6379",
"use_retry": True,
"retry_attempts": 3
},
"production": {
"url": "falkor://prod-server:6379",
"use_retry": True,
"retry_attempts": 5,
"socket_timeout": 10.0
}
}
# Switch to production configuration
settings_manager.active_key = "production"
db = get_falkordb()
```
### Runtime Overrides
```python
from kiarina.lib.falkordb import get_falkordb
# Override settings at runtime
db = get_falkordb(
url="falkor://custom-server:6379",
use_retry=True
)
```
## Advanced Usage
### Connection Caching
```python
from kiarina.lib.falkordb import get_falkordb
# These will return the same cached connection
db1 = get_falkordb()
db2 = get_falkordb()
assert db1 is db2
# Use different cache keys for separate connections
db3 = get_falkordb(cache_key="secondary")
assert db1 is not db3
```
### Custom Configuration Keys
```python
from kiarina.lib.falkordb import settings_manager, get_falkordb
# Configure multiple named configurations
settings_manager.user_config = {
"analytics": {
"url": "falkor://analytics-db:6379",
"socket_timeout": 30.0
},
"cache": {
"url": "falkor://cache-db:6379",
"socket_timeout": 5.0
}
}
# Use specific configurations
analytics_db = get_falkordb("analytics")
cache_db = get_falkordb("cache")
```
### Error Handling and Retries
```python
from kiarina.lib.falkordb import get_falkordb
# Enable automatic retries for connection issues
db = get_falkordb(use_retry=True)
try:
graph = db.select_graph("mydata")
result = graph.query("MATCH (n) RETURN count(n)")
except Exception as e:
print(f"Query failed: {e}")
```
## Configuration Reference
| Setting | Environment Variable | Default | Description |
|---------|---------------------|---------|-------------|
| `url` | `KIARINA_LIB_FALKORDB_URL` | `"falkor://localhost:6379"` | FalkorDB connection URL |
| `use_retry` | `KIARINA_LIB_FALKORDB_USE_RETRY` | `false` | Enable automatic retries |
| `socket_timeout` | `KIARINA_LIB_FALKORDB_SOCKET_TIMEOUT` | `6.0` | Socket timeout in seconds |
| `socket_connect_timeout` | `KIARINA_LIB_FALKORDB_SOCKET_CONNECT_TIMEOUT` | `3.0` | Connection timeout in seconds |
| `health_check_interval` | `KIARINA_LIB_FALKORDB_HEALTH_CHECK_INTERVAL` | `60` | Health check interval in seconds |
| `retry_attempts` | `KIARINA_LIB_FALKORDB_RETRY_ATTEMPTS` | `3` | Number of retry attempts |
| `retry_delay` | `KIARINA_LIB_FALKORDB_RETRY_DELAY` | `1.0` | Delay between retries in seconds |
## URL Formats
FalkorDB URLs support the following formats:
- `falkor://localhost:6379` - Basic connection
- `falkor://username:password@localhost:6379` - With authentication
- `falkors://localhost:6379` - SSL/TLS connection
- `falkors://username:password@localhost:6379` - SSL/TLS with authentication
## Development
### Prerequisites
- Python 3.12+
- Docker (for running FalkorDB in tests)
### Setup
```bash
# Clone the repository
git clone https://github.com/kiarina/kiarina-python.git
cd kiarina-python
# Setup development environment (installs tools, syncs dependencies, downloads test data)
mise run setup
# Start FalkorDB for testing
docker compose up -d falkordb
```
### Running Tests
```bash
# Run format, lint, type checks and tests
mise run package kiarina-lib-falkordb
# Coverage report
mise run package:test kiarina-lib-falkordb --coverage
# Run specific tests
uv run --group test pytest packages/kiarina-lib-falkordb/tests/test_sync.py
uv run --group test pytest packages/kiarina-lib-falkordb/tests/test_async.py
```
## Dependencies
- [falkordb](https://github.com/kiarina/falkordb-py) - FalkorDB Python client (fork with redis-py 6.x support and async bug fixes)
- [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) - Settings management
- [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) - Advanced settings management
- [redis](https://github.com/redis/redis-py) - Redis client (FalkorDB is Redis-compatible)
### Note on FalkorDB Client
This library uses a [fork of the official FalkorDB Python client](https://github.com/kiarina/falkordb-py) instead of the [upstream version](https://github.com/FalkorDB/falkordb-py). The fork includes:
- **Redis-py 6.x compatibility**: Support for redis-py 6.4.0+ (upstream only supports 5.x)
- **Async client bug fixes**: Fixes for issues in the asynchronous client implementation
- **Enhanced stability**: Additional improvements for production use
The fork is based on the upstream `develop` branch and will be synchronized with upstream changes. Once these improvements are merged upstream, this library will migrate back to the official client.
## License
This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.
## Contributing
This is a personal project, but contributions are welcome! Please feel free to submit issues or pull requests.
## Related Projects
- [kiarina-python](https://github.com/kiarina/kiarina-python) - The main monorepo containing this package
- [FalkorDB](https://www.falkordb.com/) - The graph database this library connects to
- [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) - Configuration management library used by this package
Raw data
{
"_id": null,
"home_page": null,
"name": "kiarina-lib-falkordb",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "kiarina <kiarinadawa@gmail.com>",
"keywords": "client, database, falkordb, graph, pydantic, redis, settings",
"author": null,
"author_email": "kiarina <kiarinadawa@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b1/8b/abd7f0a9bec6b174e3c2503025bba6dfd16384a83acb0874ee31f20c0b66/kiarina_lib_falkordb-1.6.3.tar.gz",
"platform": null,
"description": "# kiarina-lib-falkordb\n\nA Python client library for [FalkorDB](https://falkordb.com/) with configuration management and connection pooling.\n\n## Features\n\n- **Configuration Management**: Use `pydantic-settings-manager` for flexible configuration\n- **Connection Pooling**: Automatic connection caching and reuse\n- **Retry Support**: Built-in retry mechanism for connection failures\n- **Sync & Async**: Support for both synchronous and asynchronous operations\n- **Type Safety**: Full type hints and Pydantic validation\n\n## Installation\n\n```bash\npip install kiarina-lib-falkordb\n```\n\n## Quick Start\n\n### Basic Usage (Sync)\n\n```python\nfrom kiarina.lib.falkordb import get_falkordb\n\n# Get a FalkorDB client with default settings\ndb = get_falkordb()\n\n# Select a graph and run a query\ngraph = db.select_graph(\"social\")\nresult = graph.query(\"CREATE (p:Person {name: 'Alice', age: 30}) RETURN p\")\nprint(result.result_set)\n```\n\n### Async Usage\n\n```python\nfrom kiarina.lib.falkordb.asyncio import get_falkordb\n\nasync def main():\n # Get an async FalkorDB client\n db = get_falkordb()\n\n # Select a graph and run a query\n graph = db.select_graph(\"social\")\n result = await graph.query(\"CREATE (p:Person {name: 'Bob', age: 25}) RETURN p\")\n print(result.result_set)\n```\n\n## Configuration\n\nThis library uses [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) for flexible configuration management.\n\n### Environment Variables\n\nConfigure the FalkorDB connection using environment variables:\n\n```bash\n# FalkorDB connection URL\nexport KIARINA_LIB_FALKORDB_URL=\"falkor://localhost:6379\"\n\n# Enable retry mechanism\nexport KIARINA_LIB_FALKORDB_USE_RETRY=\"true\"\n\n# Timeout settings\nexport KIARINA_LIB_FALKORDB_SOCKET_TIMEOUT=\"6.0\"\nexport KIARINA_LIB_FALKORDB_SOCKET_CONNECT_TIMEOUT=\"3.0\"\n\n# Retry settings\nexport KIARINA_LIB_FALKORDB_RETRY_ATTEMPTS=\"3\"\nexport KIARINA_LIB_FALKORDB_RETRY_DELAY=\"1.0\"\n```\n\n### Programmatic Configuration\n\n```python\nfrom kiarina.lib.falkordb import settings_manager\n\n# Configure for multiple environments\nsettings_manager.user_config = {\n \"development\": {\n \"url\": \"falkor://localhost:6379\",\n \"use_retry\": True,\n \"retry_attempts\": 3\n },\n \"production\": {\n \"url\": \"falkor://prod-server:6379\",\n \"use_retry\": True,\n \"retry_attempts\": 5,\n \"socket_timeout\": 10.0\n }\n}\n\n# Switch to production configuration\nsettings_manager.active_key = \"production\"\ndb = get_falkordb()\n```\n\n### Runtime Overrides\n\n```python\nfrom kiarina.lib.falkordb import get_falkordb\n\n# Override settings at runtime\ndb = get_falkordb(\n url=\"falkor://custom-server:6379\",\n use_retry=True\n)\n```\n\n## Advanced Usage\n\n### Connection Caching\n\n```python\nfrom kiarina.lib.falkordb import get_falkordb\n\n# These will return the same cached connection\ndb1 = get_falkordb()\ndb2 = get_falkordb()\nassert db1 is db2\n\n# Use different cache keys for separate connections\ndb3 = get_falkordb(cache_key=\"secondary\")\nassert db1 is not db3\n```\n\n### Custom Configuration Keys\n\n```python\nfrom kiarina.lib.falkordb import settings_manager, get_falkordb\n\n# Configure multiple named configurations\nsettings_manager.user_config = {\n \"analytics\": {\n \"url\": \"falkor://analytics-db:6379\",\n \"socket_timeout\": 30.0\n },\n \"cache\": {\n \"url\": \"falkor://cache-db:6379\",\n \"socket_timeout\": 5.0\n }\n}\n\n# Use specific configurations\nanalytics_db = get_falkordb(\"analytics\")\ncache_db = get_falkordb(\"cache\")\n```\n\n### Error Handling and Retries\n\n```python\nfrom kiarina.lib.falkordb import get_falkordb\n\n# Enable automatic retries for connection issues\ndb = get_falkordb(use_retry=True)\n\ntry:\n graph = db.select_graph(\"mydata\")\n result = graph.query(\"MATCH (n) RETURN count(n)\")\nexcept Exception as e:\n print(f\"Query failed: {e}\")\n```\n\n## Configuration Reference\n\n| Setting | Environment Variable | Default | Description |\n|---------|---------------------|---------|-------------|\n| `url` | `KIARINA_LIB_FALKORDB_URL` | `\"falkor://localhost:6379\"` | FalkorDB connection URL |\n| `use_retry` | `KIARINA_LIB_FALKORDB_USE_RETRY` | `false` | Enable automatic retries |\n| `socket_timeout` | `KIARINA_LIB_FALKORDB_SOCKET_TIMEOUT` | `6.0` | Socket timeout in seconds |\n| `socket_connect_timeout` | `KIARINA_LIB_FALKORDB_SOCKET_CONNECT_TIMEOUT` | `3.0` | Connection timeout in seconds |\n| `health_check_interval` | `KIARINA_LIB_FALKORDB_HEALTH_CHECK_INTERVAL` | `60` | Health check interval in seconds |\n| `retry_attempts` | `KIARINA_LIB_FALKORDB_RETRY_ATTEMPTS` | `3` | Number of retry attempts |\n| `retry_delay` | `KIARINA_LIB_FALKORDB_RETRY_DELAY` | `1.0` | Delay between retries in seconds |\n\n## URL Formats\n\nFalkorDB URLs support the following formats:\n\n- `falkor://localhost:6379` - Basic connection\n- `falkor://username:password@localhost:6379` - With authentication\n- `falkors://localhost:6379` - SSL/TLS connection\n- `falkors://username:password@localhost:6379` - SSL/TLS with authentication\n\n## Development\n\n### Prerequisites\n\n- Python 3.12+\n- Docker (for running FalkorDB in tests)\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/kiarina/kiarina-python.git\ncd kiarina-python\n\n# Setup development environment (installs tools, syncs dependencies, downloads test data)\nmise run setup\n\n# Start FalkorDB for testing\ndocker compose up -d falkordb\n```\n\n### Running Tests\n\n```bash\n# Run format, lint, type checks and tests\nmise run package kiarina-lib-falkordb\n\n# Coverage report\nmise run package:test kiarina-lib-falkordb --coverage\n\n# Run specific tests\nuv run --group test pytest packages/kiarina-lib-falkordb/tests/test_sync.py\nuv run --group test pytest packages/kiarina-lib-falkordb/tests/test_async.py\n```\n\n## Dependencies\n\n- [falkordb](https://github.com/kiarina/falkordb-py) - FalkorDB Python client (fork with redis-py 6.x support and async bug fixes)\n- [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) - Settings management\n- [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) - Advanced settings management\n- [redis](https://github.com/redis/redis-py) - Redis client (FalkorDB is Redis-compatible)\n\n### Note on FalkorDB Client\n\nThis library uses a [fork of the official FalkorDB Python client](https://github.com/kiarina/falkordb-py) instead of the [upstream version](https://github.com/FalkorDB/falkordb-py). The fork includes:\n\n- **Redis-py 6.x compatibility**: Support for redis-py 6.4.0+ (upstream only supports 5.x)\n- **Async client bug fixes**: Fixes for issues in the asynchronous client implementation\n- **Enhanced stability**: Additional improvements for production use\n\nThe fork is based on the upstream `develop` branch and will be synchronized with upstream changes. Once these improvements are merged upstream, this library will migrate back to the official client.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.\n\n## Contributing\n\nThis is a personal project, but contributions are welcome! Please feel free to submit issues or pull requests.\n\n## Related Projects\n\n- [kiarina-python](https://github.com/kiarina/kiarina-python) - The main monorepo containing this package\n- [FalkorDB](https://www.falkordb.com/) - The graph database this library connects to\n- [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) - Configuration management library used by this package\n",
"bugtrack_url": null,
"license": null,
"summary": "FalkorDB client library for kiarina namespace",
"version": "1.6.3",
"project_urls": {
"Changelog": "https://github.com/kiarina/kiarina-python/blob/main/packages/kiarina-lib-falkordb/CHANGELOG.md",
"Documentation": "https://github.com/kiarina/kiarina-python/tree/main/packages/kiarina-lib-falkordb#readme",
"Homepage": "https://github.com/kiarina/kiarina-python",
"Issues": "https://github.com/kiarina/kiarina-python/issues",
"Repository": "https://github.com/kiarina/kiarina-python"
},
"split_keywords": [
"client",
" database",
" falkordb",
" graph",
" pydantic",
" redis",
" settings"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1ea94c83ae6d60a334389c0732a6cbb8e4e7cd08c2d0aa404c228e373fda04d0",
"md5": "e464403053ec55629e1f599ce0ab24e4",
"sha256": "c42f3d98910ae1ab6c765b0a0b97e7085ec1b16b44e15c4218d368600efb357d"
},
"downloads": -1,
"filename": "kiarina_lib_falkordb-1.6.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e464403053ec55629e1f599ce0ab24e4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 8511,
"upload_time": "2025-10-12T17:48:23",
"upload_time_iso_8601": "2025-10-12T17:48:23.836213Z",
"url": "https://files.pythonhosted.org/packages/1e/a9/4c83ae6d60a334389c0732a6cbb8e4e7cd08c2d0aa404c228e373fda04d0/kiarina_lib_falkordb-1.6.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b18babd7f0a9bec6b174e3c2503025bba6dfd16384a83acb0874ee31f20c0b66",
"md5": "24d154a46b3689982daa0eb2a2051cc8",
"sha256": "fce66ec06d20b05512baf55776d65ff9bd653916c8508df3529cf721cab8ea1e"
},
"downloads": -1,
"filename": "kiarina_lib_falkordb-1.6.3.tar.gz",
"has_sig": false,
"md5_digest": "24d154a46b3689982daa0eb2a2051cc8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 6999,
"upload_time": "2025-10-12T17:48:33",
"upload_time_iso_8601": "2025-10-12T17:48:33.999080Z",
"url": "https://files.pythonhosted.org/packages/b1/8b/abd7f0a9bec6b174e3c2503025bba6dfd16384a83acb0874ee31f20c0b66/kiarina_lib_falkordb-1.6.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-12 17:48:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kiarina",
"github_project": "kiarina-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "kiarina-lib-falkordb"
}
JSON
