Quickstart#

SQLThunder is designed to be fast, simple, and robust — without the overhead of full ORMs or manual SQL boilerplate.

This guide helps you get started with basic configuration, querying, and data insertion in just a few lines.

After that, go explore the documentation, as SQLThunder as much more to offer !

Step 1 — Write a config file#

Create a YAML file to store your database connection info.

SQLite (local file)#

db_type: "sqlite"
path: "data/mydb.sqlite"

MySQL#

db_type: "mysql"
user: "root"
password: "mypassword"
host: "localhost"
database: "test_db"
port: 3306

PostgreSQL#

db_type: "postgresql"
user: "postgres"
password: "mypassword"
host: "localhost"
database: "mydb"
port: 5432
connect_timeout: 10

Step 2 — Connect to the database#

From a YAML config#

from sqlthunder import DBClient

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

Step 3 — Create table#

client.execute(
    """
    CREATE TABLE IF NOT EXISTS trades (
        id INT PRIMARY KEY,
        symbol VARCHAR(10) NOT NULL,
        price DECIMAL(10, 2) NOT NULL,
        trade_time DATETIME DEFAULT CURRENT_TIMESTAMP
    )
    """
)

Step 4 — Insert rows#

Besides what is shown below for INSERT, you can check out execute_many and execute_batch for other DML operations with bulk arguments.

Insert multiple rows in one transaction#

data = [
    {"id": 2, "symbol": "GOOG", "price": 2750.0},
    {"id": 3, "symbol": "MSFT", "price": 299.0}
]
client.insert_many("trades", data)

Or use multiple transactions in chunks with threaded batch insert#

client.insert_batch("trades", data * 1000, chunk_size=500, max_workers=4)

Threads make large inserts faster and more fault-tolerant.

Step 5 — Run a query#

df = client.query("SELECT * FROM trades LIMIT 10")
print(df)

You can choose your return type: dataframe (default), list, or raw.

You also have other query options for larger tables (query_keyed and query_batch).

Step 6 — Use the CLI#

SQLThunder includes a built-in CLI for fast, scriptable access:

sqlthunder query "SELECT COUNT(*) FROM trades" -c config/mysql.yaml

You can also insert (from CSV or Excel file) or execute statements from the terminal.

Next Steps#