diff --git a/apps/docs/content/guides/database/tables.mdx b/apps/docs/content/guides/database/tables.mdx index e8da0a6631e..39a70ce6e1e 100644 --- a/apps/docs/content/guides/database/tables.mdx +++ b/apps/docs/content/guides/database/tables.mdx @@ -504,7 +504,7 @@ Now you can create tables inside the `private` schema: ```sql create table private.salaries ( id bigint generated by default as identity primary key, - salary bigint not null, + salary numeric not null, actor_id bigint not null references public.actors ); ``` @@ -519,6 +519,15 @@ A custom schema isn't reachable through the Supabase Data API until you expose i Reference material for choosing a column type. +### Choosing a type + +Postgres offers several near-equivalent types for the same job. These defaults are safe: + +- **Timestamps:** prefer `timestamptz` over `timestamp`. `timestamptz` records the instant and renders it in the session's time zone. `timestamp` stores only the date and time fields, so the same stored value means different moments to clients in different zones. Reach for `timestamp` when you mean a wall-clock time rather than an instant, such as a 9 a.m. opening time that holds in every location. +- **Text:** prefer `text` over `varchar(n)`. The two use the same storage representation, and `text` has no declared limit to migrate later. Add a check constraint when you need to bound the length. +- **Money and other exact decimals:** prefer `numeric`. `real` and `double precision` can't represent values such as `0.10` exactly, so totals drift as they accumulate. `money` is exact, but its fractional precision and formatting follow the server's `lc_monetary` setting, so the same value reads differently on another server. +- **Identifiers:** prefer `bigint` over `integer`. An `integer` tops out at 2,147,483,647, and an identity column doesn't reuse the values it skips, so a table reaches that ceiling before it holds that many rows. + ### Data types Every column has a data type. Postgres provides many [default types](https://www.postgresql.org/docs/current/datatype.html), and you can design your own or use extensions if the default types don't fit your needs. You can use any data type that Postgres supports via the SQL editor. The Table Editor supports a subset of these, which keeps the experience focused for people with less database experience.