toolssql 0.1.4

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 retries are disabled (retry_on_error=0). To enable, pass the number of extra attempts and an optional delay between them:

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()

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.