A new open-source learning resource teaches PostgreSQL through annotated SQL examples, covering everything from your first SELECT to roles, indexes, and transactions. It's a reference disguised as a tutorial, and that's the point.
Most database tutorials fall into one of two traps. They either bury you in prose before you type a single query, or they hand you copy-paste snippets with no explanation of what's actually happening. Postgres by Example, a project by Dariush Abbasi published under the boringcollege organization on GitHub, takes a different route: it teaches PostgreSQL through annotated SQL examples, where the code is the lesson and the annotations fill in the why.
What the project actually is
The pitch is straightforward. PostgreSQL is a mature open-source relational database, and the official documentation is famously thorough but not exactly a gentle on-ramp. Postgres by Example positions itself as a hands-on introduction built around runnable examples rather than reference-manual completeness. The prerequisites are minimal: a PostgreSQL install, a running server, and the ability to connect with psql. Examples assume the default postgres database unless stated otherwise, and they target current stable PostgreSQL.
That last detail matters more than it sounds. A lot of SQL tutorials online are pinned to whatever version was current when someone wrote them in 2016, which means you hit syntax that has since changed or features that didn't exist yet. By explicitly tracking current stable Postgres and telling readers to use the latest version they can, the project sidesteps a common source of frustration for beginners who can't tell whether their query is wrong or just outdated.
The table of contents tells the story
The structure is the clearest signal of who this is for. It opens with Getting Started (First Query, psql Basics), then moves through Querying with SELECT, WHERE, ORDER BY, LIMIT/OFFSET, DISTINCT, and how NULL behaves. From there it covers data types (numeric, text, boolean, dates, and notably UUID and JSONB), then DDL for creating and altering tables with constraints, primary keys, and defaults.
The DML section walks through INSERT, UPDATE, DELETE, and RETURNING. Joins get real coverage: inner and left, right and full, self-joins, and the set operations UNION, INTERSECT, and EXCEPT. Then aggregation (COUNT, SUM, AVG, GROUP BY, HAVING), subqueries (scalar, IN, EXISTS, derived tables), string and date functions, COALESCE, and CASE.
What pushes it past a pure beginner cheat sheet is the back half. There's a section on indexes that covers not just CREATE INDEX but when to index, which is the harder and more useful question. Transactions get BEGIN/COMMIT/ROLLBACK plus savepoints. Views, security with roles and GRANT, and an Extras section covering psql meta-commands and COPY round it out. That progression, from your first query to access control and bulk loading, mirrors the order someone actually runs into these problems while building something real.
Why the annotated-example format works
The value of an example-first approach is that SQL is a language you learn by reading and modifying working queries, not by memorizing grammar. Including RETURNING alongside the basic DML statements is a good example of this philosophy. It's a Postgres feature that lets a single INSERT, UPDATE, or DELETE hand back the affected rows, which saves a round trip and a follow-up SELECT. Plenty of developers who have written SQL for years never picked it up because no tutorial put it next to the operation it modifies.
The same goes for putting JSONB in the data types section rather than treating it as an advanced topic. JSONB is one of the features that keeps teams on Postgres instead of reaching for a separate document store, and introducing it early frames it as a normal column type rather than something exotic. The coverage of NULL behavior as its own topic is another sign the author has watched people get burned. NULL comparison semantics are the single most common source of quietly wrong query results, and giving them dedicated space is the right call.
There are trade-offs to the format. An example-driven book is not a substitute for the official PostgreSQL documentation, and the project says as much by pointing readers there. You won't get exhaustive coverage of every option flag or every edge case in locking behavior. What you get instead is a path through the features in roughly the order you'll need them, with enough annotation to understand each one before moving on.
Where it fits
For someone coming from another database or from an ORM that has hidden the SQL from them, a resource like this fills a specific gap: it teaches the database directly, without a framework in between. The licensing is permissive, CC BY 4.0, so the material can be reused and adapted with attribution, which makes it reasonable for internal onboarding docs or course material.
The honest framing in the project's own description, self-described as "yet another postgresql book," is refreshing. It isn't claiming to replace the documentation or the well-known commercial books. It's offering a particular teaching style for people who learn best by running queries and reading what changed. If that describes how you pick up a new tool, the source is on GitHub and the first example is a click away.
Comments
Please log in or register to join the discussion