Minimal, dependency-free SQL query loader (pugsql-like) and forward-only migrations with a tiny CLI.

poetry add --path . --editable

project/
  sql/
    migrations/
      0001_initial.sql
    users.sql
  app.py

sql/users.sql

-- :name users.create :affected
INSERT INTO users(id, email) VALUES (:id, :email);

-- :name users.by_id :one
SELECT id, email FROM users WHERE id = :id;

-- :name users.all :many
SELECT id, email FROM users ORDER BY id;

Create:

lightql migrations create add_users_table --sql-dir sql

Edit the new file, e.g. sql/migrations/0001_add_users_table.sql:

CREATE TABLE IF NOT EXISTS users (
  id INTEGER PRIMARY KEY,
  email TEXT NOT NULL
);

Apply / Status:

lightql migrations apply  --sql-dir sql --dsn sqlite:///app.db
lightql migrations status --sql-dir sql --dsn sqlite:///app.db

from lightql import connect, load_queries

conn = connect("sqlite:///app.db")
q = load_queries("sql", conn)

q.users.create(id=1, email="[email protected]")  # :affected -> int rowcount
print(q.users.by_id(id=1))                     # :one -> dict or None
print(q.users.all())                           # :many -> list[dict]

• DSN support: sqlite only (e.g., sqlite:///app.db). Extend lightql/db.py to add other drivers.
• Parameters: use named parameters (e.g., :id) to match Python DB-API for sqlite.
• :script blocks run with executescript (SQLite) or naive ; splitting.
• Forward-only migrations tracked in schema_migrations.