How-to guides

Directions for a task you already have in mind: a join, a page of results, a batch, a retry. Each assumes the basics of the tutorial, and links to the reference for every option.

• Joins

  Get rows with the rows they relate to, in one query and one typed result: a film with its cast, a crew member with their mentor.

• Pagination

  Show a long list a page at a time: here the films, newest first, two to a page. The last section puts the steps together in a request handler.

• Batches

  Write many rows at once: split them under Postgres's parameter limit, skip the ones already there, add up counts, keep rows with different keys from erasing what's stored, and get back only what you need.

• Retries

  Book seats at a screening under SERIALIZABLE, so that two requests at once can't break a rule, and let pgcast run the transaction again when Postgres refuses one.

• Custom types

  A type the generator can't map to TypeScript, such as point, and each domain come to you as a placeholder in zapatos/custom, for you to fill in.

• Raw SQL

  When no shortcut writes the query you need (a join, a window function, an INSERT … SELECT), write it in the sql template, and keep every value that comes from outside out of its text.

• Errors

  Tell what went wrong with a query, and answer it: a seat already booked, a screening that isn't there, an option your own code got wrong.

• Testing

  Three ways to test a function that runs pgcast queries, the most faithful first: against a real Postgres, each test rolled back; on the query it compiles, with no database; on a fake result typed from the schema.

• AI assistants

  Give an assistant that writes your queries three things: these docs, your generated schema and a short rules file, so that it writes them the pgcast way.

• Switch from Zapatos

  Move a project from Zapatos 6.6.1 to pgcast: change one line of package.json, regenerate, then let tsc, a look through your code and pgcast's warnings show you the few calls whose result changes.