DBClient#

The DBClient class is the central interface for all database interactions in SQLThunder. It wraps SQLAlchemy with built-in thread pooling, error handling, and configuration loading.

SQLThunder supports MySQL, PostgreSQL, and SQLite through a single unified client.

Client Initialization#

from sqlthunder import DBClient

client = DBClient("config/postgres.yaml")

Required parameters:#

Argument	Description
`config_file_path`	Path to the YAML config file. Required.

Optional parameters:#

Argument	Description
`db_type`	Optional override for DB type (`mysql`, `postgresql`, `sqlite`) if not specified in config file.
`pool_size`	SQLAlchemy connection pool size. Default: 10.
`max_overflow`	Max overflow connections beyond pool. Default: 5.
`max_workers`	Thread pool size for parallel operations. Defaults to `pool_size + max_overflow`. Must be less than `pool_size + max_overflow`

Connection Lifecycle#

SQLThunder opens a persistent connection pool and thread executor at startup. You are responsible for managing the client lifecycle.

Close the client:#

client.close()

Shuts down the engine and thread pool.
After closing, all operations will raise a DBClientClosedError.

Reopen a closed client:#

client.reopen_connection()

Re-initializes the engine and thread pool.

Check if closed:#

client.is_closed  # True or False

Validate the connection:#

client.test_connection()

Using DBSession (Context Manager)#

For more structured workflows or temporary usage, wrap the client in a DBSession:

from sqlthunder import DBSession

with DBSession(client, label="load-prices", auto_close=True) as db:
    df = db.query("SELECT * FROM prices")

DBSession Options#

Argument	Description
`client`	A `DBClient` instance.
`label`	Optional name for logging/debugging. Default: `"UnnamedSession"`.
`auto_close`	Whether to automatically call `.close()` on exit. Default: `False`.
`auto_reopen`	Whether to automatically reopen a closed client on entry. Default: `False`.

If auto_reopen=False and the client is closed, DBClientSessionClosedError will be raised.

Public Methods Overview#

These are the key public methods for managing DBClient lifecycle:

`test_connection() -> bool`#

Checks if the client can successfully connect to the database.

`reopen_connection() -> None`#

Recreates engine and thread pool after shutdown. Use after close().

`close() -> None`#

Shuts down the engine and thread executor. Marks the client as unusable.

`is_closed: bool`#

Property indicating whether the client has been closed.

Notes#

All operations on a closed client will raise DBClientClosedError.
Use DBSession when possible for cleaner control of session lifetimes.
The client automatically validates config paths, SSL certificates, and connection URLs during init.

For querying, executing DDL/DML statements, inserting, batch operations, and CLI usage, see: