Skip to content

Type Signature File

Type signature files (*.sig1.pgn.yaml) are auto-generated by pGenie for PostgreSQL enum and composite types referenced by your queries.

They live under types/<schema>/. For example:

types/
└── public/
    ├── album_format.sig1.pgn.yaml
    └── recording_info.sig1.pgn.yaml

Domain types do not get a type signature file.

Purpose

Type signature files serve similar goals to query signature files, but at the type-definition level:

  1. Reviewable type contracts: enum variants and composite fields are stored in plain YAML and show up in pull request diffs.
  2. Drift detection for types: if a referenced enum or composite type changes, pGenie detects the mismatch and fails the run until you acknowledge it.
  3. Constraint tightening for composites: you can tighten not_null and element_not_null on composite fields when you want generators to expose stricter types.

Type signature files should be committed to version control.

Type signature files are not automatically overwritten

When pGenie sees a referenced enum or composite type without a signature file, it writes one. On later runs it reads the existing file, validates it against the database schema, and fails if they differ. It never silently overwrites the file.

Enum Format

An enum signature file contains the ordered list of PostgreSQL labels:

enum:
  - Vinyl
  - CD
  - Cassette
  - Digital

The order must match PostgreSQL exactly. Reordering, renaming, adding, or removing variants causes validation to fail.

Composite Format

A composite signature file contains one entry per field:

composite:
  studio_name:
    type: text
    not_null: false
  city:
    type: text
    not_null: false
  country:
    type: text
    not_null: false
  recorded_date:
    type: date
    not_null: false

Array-valued composite fields include dims and element_not_null:

composite:
  tags:
    type: text
    not_null: false
    dims: 1
    element_not_null: true

Validation Rules

Enums

  • The variant list must match the database exactly.
  • Variant order is significant.
  • Enum signature files are effectively acknowledgements of the current database definition, not a place to redefine it.

Composites

  • Field names must match the database type exactly.
  • Field types must match exactly.
  • not_null may be tightened, but not relaxed.
  • element_not_null for arrays may be tightened, but not relaxed.

This lets you make generator output stricter than what pGenie can infer conservatively, while still preventing incompatible edits.

Regenerating

To regenerate a type signature file from scratch:

  1. Delete the existing types/<schema>/<name>.sig1.pgn.yaml file.
  2. Run pgn generate or pgn analyse again.

pGenie will recreate the file from the current PostgreSQL schema.

Versioning

The filename suffix sig1 refers to version 1 of the type signature file format. Future breaking changes would introduce a new suffix such as sig2.