Field types: what each one decides

Thirty one field types ship. This chapter is not a reference, it is an argument about why a field type is the right place to put a decision.

The argument

When you write total:money, you are not choosing a storage format. You are making five decisions at once:

• Database
• an integer column in minor units, never a float
• Go
• a money.Amount, with arithmetic that cannot drift
• Validation
• a Zod rule that accepts 12.34 and rejects 12.345
• Form
• a money input with a currency prefix and two decimal places
• Table
• right aligned, formatted for the locale

Say float instead and all five change, each in a direction that is slightly wrong, and the one that costs you is the first. 0.1 + 0.2 is not 0.3 in any language with IEEE floats, and an invoice total that is out by a penny is found by an accountant rather than by a test.

The full list

string  text  richtext  int  uint  float  bool  toggle  select  radio
check  datetime  date  money  slug  belongs_to  one_to_one  many_to_many
string_array  file  files  email  url  domain  tel  country  color
percent  rating  time  json

Most are unsurprising. The ones worth knowing properly are below.

Text in three sizes

string, text and richtext differ in the column type and the input:

• string
• A varchar, a single line input. Names, codes, references
• text
• A text column, a textarea. Descriptions, notes
• richtext
• A text column holding HTML, and an editor in the form

richtext is the one with a hidden cost: it stores HTML that a user supplied, so it has to be sanitised on the way in or you have shipped stored cross-site scripting. The generated service does that, which is the reason to use the field type rather than a text plus an editor you wire yourself.

Choices, in three shapes

select, radio and check all constrain a value to a set, and differ only in the control:

grit generate resource Ticket \
  --fields "status:select:open=Open|closed=Closed|held=On hold"

The values before the = go in the database; the labels after it go on the screen. This produces a constraint, a Go constant set, a Zod enum and a dropdown, from one string.

Relationships

Three, and they are the field types that save the most work.

belongs_to is one word that produces a foreign key column with a constraint, a preloaded struct field, a nested TypeScript type, and a searchable dropdown in the form that shows the related record's label column rather than a UUID.

--fields "client:belongs_to"

ClientID uint    `json:"client_id"`
Client   *Client `json:"client"`     // preloaded on read

one_to_one is the same with a uniqueness constraint. many_to_many creates the join table and a multi-select picker.

Identity and files

slug derives a URL-safe string from another field and keeps it unique, which is three decisions people usually get wrong separately: how to slugify, when to regenerate, and what to do about collisions.

file and files store an upload reference rather than bytes in a column, and wire the upload pipeline from chapter forty two: resize, re-encode, strip EXIF, generate a thumbnail. Writing photo:file is how B8 gets answered.

Validated strings

email, url, domain, tel and country are all strings with a format. They look cosmetic and are not: each produces a matching rule in Go and in Zod, so the browser and the API agree about what is valid.

Numbers with meaning

int, uint and float are the raw ones. percent, rating and money are numbers that carry their own rules: a range, a step, a format. Prefer the specific one, because the constraint travels with it.

json stores arbitrary structure. Use it for genuinely unstructured data such as a webhook payload, and resist using it to avoid designing a schema, because nothing can query it well and nothing validates it.

Time, in three precisions

date is a calendar day with no time and no zone: a birthday, an invoice due date. datetime is an instant, stored UTC. time is a clock time with no date, for opening hours.

Choosing well, in one table

• Money
• money, never float
• A fixed set
• select, never string
• A calendar day
• date, never datetime
• A relationship
• belongs_to, never an int you join by hand
• An upload
• file, never a string holding a path
• An email
• email, so both sides validate it
• Unstructured
• json, and only when it really is

Every row of that table is a decision that is cheap now and expensive in six months, which is the whole case for field types being a type system rather than a convenience.

grit generate resource Property \
  --fields "title:string, slug:slug, description:richtext, \
price:money, bedrooms:int, rating:rating, available_from:date, \
viewing_time:time, status:select:draft=Draft|live=Live|sold=Sold, \
contact_email:email, website:url, photos:files, owner:belongs_to"
grit migrate
grit seed Property --count 200
grit start

Assignment

Commit your work with the message Field Types - Assignment One, exactly as written, so the leaderboard can score it.