db-client-smacondi 1.0.0
a pymongo dbClient for multiple clusters
Requires Python: >=3.9


# db-client-python

> **⚠️ ATTENTION: Recent Module Structure Changes**  
> This package has undergone significant structural changes. If you are upgrading from a previous version, please check the [Breaking Changes](#breaking-changes) section below.

A Python client for managing database connections and account-based cluster routing, designed for MongoDB and similar backends.



## Features
- Dynamically route database connections based on account information
- Cache and reuse database clients for efficiency
- Support for main and cluster-specific connection strings
- Async API for account cluster lookup

## Installation

```bash
pip install db-client-smacondi
```

## Usage

### 1. Prepare your connection string map
This is a dictionary mapping cluster names to MongoDB connection strings. You must provide at least a `MAIN` entry:

```python
connection_string_map = {
        'MAIN': 'mongodb://main.example.com:27017',
        'CLUSTER1': 'mongodb://cluster1.example.com:27017',
        # ... add more clusters as needed
}
```

### 2. Set your Account API URL
This should be an HTTP endpoint that returns account cluster info as JSON. The API must support a GET request with a query parameter `accountId` and return a response like:

```json
{
    "clusterId": "CLUSTER1",
    "dbName": "telemetry_db",
    "_id": "account123"
}
```

Example:
```python
account_api_url = "https://api.example.com/account-info"
```

### 3. Using DbClientSupport

```python
from db_client_smacondi.db_client_smacondi import get_db_client_smacondi

# Initialize
support = get_db_client_smacondi(apiURL=account_api_url, conn_string_map=connection_string_map)

# Get DB client for a specific cluster
cluster_client = support.get_db_client_by_cluster_id("CLUSTER1")

# Get DB client for a specific account (async)
import asyncio
async def get_account_client():
        result = await support.get_db_client_of_account("account123")
        db_client = result["db_client"]
        db_name = result["db_name"]
        # Use db_client as needed

asyncio.run(get_account_client())
```

### 4. Closing connections

To properly close all database connections:

```python
from db_client_smacondi.db_client_smacondi import close_all_db_clients

# Close all database connections
close_all_db_clients()
```

## Breaking Changes

If you're upgrading from a previous version, be aware of these breaking changes:

### Module Structure
- Module renamed from `dbClientSmacondi` to `db_client_smacondi`
- File names changed from camelCase to snake_case:
  - `dbClientSmacondi.py` → `db_client_smacondi.py`
  - `dbClient.py` → `db_client.py`

### API Changes
- The `DbClientSupport` class is no longer directly exposed
- Use `get_db_client_smacondi()` function to get a client support instance
- The class `_DbClientSupport` is now considered an implementation detail
- `get_main_db_client()` method has been removed, use `get_db_client_by_cluster_id('MAIN')` instead

### Import Changes
```python
# Old import
from dbClientSmacondi.dbClientSmacondi import DbClientSupport

# New import
from db_client_smacondi.db_client_smacondi import get_db_client_smacondi
```

### Instantiation Changes
```python
# Old instantiation
support = DbClientSupport(apiURL=account_api_url, conn_string_map=connection_string_map)

# New instantiation
support = get_db_client_smacondi(apiURL=account_api_url, conn_string_map=connection_string_map)
```

## Testing

To run tests and check coverage:
```bash
pytest --cov=src/db_client_smacondi --cov-report=html
```

## License
AGPL-3.0-or-later