examples/

README

Examples

This directory contains a number of different examples showing useful ways to use pggen. They contain checked in versions of the generated code and an output.txt file showing what they print so that you don't have to go to the trouble of running them if you don't want to. Because it is checked in when the example is first written, the generated code may not be entirely up to date with the most recent master version of pggen.

Instructions For Running

First, cd into the example directory, then set up the database

> createdb pggen_development
> psql pggen_development < db.sql

Make sure that $DB_URL is postgres://localhost/pggen_development?sslmode=disable either by explicitly setting it in the environment with

export DB_URL=postgres://localhost/pggen_development?sslmode=disable

or by installing direnv and doing direnv allow at the repo root (this will source the .envrc file).

Finally, run the program

> go run ./main.go

List of Examples

Example: query

This example shows how to configure a query to be run against the database.

Example: statement

This example shows how to configure a statement to be executed against the database.

Example: extending_models

This example shows how to add methods containing business logic to the model structs generated by pggen. This can help you avoid an error prone and labor intensive manual translation from the model structs to an extra layer just so you can define methods on the intermediate layer.

Example: upsert

This example shows how to use the upsert interface that pggen will automatically generate for each model struct generated from a table.

Example: id_in_set

This example shows how to write a query that checks for set containment using the = ANY idiom rather than the IN operator that is typically used with other database interactivity libraries.

Example: include_specs

This example shows how to use include specs to tell pggen how to fill in records which are associated with one another via foreign keys. Include specs are the key to the way that pggen deals with associations.

Example: timestamps and soft deletion

This example shows how to make use of the automatic timestamp features that pggen provides. You can ask pggen to automatically take care of keeping track created at and updated at timestamps. Soft deletes are often implemented with a timestamp rather than just a boolean flag, so pggen supports them using similar machinery, which is also demonstrated in this example.

Example: query argument names

This example shows how to provide useful names for query arguments. You can also provide useful names for query arguments by defining a stored function and telling pggen to generate shims for it, but you may prefer to avoid the ceremony usually involved in managing objects in a database.

Example: middleware

This example shows how to inject middleware between the generated PGClient and the database connection. This allows you to implement things like logging and tracing to see what queries are getting run against the database.

Example: single_results

This example shows how to write queries that return just a single row as a result using the single_result configuration option. This is a small quality of life improvement over having to unpack a slice each time you place a query.

Example: json_columns

This example shows how to ask pggen to generate conversion code between arbitrary go types and json or jsonb types in postgres.

Example: nullable_query_arguments

This example shows how to ask pggen to generate code which allows nils to be passed into queries. By default, you can only pass concrete types like string and int into a pggen query.

Example: uuid

This example shows how to work postgres's uuid type using the github.com/gofrs/uuid library. There is no uuid type in the go standard library, so you must use a third party type. pggen does not want to force a hard dependency on any particular uuid library, so you must explicitly configure a type override in order to work with uuids.

Example: nullable_statement_arguments

This example shows how to generate a statement with that accepts nullable arguments. By default, you can only pass in non NULL values to statements, since this is generally more convenient, but if you want you can explicitly ask pggen to allow you to pass in NULL values.