# What a field type becomes in Postgres

URL: https://kywi-docs-production.up.railway.app/developing/what-a-field-type-becomes-in-postgres
Type: docPage

Each field type maps to one Drizzle column — text, varchar, jsonb, uuid, timestamp, boolean or numeric — and boolean is the only one that gets NOT NULL.

One switch decides every column in a `kywi_ct_*` table. Nothing about a field's label, options or validation reaches the database — only its `type` does, and eighteen field types collapse onto eight column shapes.

Every field type maps to exactly one Postgres column type, and the column name is the field name snake-cased. The table is `kywi_ct_` plus the snake-cased type name, and it always carries `id uuid primary key` and `site_id uuid not null` before any field of yours.

## What a generated table actually looks like

// Generated by @kywi-software/core schema engine — do not edit manually // Run 'kywi migrate:generate' to regenerate this file import { pgTable, text, uuid, varchar } from 'drizzle-orm/pg-core' export const kywiCtDocPage = pgTable('kywi_ct_doc_page', { id: uuid('id').primaryKey(), siteId: uuid('site_id').notNull(), summary: text('summary'), surface: varchar('surface', { length: 255 }), persona: varchar('persona', { length: 255 }), appliesTo: text('applies_to'), updatedForVersion: text('updated_for_version'), })

## kywi-generated/schema/kywi_ct_doc_page.ts

## required is not NOT NULL

`summary` above is declared `required: true`, and its column is a plain nullable `text` — an unrelated fact from the same field name being on the reserved list ([Designing a content type](/developing/designing-a-content-type/) covers that collision; this is only about what `required` does to the column). Requiredness is enforced by the API's create and update schemas, never by the column — so a row written by anything that bypasses those schemas can hold a null in a "required" field, and dropping `required` from a field later needs no migration at all.

`boolean` is the exception: unless a field says `required: false` outright, its column is `NOT NULL DEFAULT false`. That is the one place where a field declaration writes a constraint.

## A boolean with no required lands differently on the two paths

Schema generation treats an unset `required` as required and emits `NOT NULL DEFAULT false`. The runtime `ALTER TABLE` path — the one that adds a column when a field is added in the Type Designer — reads the same unset value as optional and adds a plain nullable `boolean`. The same declaration therefore produces a different column depending on which path created it. Set `required` explicitly on booleans and the ambiguity disappears.

## Three things the column type does not give you

**No referential integrity.** `relationship`, `image` and `file` are bare `uuid` columns with no foreign key. Delete the target and the id stays behind, pointing at nothing; nothing errors and nothing cascades. (Extension attribute values, by contrast, do carry a real cascading FK to their content row.)

**No numeric precision.** `number` is `numeric` with no precision or scale, and drizzle types that column as a string — so a value read back is `"42"`, not `42`. Anything that sums, compares or sorts it in application code has to coerce first, and a JSON response carries the string.

**No room in a varchar.** 255 characters for `select`/`slug`/`email` and 7 for `color` are the real ceilings. They are generous for a select option and exact for a hex colour, which is the trap: `#rrggbbaa` and `rgba(…)` both fail to write.

## Three field types the config validator rejects

`url`, `email` and `list` are real field types — the type union declares them and the column switch handles all three — but the config validator's enum omits them. A config using one runs fine in the app, because nothing else re-validates it, and then fails at `kywi migrate:generate`, which is the only caller of the validator: the command prints `Invalid kywi.config.ts:` and exits non-zero, taking `kywi migrate` down with it. Declare those three through the Type Designer, where the route's own schema accepts them, until the enums agree.

What happens to an existing table when any of this changes is [Changing the content model on a database that has data](/developing/changing-the-content-model-on-a-database-that-has-data/).
