toolssql 0.1.5

Small SQL helper utilities with optional external authsql.py config loading.

toolssql

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

Install

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:

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

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:

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, one retry is enabled (retry_on_error=1, i.e. 2 attempts total) with a 10 s base delay plus random jitter (actual sleep is between 5–10 s) to avoid thundering-herd collisions. By default, only deadlocks are retried; to retry other transient errors, set retry_errors. You can customise this:

from toolssql import MysqlFetch

# default: 1 retry (2 attempts total) with ~10 s jittered delay
sql = MysqlFetch("SELECT 1")
sql.runsql()

# disable retries
sql = MysqlFetch("SELECT 1", retry_on_error=0)

# up to 3 retries (4 attempts total) with 5 s delay
sql = MysqlFetch("SELECT 1", retry_on_error=3, retry_delay=5)

# retry all built-in transient errors
from toolssql.sql import RETRYABLE_ERRORS
sql = MysqlFetch("SELECT 1", retry_on_error=2, retry_delay=5, retry_errors=RETRYABLE_ERRORS)

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.