types when application code needs the latest database shape before a migration is applied.
types reads one schema source, writes database.types.ts, and writes database.zod.ts unless TypeScript output is sent to stdout.
database.types.ts follows the Supabase generated type contract: Database, helper types such as Tables, TablesInsert, TablesUpdate, Enums, CompositeTypes, and runtime enum Constants. database.zod.ts is a Supaschema runtime extension exposed as SupaschemaZod; it is not part of the upstream Supabase TypeScript contract.
SupaschemaZod translates only CHECK constraints whose refinements are loose-or-exact for the client-to-PostgreSQL wire path. Scalar integer and float8/double precision columns support bounds; typmod-free numeric/decimal supports non-strict bounds; all three support BETWEEN. Equality is limited to safe integer literals on integer-family columns, and parsed float literals produce only non-strict bounds. Typmod-free text, varchar/character varying, and citext support char_length; typmod-free text and varchar/character varying support IN only without an explicit collation. Bare booleans become column refinements. Numeric column comparisons are null-aware and require wire-exact small-integer or float8 targets. Casts unwrap only when both the source and safe text-family target are typmod-free and have the same resolved base type. Scalar columns inherit column-level checks from every unambiguously resolved CREATE DOMAIN in their type chain, with VALUE resolved to the column. Real/float4, typmod-constrained numeric, char/bpchar, domain arrays, ambiguous domain hops, explicitly collated list checks, widening or typmod-bearing casts, precision-sensitive arbitrary-numeric or bigint comparisons, and any other uncertain expression are skipped rather than approximated. NOT VALID table checks refine Insert and Update but not Row, because existing rows are unverified until the constraint is validated.
The generated contract is derived from the schema source itself. Tables, views, materialized views, view dependencies, functions, enums, composites, and supported catalog-backed objects should resolve from the parsed SQL model before a database is available. If a view depends on an extension-owned relation that is not in the configured source, add or use a supported extension model/source rather than patching application code with local casts or copied contracts.
If a modeled relation, function, extension, or expression should resolve but is generated as unknown, fix the schema source, supported model, or typegen diagnostic path before updating application consumers. Unsupported PostgreSQL scalars intentionally keep the upstream unknown fallback.
Use this when
- A pull request changes SQL and TypeScript together.
- You want generated runtime validators at API boundaries.
- A database connection is not available.
- The schema tree changed and generated contracts need refresh.
Run it
types is the generated-contract command. diff writes migration SQL; it does not refresh TypeScript or Zod outputs.
Flags
source
Schema source to parse. Defaults to the configured schema tree.
path | stdout
TypeScript output path.
stdout prints types and skips the Zod file.Output paths
Commit generated outputs when reviewers should see app-type impact in the same pull request as schema changes.
Related
Type generation guide
Generate types before applying migrations.
Configuration
Set output paths and workflow policy.
Diff
Generate migration SQL from schema changes.
ORM-free apps
Use generated types and validators as the application contract.