config

Documentation

Index

• type BelongsTo
• type DbConfig
  • func (c *DbConfig) Normalize() error
  • func (c *DbConfig) Validate() error
• type FieldTag
• type JsonType
• type QueryConfig
• type StmtConfig
• type TableConfig
• type TypeOverride

Types

type BelongsTo

type BelongsTo struct {
	// The table that this table belongs to
	Table string `toml:"table"`
	// The name of the foreign key which points to the table this table
	// belongs to.
	KeyField string `toml:"key_field"`
	// Optional. If true the owning table has at most one of this table
	OneToOne bool `toml:"one_to_one"`
	// Optional. The name to give the pointer field in the generated parent
	// struct. If not provided, this will just be the name of the child struct.
	ParentFieldName string `toml:"parent_field_name"`
	// Optional. The name to give the pointer field in the generated child
	// struct. If not provided, this will just be the name of the parent struct.
	ChildFieldName string `toml:"child_field_name"`
}

An explicitly configured foreign key relationship which can be attached to a table's config.

type DbConfig

type DbConfig struct {
	// The name of the field that should be updated by pggen's generated
	// `Insert` methods. Overridden by the config option of the same name
	// on TableConfig.
	CreatedAtField string `toml:"created_at_field"`
	// The name of the field that should be updated by pggen's generated
	// `Update` and `Insert` methods. Overridden by the config option of
	// the same name on TableConfig.
	UpdatedAtField string `toml:"updated_at_field"`
	// The name of the nullable timestamp field that should be used to
	// implement soft deletes. Overridden by the config option of the
	// same name on TableConfig.
	DeletedAtField string `toml:"deleted_at_field"`
	// If true, it is an error for any [[query]] config block to be missing
	// the `comment` field. Useful if you want to be strict about documentation.
	RequireQueryComments bool           `toml:"require_query_comments"`
	TypeOverrides        []TypeOverride `toml:"type_override"`
	Queries              []QueryConfig  `toml:"query"`
	Stmts                []StmtConfig   `toml:"statement"`
	Tables               []TableConfig  `toml:"table"`
}

The configuration file format used to specify the database objects to generate code for.

func (*DbConfig) Normalize

func (c *DbConfig) Normalize() error

Given a user provided configuration, convert it into a normalized form that is suitable for use by pggen.

In particular we:

• resolve timestamp overrides and inheritance

func (*DbConfig) Validate

func (c *DbConfig) Validate() error

Give a user provided configuration, runs some santity checks on the provided values to try to provent users from encountering hard to diagnose issues down the line.

type FieldTag

type FieldTag struct {
	ColumnName string `toml:"column_name"`
	Tags       string `toml:"tags"`
}

Custom annotations to attach to the field generated for a given database column.

type JsonType

type JsonType struct {
	// The name of the `json` or `jsonb` column which should be parsed and serialized
	// into a structured type using the encoding/json package.
	ColumnName string `toml:"column_name"`
	// The name of the type, including package name, that the column should be parsed
	// into.
	TypeName string `toml:"type_name"`
	// The import string for the package in which the type lives. Should include quotes.
	Pkg string `toml:"pkg"`
}

type QueryConfig

type QueryConfig struct {
	// The name that should be used to identify this query in generated go
	// code.
	Name string `toml:"name"`
	// A comment to place on the generated method so that IDEs can provide
	// online documentation for the method.
	Comment string `toml:"comment"`
	// The actual text of the query.
	Body string `toml:"body"`
	// A string consisting of the runes '-' and 'n' to indicate the
	// nullability of return columns. '-' indicates that the column is
	// not nullable (NOT NULL), while 'n' indicates that it is nullable.
	// These need to be specified manually because postgres does not expose
	// a mechanism for infering the nullability of query results that I
	// could discover. The flags string must be exactly as long as the
	// result set is wide.
	NullFlags string `toml:"null_flags"`
	// A long-form way of specifying the same thing as `NullFlags`. Only one
	// of the two options should be provided. Any fields appearing in this list
	// will be treated as not nullable, with all other fields being considered
	// nullable as is the default.
	NotNullFields []string `toml:"not_null_fields"`
	// The name that should be used for this query's return type.
	// This is useful because it allows multiple queries to return
	// values of the same type so that client code does not have to
	// perform a series of endless conversions. If two queries which
	// return different types are given the same name to use for their
	// return type, it is an error.
	ReturnType string `toml:"return_type"`
	// A mapping of argument numbers to names to generate for them.
	// This configuration option allows you to give useful names to the
	// query arguments in the genrated code (normaly pggen will just make up
	// names like `arg0`, `arg1` and so on). An example mapping is
	// `"1:foo 2:bar 3:baz"`.
	ArgNames string `toml:"arg_names"`
	// If true, this query is expected to return just one result row, so
	// `pggen` will generate code that returns just a single result rather
	// than a slice that always has just one record you have to unpack.
	// If `single_result` is true, `pggen` will not generate a *Query method
	// for this query, as there is no point to supporting streaming mode for
	// a single-result query.
	SingleResult bool `toml:"single_result"`
	// If true, allow nullable types to be passed in as arguments to the query.
	// Normally, query arguments are always non-null so making every argument
	// a pointer type would just be annoying for client code, but sometimes you
	// do actually want nullable arguments.
	NullableArguments bool `toml:"nullable_arguments"`
	// If true and the query returns a slice, the values will be boxed as a slice
	// of pointers. Otherwise, it will be a slice of struct values.
	BoxResults bool `toml:"box_results"`
}

Queries registered in the config file represent arbitrary bits of SQL, possibly parameterized by $N arguments. The generated code will use `sql.QueryContext` and marshal the results into a list of rows returned.

type StmtConfig

type StmtConfig struct {
	// The name that should be used to identify this statement in generated
	// go code.
	Name string `toml:"name"`
	// The actual text of this statement.
	Body string `toml:"body"`
	// A mapping of argument numbers to names to generate for them.
	// This configuration option allows you to give useful names to the
	// query arguments in the genrated code (normaly pggen will just make up
	// names like `arg0`, `arg1` and so on). An example mapping is
	// `"1:foo 2:bar 3:baz"`.
	ArgNames string `toml:"arg_names"`
	// If true, allow nullable types to be passed in as arguments to the statement.
	// Normally, statement arguments are always non-null so making every argument
	// a pointer type would just be annoying for client code, but sometimes you
	// do actually want nullable arguments.
	NullableArguments bool `toml:"nullable_arguments"`
	// A comment to place on the generated method so that IDEs can provide
	// online documentation for the method.
	Comment string `toml:"comment"`
}

Statements are like queries but they are executed for side effects and therefore return `(sql.Result, error)` rather than a set of rows. Statements should be used for INSERT, UPDATE, and DELETE operations.

type TableConfig

type TableConfig struct {
	// The name of the table in the database
	Name string `toml:"name"`
	// If true, pggen will not infer a relationship between this table
	// and any owning tables based on any foreign keys in this table.
	NoInferBelongsTo bool `toml:"no_infer_belongs_to"`
	// A list of tables that this table belongs to
	BelongsTo []BelongsTo `toml:"belongs_to"`
	// The timestamp to update in `Insert`. Overriddes global version.
	CreatedAtField string `toml:"created_at_field"`
	// The timestamp to update in `Update` and `Insert`.
	// Overriddes global version.
	UpdatedAtField string `toml:"updated_at_field"`
	// The nullable timestamp for implementing soft deletes.
	// Overriddes global version.
	DeletedAtField string `toml:"deleted_at_field"`
	// A list of extra annotations to add to the generated fields.
	FieldTags []FieldTag `toml:"field_tags"`
	// A list of annotations indicating types that specific json columns should
	// be (de)serialized into. By default, all `json` and `jsonb` columns will
	// become byte arrays.
	JsonTypes []JsonType `toml:"json_type"`
	// If true, queries that return sliced results will return a slice of pointers.
	// Otherwise, it will be a slice of struct values.
	BoxResults bool `toml:"box_results"`
}

type TypeOverride

type TypeOverride struct {
	// The name of the type in postgres
	PgTypeName string `toml:"postgres_type_name"`
	// The name of the package in which the type appears as it would
	// appear in an import list, including quotes. The package name
	// may include an alias just like an import might.
	//
	// Examples:
	//   - '"github.com/google/uuid"'
	//   - 'my_uuid_alias "github.com/google/uuid"'
	Pkg string `toml:"pkg"`
	// The go name for the type, including package name
	TypeName string `toml:"type_name"`
	// The name of the package in which the nullable version of the type
	// appears. If `pkg` was already provided, `nullable_pkg` may be omitted.
	NullPkg string `toml:"nullable_pkg"`
	// The name of a go type which might be null (often Null<TypeName>)
	NullableTypeName string `toml:"nullable_type_name"`
	// This should contain a golang template that expands to a go expressions of type
	// `type_name`. The template can expect a context which includes key `.Value` which
	// will be an expression which evaluates to a value of type `nullable_type_name`.
	// It `pkg` and `nullable_pkg` will have been imported, so you can use them in the
	// expression if needed.
	//
	// For example, the nullable_to_boxed template for the binding the UUID type from the
	// github.com/gofrs/uuid package to postgres' `uuid` type might look like:
	//
	// “`
	// func(u uuid.NullUUID) *uuid.UUID {
	// 	if u.Valid {
	// 		return &u.UUID
	// 	}
	// 	return nil
	// }({{ .Value }})
	// “`
	//
	// If no template expression is provided, `.Value` will be assumed to be directly
	// assignable to a boxed version of `type_name`.
	NullableToBoxed string `toml:"nullable_to_boxed"`
}