From 4d57edd6227dded0d9e55d6d1c1809d8926d63f6 Mon Sep 17 00:00:00 2001 From: Miranda Limonczenko Date: Mon, 14 Sep 2026 19:50:23 -0700 Subject: [PATCH] docs(database): add data type guidance to the tables guide (#50025) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refs FDBKIN-4668 Part 5 of a 5-PR stack on `apps/docs/content/guides/database/tables.mdx`. Builds on #50024. ## Problem Reader feedback in FDBKIN-4668 reports developers mixing `timestamptz` and `timestamp` across production schemas for lack of guidance. This PR adds the guidance half of that ask. The issue also asks for linting in the schema designer, which is a Frontend change and stays open. The page listed 44 data types and recommended neither side of any pair a reader actually has to choose between: `timestamp` or `timestamptz`, `varchar` or `text`, `numeric` or `float`, `integer` or `bigint`. No example on the page had a timestamp column at all, and `timestamptz` appeared only inside the reference table. ## Solution Adds a short "Choosing a type" section to the Reference group, stating a safe default for each pair and why. Also changes `salary bigint` to `salary numeric` in the private schema example. That line was checked against the wrong-outcome test in #50023 and deliberately left there, because a reader storing cents in a `bigint` gets a working table. It changes here because **this branch is what makes it wrong**: once the page recommends `numeric` for money, an example doing the opposite two screens away teaches the reader the opposite of what the page just said. ## Manual testing Preview: https://docs-git-docs-tables-datatypes-supabase.vercel.app/docs/guides/database/tables#choosing-a-type 1. Open the preview at that anchor. "Choosing a type" renders above the data type table. 2. Open `#data-types` on the same preview. It still lands on the reference table, which Studio deep-links to from three components. 3. In a local database, insert `1234.56` into `private.salaries.salary` and select `salary * 3`. Returns `3703.68` exactly. ## Verification (`test-the-docs`) Run in the Compose sandbox against a local stack. | Check | Result | | --- | --- | | `create table private.salaries` with `salary numeric` | pass | | `insert ... values (1234.56, ...)` then `select salary, salary * 3` | pass — returns `1234.56` and `3703.68`, exact | The same example failed to run at all before this stack, because `public.actors` didn't exist on the page's path. #50023 fixes that. ## Summary by CodeRabbit - **Documentation** - Updated the Postgres tables guide with practical guidance for choosing column types. - Added recommendations for timestamps, text, monetary and decimal values, and identifiers. - Updated the example salary column to use the `numeric` type instead of `bigint`. - Expanded the column type reference section to help readers select appropriate types for common data. --- apps/docs/content/guides/database/tables.mdx | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) 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.