I came from Rust where I used sqlx — you write raw SQL, you get typed structs back. Simple, honest, fast.

Then I had to write Python and reached for SQLAlchemy. Big mistake.

Suddenly I was learning a DSL on top of SQL. Debugging what ORM decided to generate behind my back. Fighting N+1 queries I didn't even know were happening. Writing text() to escape into raw SQL anyway.

So I built EzQL.

What is it?

A minimal wrapper around asyncpg. You write SQL. You get typed Pydantic models back. That's literally it.

The entire core is 57 lines of code.

How it works

Define your model:

from pydantic import BaseModel

class User(BaseModel):
    __table__ = "users"  # Marks this model as an EzQL model

    id: int
    name: str

Connect and query:

from ezql import create_client

client = await create_client(
    user, password, database, host,
    min_connections=2,
    max_connections=10
)

# Fire and forget
await client.execute("INSERT INTO users (name) VALUES ($1)", "Nazar")

# Returns List[User] or []
users = await client.query_as(User, "SELECT id, name FROM users WHERE name = $1", "Nazar")

assert users[0].name == "Nazar"
assert isinstance(users[0], User)

No sessions. No .commit(). No magic lazy loading. You know exactly what hits the database.

Joins

For joins you just define a DTO — a plain Pydantic model without __table__:

class UserWithPosts(BaseModel):
    # No __table__ — this is a DTO, not a table model
    user_name: str
    post_title: str

users_with_posts = await client.query_as(UserWithPosts, """
    SELECT users.name as user_name, posts.title as post_title
    FROM users
    JOIN posts ON posts.user_id = users.id
    WHERE users.id = $1
""", user_id)

Same approach as sqlx in Rust — separate struct for each query shape. No relationship magic, no hidden queries.

Warning: Always select columns explicitly in joins. SELECT * may cause a ValidationError at runtime since column names can collide across tables.

CLI validator

EzQL also ships with a CLI tool that validates your models against the actual DB schema before you deploy:

ezql ./models --dsn postgresql://user:password@localhost:5432/mydb

Found 1 models. Validating against DB...
Validating User → table users
┏━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┓
┃ Field ┃ Model type    ┃ DB type ┃ Status ┃
┡━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━┩
│ id    │ <class 'int'> │ integer │ ✓      │
│ name  │ <class 'str'> │ text    │ ✓      │
└───────┴───────────────┴─────────┴────────┘
All models are valid ✓

Catches missing columns, type mismatches, and tables that don't exist — before production blows up.

Why not just use SQLAlchemy?

SQLAlchemy makes sense when:

• Your team doesn't know SQL
• You need to support multiple databases simultaneously
• You're maintaining a legacy codebase that already uses it

Otherwise it's just an extra layer of abstraction you'll eventually punch through with text() anyway.

If you know SQL — just write SQL.

GitHub

import asyncio
from pydantic import BaseModel
from ezql import create_client
class User(BaseModel):
    __table__ = "users"

Feedback welcome — especially if you find a case where the type mapping breaks.