Skip to content
Skills Library
Programming · Building & coding

sqlty-adopt

/sqlty-adopt

Introduce sqlty into an existing Python project with raw SQL queries, one module at a time. Use when a project doesn't use sqlty yet and you are asked to add it, type its SQL queries, configure [tool.sqlty] (dialect, schema from a database dump or migrations), choose which queries to convert first, mark the ones sqlty can't type yet, or add the first CI gate.

Repository
sqlty ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Introduce sqlty into an existing Python project with raw SQL queries, one module at a time. Use when a project doesn't use sqlty yet and you are asked to add it, type its SQL queries, configure [tool.sqlty] (dialect, schema from a database dump or migrations), choose which queries to convert first, mark the ones sqlty can't type yet, or add the first CI gate.

Original author description

Introduce sqlty into an existing Python project with raw SQL queries, one module at a time. Use when a project doesn't use sqlty yet and you are asked to add it, type its SQL queries, configure [tool.sqlty] (dialect, schema from a database dump or migrations), choose which queries to convert first, mark the ones sqlty can't type yet, or add the first CI gate.

How it works

  1. 1. Install and configure
  2. 2. Convert one module
  3. 3. Name the important rows
  4. 4. Gate it in CI
  5. Don't
  6. Reference
Original SKILL.md headings · 122 lines, 543 words
SKILL.md preview
---
name: sqlty-adopt
description: Introduce sqlty into an existing Python project with raw SQL queries, one module at a time. Use when a project doesn't use sqlty yet and you are asked to add it, type its SQL queries, configure [tool.sqlty] (dialect, schema from a database dump or migrations), choose which queries to convert first, mark the ones sqlty can't type yet, or add the first CI gate.
---

# Adopt sqlty

sqlty only acts on strings that start with `--sql`, so you can adopt it one
module, or one query, at a time. Unconverted code keeps working.

Run `sqlty version`: this skill may be newer or older than the installed sqlty.
When it and `sqlty --help` disagree, trust the command.

## 1. Install and configure

```bash
uv add sqlty            # or: pip install sqlty; sqlty requires Python >= 3.14
```

Find the dialect from the driver (`psycopg` or `asyncpg`: `postgres`;
`sqlite3`: `sqlite`; `pymysql` or `mysqlclient`: `mysql`) and the schema. A
schema saves a cast in every query. Dump it from the database, or point at
the migrations:

```bash
pg_dump --schema-only app > schema.sql      # PostgreSQL
sqlite3 app.db .schema > schema.sql         # SQLite
mysqldump --no-data app > schema.sql        # MySQL
```

```toml
[tool.sqlty]
dialect = "postgres"
schema = "schema.sql"   # or a directory of migrations: "migrations/"
```

`schema.sql`:

```sql
CREATE TABLE public.users (
    id integer NOT NULL,
    name text NOT NULL,
    created_at timestamp with time zone DEFAULT now()
);
```

Statements that don't shape a table, such as grants and indexes, are ignored,
and a schema-qualified table matches an unqualified query:

```python
query = "--sql\nSELECT id, name, created_at FROM users WHERE id = %s"
# rewritten: query = SQL[tuple[int, str, datetime.datetime | None]]("--sql\nSELECT id, name, created_at FROM users WHERE id = %s")
```

## 2. Convert one module

Pick a module whose queries are plain string literals. Add `--sql` and a
newline to the start of each query, then:

```bash
sqlty rewrite app/users.py
sqlty check app/users.py
```

Skip queries built with f-strings, `+` or `%`: convert them to parameters
(`%s`, `$1`, `?`) first, in a separate change. A `--sql` string that is still
unwrapped after `rewrite` has a column sqlty can't type: cast it, or add its
table to the schema.

`sqlty check` lists the `--sql` strings left unwrapped as `stale-rewrite`, so
you can see what is left. To make each untyped query visible as
`SQL[UNTYPED]`, set `untyped = "sentinel"`.

## 3. Name the important rows

Replace `tuple[...]` with a `TypedDict`, `dataclass` or `NamedTuple` where a
query feeds domain code, starting with the rows passed around the most. With
psycopg, `sqlty.drivers.psycopg.execute` returns rows of that type:

```python
from dataclasses import dataclass
from datetime import datetime

from sqlty import SQL
from sqlty.drivers.psycopg import execute

@dataclass
class User:
    id: int
    name: str
    created_at: datetime

GET_USER = SQL[User]("--sql\nSELECT id, name, created_at FROM users WHERE id = %s")

def get_user(conn, user_id: int) -> User | None:
    return execute(conn, GET_USER, (user_id,)).fetchone()
```

`sqlty check` now fails if `users` changes and `User` doesn't follow.

## 4. Gate it in CI

Start with what passes today, then tighten:

```yaml
- run: uv run sqlty rewrite --check .
- run: uv run sqlty check --output-format github .
```

Promote `stale-type` to `error` once the converted modules are clean, and add
`sqlty breaking` when schema changes start going through pull requests. See
`sqlty-ci`.

## Don't

- Don't convert every module in one change: each module is reviewable on its own.
- Don't hand-write `T`, and don't strip a file with named row types.
- Don't write `"--sql SELECT ..."` with a space: the query is a SQL comment.

## Reference

- [Migration](https://jirikuncar.github.io/sqlty/recipes/migration/)
- [Schema inference](https://jirikuncar.github.io/sqlty/guide/schema-inference/)
- [Drivers and ORMs](https://jirikuncar.github.io/sqlty/guide/drivers-and-orms/)
- [Configuration](https://jirikuncar.github.io/sqlty/reference/configuration/)

Versions

The database has no other skills named sqlty-adopt.

Database snapshot: 13.11.2026 · package version c19cda46779e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100sqlty
    Write, type and check raw SQL in Python with sqlty. Use when adding or editing a query in a project that uses sqlty (strings starting with --sql, SQL[T] or SQLTemplate[T] wrappers, a [tool.sqlty] section), when generating Python row types for a query, or when checking that…
  • 100sqlty-rewrite
    Wrap --sql query strings as SQL[T] with sqlty rewrite, update or remove the wrappers, and keep them in sync after editing a query. Use when writing a new SQL query in Python, editing the SQL inside an SQL[T] wrapper, committing or removing wrappers (sqlty rewrite, sqlty strip,…
  • 100add-module
    Creates a new module in this solution with its project, database schema, registration, migrations resource and test project, and its contracts project once another module needs one. Use when asked for a new module or bounded context, including in a solution that has no modules yet.
  • 95database-fundamentals
    Reviews schema design, SQL queries, ORM patterns. Use when junior creates schema, writes queries, adds migrations, works with Prisma/MongoDB/PostgreSQL, or asks "is this SQL safe", "N+1", "index".
  • 96add-module
    Adds a new application module to this Spring Modulith project with the package layout the ModuleBoundariesTests gate expects, and a module-scoped integration test. Use when the user asks for a new module, bounded context, or feature area that doesn't belong in an existing module.
  • 90database-management
    When you need to modify the database schema, run migrations, or deploy Supabase changes. Use this for all SQL and Supabase-related tasks.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.