Peewee Overview
Peewee is a small, friendly Python ORM - a layer that maps Python classes to database tables and Python objects to rows, so you query and mutate data with class expressions instead of raw SQL. Its design bet is legibility: the query API reads almost like the English of the data ("all users whose age is greater than 21, ordered by name"), and the generated SQL is simple and inspectable, which keeps Peewee a good fit for apps where the database is a detail you want out of the code, not a layer you want to fight. This tutorial builds from the first model to production concerns - pooling, migrations, performance - and the mental model to carry throughout is one sentence: a model is a table, an instance is a row, and a query is a chain of class expressions that ends in executed SQL.
What Peewee Gives You
| Layer | What it is | Chapters |
|---|---|---|
| Models and fields | the class-to-table mapping | models-fields |
| Connections | SQLite, PostgreSQL, MySQL, the connect lifecycle | connections |
| Queries | select, where, order_by, the expression language | crud-operations, query-expressions |
| Relationships | ForeignKey, OneToOne, many-to-many, joins | one-to-many, many-to-many, joins-subqueries |
| Writes | insert, update, delete, upsert, bulk | crud-operations, bulk-operations |
| Advanced | aggregation, migrations, transactions, signals | aggregation, migrations, transactions, signals-hooks |
| Playhouse | pooling, pooling, extras, the utility modules | playhouse-pooling, playhouse-extras |
Everything in Peewee derives from the Model base: a model class declares its fields, Peewee builds the table from them, and the query methods (select, insert, update, delete) are classmethods that return query objects you refine with where/join/order_by and execute. The uniformity is the point - the same expression language works for a read or a write, a single table or a join, and the generated SQL is the same simple dialect you would write by hand.
Why Peewee (and What It Is Not)
Peewee is the right tool when you want an ORM's productivity - models, queries, migrations - with a small, readable layer that does not hide the SQL. It is not a heavyweight ORM: it has no identity map by default, no unit-of-work that tracks every change, and no deep relationship-graph magic. The trade is the same shape as the Kivy-versus-native-toolkit comparison from the other tutorials - Peewee gives you a consistent, expressive query style and a migration path, and the cost is that some of the "automatic" behaviors of a heavier ORM are things you write explicitly (a save is a save, a relationship load is a join you ask for). For apps where the data access should be obvious and the SQL should be predictable, that is a feature, not a limitation.
Tutorial Roadmap
- Setup, the first model, and the connection lifecycle.
- CRUD and the query expression language - the core API.
- Relationships - foreign keys, one-to-one, many-to-many, and the joins that read across them.
- Aggregation and the analytical queries - counts, sums, groups.
- Schema changes - migrations and the playhouse tools.
- Transactions, signals, and the write-side discipline.
- Playhouse - pooling and the utility modules.
- Data movement, testing, performance, and the design rules.
Conventions
Examples run against SQLite in-memory or a file database, so they are runnable with no server; the PostgreSQL and MySQL variants are noted where the dialect differs. The running example across the middle chapters is a small blog/content domain - authors, articles, tags - which gives the relationship and join chapters a shared shape to build on. Names follow Peewee's own conventions: model classes are CapWords, fields are declared as class attributes, and the query methods are the lowercase classmethods. The generated SQL is shown alongside the Python in the chapters where the mapping matters, because reading the SQL the ORM produces is the skill that keeps you in control of it.
Summary
Peewee maps Python classes to tables and objects to rows, and expresses data access as chains of class expressions that end in simple, inspectable SQL. The model is the foundation - a class with field declarations that Peewee turns into a table - and the query methods are the uniform API over reads and writes, single tables and joins. Choose Peewee when you want ORM productivity with a thin, legible layer and predictable SQL; skip it when you need a heavyweight unit-of-work or you would rather write the SQL directly. The next chapter installs the package and connects a database, and the first model you define there is the shape every later example reuses.