2 Commits

Include renames

Author	SHA1	Message	Date
Miranda Limonczenko	d8b0a3e87f	docs(database): make the guide's snippets run in document order (#50822) ... Part 3 of 4 in stack #50823. This PR carries **technical revision only**: claims that produce a wrong outcome for a reader. ## Problem This PR came from running a technical assessment using `/test-the-docs`. A reader pastes the guide top to bottom. Two snippets fail. The `planets` table uses a `serial` primary key, then the seed sets ids explicitly. Explicit ids don't advance the sequence, so it stays at 0. The `add_planet('Jakku')` example then draws id 1, which the seed already used: ``` ERROR: duplicate key value violates unique constraint "planets_pkey" DETAIL: Key (id)=(1) already exists. ``` The `security definer` example re-creates `hello_world` with `create` rather than `create or replace`, so it collides with the function from Basic functions: ``` ERROR: function "hello_world" already exists with same argument types ``` The Data tab spells the planet Tatooine. The SQL tab spells it Tattoine. Two debugging snippets read `attendance_table` and `some_table`. No fence creates either, and neither is marked as omitted. ## Solution - **Seeds `planets` and `people` without explicit ids.** The sequence advances, so `add_planet` succeeds. This also settles Tattoine against Tatooine. - **Uses `create or replace` in the definer example**, so it no longer collides. - **Marks the two assumed tables** in the debugging snippets with a comment. - **Points the CREATE FUNCTION link at the current Postgres docs.** It pointed at 9.1, while the intro already links the current version of the same page. **Verification.** I ran every `sql` fence from the guide in document order against Postgres 15 in a throwaway container, with `anon` and `authenticated` created first. Before these changes, two fences errored. After them, the sequence runs clean. ## Manual testing 1. Start a throwaway Postgres: `docker run --rm -d --name pgcheck -e POSTGRES_PASSWORD=pw postgres:15`. 2. Create the Supabase roles the guide references: `docker exec -i pgcheck psql -U postgres -c "create role anon; create role authenticated;"`. 3. Paste every `sql` block from the guide, in page order, into `docker exec -i pgcheck psql -U postgres`. No statement errors. 4. Run `select * from planets;`. Tatooine, Alderaan, Kashyyyk, and Jakku, with sequential ids. 5. Remove it: `docker rm -f pgcheck`. ## Preview links | Site | Live | Preview | Search for | | --- | --- | --- | --- | | Docs | [/docs/guides/database/functions](https://supabase.com/docs/guides/database/functions) | [/docs/guides/database/functions](https://docs-git-docs-functions-technical-supabase.vercel.app/docs/guides/database/functions) | `('Tatooine')` | | Docs | New page, 404 in production | [/docs/guides/database/debugging-functions](https://docs-git-docs-functions-technical-supabase.vercel.app/docs/guides/database/debugging-functions) | `assumes an attendance_table` | <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Clarified the required column types in database function examples. - Expanded guidance on function return values, including `INSERT`, `UPDATE`, and `DELETE` statements with `RETURNING` clauses. - Updated SQL examples to show table creation and automatically generated IDs, corrected the spelling of “Tatooine,” and refreshed the PostgreSQL reference link. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-10-05 15:18:00 -07:00
Miranda Limonczenko	8b148f93c1	docs(database): regroup the database functions guide and split out debugging (#50821) ... Part 2 of 4 in stack #50823. This PR carries **structure only**: moves, regrouping, and the connective text the new shape needs. Reworded prose already landed in #50820. ## Problem This PR is running a structure edit. A reader arrives from search and has to find one thing. The guide gave them eight top-level headings, no grouping, and no opening outline. The style guide caps a group at 5 ± 1. Four of those headings are the action path: Getting started, Basic functions, Returning data sets, and Passing parameters. Nothing marked them as one sequence. `Suggestions` held four unrelated things: an Edge Functions comparison, two security topics, and a three-part debugging reference. The heading names nothing the reader is doing. Debugging was the largest thing on the page. It sat at H3 with three H4 children, and it shared only the word "function" with the rest of the guide. ## Solution - **Groups the four procedures** under `Create a database function`, so the action path is one unbroken sequence. - **Moves the Edge Functions comparison ahead of the procedures.** A reader choosing between the two needs it before the steps, not after them. - **Groups the two security sections** under `Secure a database function`. - **Splits debugging onto its own page**, `guides/database/debugging-functions`. It is registered in the Database sidebar and cross-referenced from the guide. - **Folds `Deep dive` into `Resources`.** Two trailing headings did one job. - **Adds an opening outline** linking each group and saying when to use it. - **Renames the frontmatter title** to sentence case, `Database functions`. ## Manual testing 1. Open the [guide on the deploy preview](https://docs-git-docs-functions-structure-supabase.vercel.app/docs/guides/database/functions). Five top-level headings, with the opening outline linking each group. 2. Open the [new debugging page](https://docs-git-docs-functions-structure-supabase.vercel.app/docs/guides/database/debugging-functions). It appears in the Database sidebar under Managing database functions. 3. Follow a repointed link. Open [Postgres log config](https://docs-git-docs-functions-structure-supabase.vercel.app/docs/guides/database/postgres/postgres-log-config) and click Database Function Logging. It lands on the new page at General logging. 4. Run `pnpm build:guides-markdown` from `apps/docs`. Both pages appear under `public/markdown/guides/database/`. Discard the `manifest.json` change. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added a guide to debugging Postgres database functions, with examples for logging, error handling, and inspecting query results. * Added the guide to Database navigation and updated related resources to link to it. * Reorganized the database functions guide to clarify function creation, security, and privileges. <!-- end of auto-generated comment: release notes by coderabbit.ai --> ## Preview links | Site | Live | Preview | Search for | | --- | --- | --- | --- | | Docs | [/docs/guides/database/functions](https://supabase.com/docs/guides/database/functions) | [/docs/guides/database/functions](https://docs-git-docs-functions-structure-supabase.vercel.app/docs/guides/database/functions) | `Secure a database function` | | Docs | New page, 404 in production | [/docs/guides/database/debugging-functions](https://docs-git-docs-functions-structure-supabase.vercel.app/docs/guides/database/debugging-functions) | `Debugging database functions` | | Docs | [/docs/guides/database/postgres/postgres-log-config](https://supabase.com/docs/guides/database/postgres/postgres-log-config) | [/docs/guides/database/postgres/postgres-log-config](https://docs-git-docs-functions-structure-supabase.vercel.app/docs/guides/database/postgres/postgres-log-config) | `Database Function Logging` | ## Review instructions This PR moves content. The risk is a broken link, not bad prose. 1. Open the preview of the guide. Count the top-level headings in the right-hand outline. There are five, down from eight. 2. Read the four bullets at the top of the page. Each links to a group, and each says when to use it. Click all four and confirm each lands on its section. 3. Open the new debugging page from the second row. Confirm it appears in the left sidebar under **Managing database functions**. 4. **Check the three locked anchors.** Append each to the preview guide URL and confirm the page jumps: `#quick-demo`, `#security-definer-vs-invoker`. Then append `#general-logging` to the **debugging page** URL. Four other pages link to these. 5. Open the Postgres log config preview from the third row. Find **Database Function Logging** in the Resources list and click it. It lands on the new debugging page, not on a dead anchor. 6. Compare the prose against the live page. **No sentence should have changed** beyond the new opening outline and the cross-reference to the debugging page. **If you only have two minutes:** do steps 4 and 5. A moved section that leaves a dead anchor is the failure this PR could cause. **A note on running SQL from this page.** Don't hand-paste from the rendered page. Blocks are split across tabs, and the Data tab in Returning data sets holds markdown tables that look pasteable but are not SQL. Use the `.md` export of the page, which flattens every tab in page order. #50822 has a copy-paste command for this.	2026-10-05 15:18:00 -07:00