Metadata-Version: 2.4
Name: toolssql
Version: 0.1.4
Summary: Small SQL helper utilities with optional external authsql.py config loading.
Author: MH
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pymysql>=1.0.0
Dynamic: license-file

# toolssql

Small SQL helper utilities (MySQL-focused) with flexible auth configuration.

## Install

```bash
pip install toolssql
```

## Auth config loading

This package will try to load `CONNECTION_CONFIG` and `CONNECTION_CONFIG_DEFAULT`
from an `authsql.py` module/file in this order:

1. `AUTHSQL_MODULE` env var (importable module path, e.g. `myapp.authsql`)
2. Import `authsql` (works when your project root is on `sys.path`)
3. `AUTHSQL_PATH` env var pointing directly to an `authsql.py` file (supports `~` and `$HOME`)
4. Home directory fallbacks:
   - `~/authsql.py`
   - `~/.authsql.py`
   - `~/.config/authsql.py`

Example config:

```python
from typing import Dict, Any
CONNECTION_CONFIG: Dict[str, Any] = {
    'config1':
    {
        'host': 'localhost',
        'user': 'Analyst',
        'password': 'XXXXXXXXXXXXXXXXX',
        'database': 'Playground',
    },
    'config2':
    {
        'host': 'localhost',
        'user': 'Analyst2',
        'password': 'XXXXXXXXXXXXXXXXX',
    },
}

# default connection to be used, if nothing else is specified
CONNECTION_CONFIG_DEFAULT = "config1"
```

If none are found, it falls back to `{}` / `None`.

**Important:** Do not ship secrets inside this PyPI package. Keep `authsql.py` outside git.

## Usage

```python
from toolssql import MysqlConnect

db = MysqlConnect()  # uses loaded defaults if available
df = db.select_df("SELECT 1 AS one")
print(df)
```

Or inject config explicitly:

```python
from toolssql import MysqlConnect

cfg = {
  "prod": {"host": "...", "user": "...", "password": "...", "database": "..."}
}
db = MysqlConnect(connection="prod", connection_config=cfg, connection_default="prod")
```

## Retry on transient errors

`MysqlFetch` and `MysqlInsertValues` support automatic retries for transient
MySQL errors (deadlock, lock timeout, server gone, lost connection).

By default retries are disabled (`retry_on_error=0`). To enable, pass the
number of **extra** attempts and an optional delay between them:

```python
from toolssql import MysqlFetch

# retry once (2 attempts total) with 10 s delay between them
sql = MysqlFetch("SELECT 1", retry_on_error=1, retry_delay=10)
sql.runsql()
```

```python
from toolssql import MysqlInsertValues

ins = MysqlInsertValues(
    "my_insert",
    "INSERT INTO t (a, b) VALUES (%s, %s)",
    retry_on_error=2,   # up to 3 attempts total
    retry_delay=5,       # 5 s between retries
)
```

Non-retryable errors (e.g. syntax error, duplicate key) are never retried.
