SQLTy

⚠️ Experimental Package: This is an experimental project under active development. APIs may change without notice. Feedback and contributions are welcome!

Type-safe SQL queries for Python with automatic stub generation and runtime validation.

Powered by sqlglot - SQL parsing and analysis engine that makes type inference possible across multiple SQL dialects.

Overview

SQLTy provides type-safe SQL query execution with automatic type inference and stub generation. Write SQL queries with explicit type casts, and let SQLTy generate precise type stubs for full mypy integration.

from sqlty import SQLRegistry

class Query(SQLRegistry):
    pass

sql = Query.sql

# Type-safe query with automatic inference
query = sql("SELECT id::INTEGER, name::TEXT FROM users")
# Type: SQL[tuple[int, str]]

# Execute with full type safety
from sqlty.drivers.psycopg import execute
result = execute(conn, query, {})
# Type: Iterator[tuple[int, str]]

# Full mypy support
for user_id, name in result:
    print(f"User {user_id}: {name}")

Features

• 🔒 Type Safety: Full mypy integration with precise type inference
• 🚀 Automatic Stub Generation: Analyze code and generate .pyi files automatically
• 🎯 SQL Type Casts: Use PostgreSQL-style ::TYPE casts for explicit typing
• 📦 Multi-Registry Support: Organize queries into multiple registries
• 🔍 Source Tracking: Generated stubs include source location comments
• 🌐 Multiple SQL Dialects: Support for PostgreSQL, MySQL, SQLite, and more via sqlglot

Quick Start

Install:

pip install sqlty
# or
uv add sqlty

Write queries:

See advanced usage documentation for:

• Multi-registry and multiple schema support
• Configuration via pyproject.toml
• Full package example with stub generation and usage

# queries.py
from sqlty import SQLRegistry

class Query(SQLRegistry):
    pass

sql = Query.sql

# app.py
from queries import sql
from sqlty.drivers.psycopg import execute

query = sql("SELECT id::INTEGER, name::TEXT FROM users WHERE id = :id")
# Type: SQL[tuple[int, str]]

result = execute(conn, query, {"id": 123})
# Type: Iterator[tuple[int, str]]

Generate stubs:

sqlty . --mode=full

Type check:

mypy .
# Success: no issues found

Pre-commit Hook

Automatically generate stubs on commit by adding to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/jirikuncar/sqlty
    rev: v0.1.0  # Use the latest version
    hooks:
      - id: sqlty
        # Optional: customize with args
        # args: [".", "--mode=full", "--schema=schema.sql"]

Documentation

📚 Complete Documentation

Quick Links

• Installation Guide - Setup instructions for pip, uv, poetry, and more
• User Guide - Complete guide with basic and advanced usage
• API Reference - Detailed API documentation for all classes and methods
• Examples Guide - Step-by-step tutorials from basic to advanced

Key Topics

• Basic Usage - Creating registries, writing queries, generating stubs
• Multi-Registry Pattern - Organizing queries for large applications
• Type Inference - How SQLTy infers Python types from SQL
• Internals - Architecture and implementation details

Contributing

See DEVELOPMENT.md for development setup, workflows, and contribution guidelines.

License

MIT License - see LICENSE file for details.