Skip to content
mplemayPublic

About

Typesafe raw SQL for Python, with a PostgreSQL driver and query checker.

Topics

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

200 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

rowx

Typesafe raw SQL for Python 3.14+, with no ORM. You write SQL as a PEP 750 t-string and say what a row looks like.

rowx check prepares each checked query against a live Postgres 18 database. query_unchecked SQL is not described.

  • SQL stays SQL. You write the statement you would write in psql. {name} is a bound parameter. It is never pasted into the SQL text.
  • The row is a normal type. A tuple, a scalar, a dataclass, a NamedTuple, a TypedDict, or a pydantic model. pyright, mypy, and ty see that type with no plugin.
  • The database checks it. rowx check asks Postgres to prepare and describe the statement, then compares the columns and parameters with the row type.
  • Postgres, async, one driver. Python 3.14+, asyncio, and rowx.postgres. There is no dialect layer.

Postgres only. One statement per query. query_unchecked SQL is not described. There is no ORM and no generated query functions. The boundary is Why rowx and Known limits.

Quickstart

Install the checker and the PostgreSQL backend with uv add "rowx[postgres]".

import asyncio

from rowx import query
from rowx.postgres import Pool

type UserRow = tuple[int, str, str | None]  # id, name, email


async def main() -> None:
    async with Pool(DSN, max_size=10) as pool:
        name = "alice"
        user = await query[UserRow](t"SELECT id, name, email FROM users WHERE name = {name}").one(pool)
        assert user[1] == "alice"

        names = await query[str](t"SELECT name FROM users ORDER BY name").all(pool)
        assert names == ["alice", "bob", "carol"]

        ids = [user[0]]
        updated = await query(t"UPDATE users SET email = {None} WHERE id = ANY({ids})").execute(pool)
        assert updated.rows_affected == 1


asyncio.run(main())

You now have:

  • a parameter ({name}) bound on the server
  • a row type (UserRow) that the checker and your type checker both see
  • .one, .all, and .execute (.optional when the row may be missing)
  • a pool (Pool) or one connection (from rowx.postgres import connect)
  • a check that fails the build when the schema and UserRow disagree

A dataclass, NamedTuple, TypedDict, or pydantic model matches columns by name. The shapes are on Rows.

import asyncio
from dataclasses import dataclass

from rowx import query
from rowx.postgres import connect


@dataclass(slots=True)
class User:
    id: int
    name: str
    email: str | None


async def main() -> None:
    async with await connect(DSN) as conn:
        user = await query[User](t"SELECT id, name, email FROM users WHERE name = {'alice'}").one(conn)
        assert user.name == "alice"


asyncio.run(main())

Pool imported from rowx is the executor protocol, not a connection pool. Import it from rowx.postgres. The four distributions are Packages.

Check the queries against your database:

rowx check src --database-url postgresql://app@localhost/app

rowx check exits 0 when it reports no diagnostics, including when no queries were found, 1 when it reports one or more diagnostics, and 2 when the check could not run. The checker reference is the contract for the exit codes.

No server? uv add "rowx[embedded]" adds an in-process Postgres 18: use rowx.embedded.Database() in code, or an embedded:// database URL for rowx check, rowx migrate and the pytest plugin, with no Docker. It is for development, checking and tests, and it is not for production. See Embedded Postgres.

A type mismatch is reported like this:

error[type-mismatch]: column 2 "name": column type is `int` but the annotation is `str`
  --> src/app.py:14:22
   |
14 |     query[tuple[int, str]](t"SELECT id, name FROM users")
   |                      ^^^ element 2

Next

  • First query: install, then SELECT.
  • From SQLAlchemy: a Session, select(), and text() / tstring(), and what replaces them.
  • Why rowx: the decision, then SQLx, sqlc, asyncpg, and psycopg.

The rules of a check are in the checker guide. The use-rowx skill is agent guidance for queries, the package split, and rowx check. The changelog is what changed in each release. The user guide is the rest of the job.

About

Typesafe raw SQL for Python, with a PostgreSQL driver and query checker.

Topics

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages