The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
docs(database): regroup the database functions guide and split out debugging (#50821)
Miranda Limonczenko8b148f93c104
diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.tsindex 17022d54b9b..0f7c3bb734a 100644--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts@@ -1099,6 +1099,10 @@ export const database: NavMenuConstant = {name: 'Managing database functions',url: '/guides/database/functions' as `/${string}`,},+ {+ name: 'Debugging database functions',+ url: '/guides/database/debugging-functions' as `/${string}`,+ },{name: 'Managing database triggers',url: '/guides/database/postgres/triggers' as `/${string}`,diff --git a/apps/docs/content/guides/database/debugging-functions.mdx b/apps/docs/content/guides/database/debugging-functions.mdxnew file mode 100644index 00000000000..669f6c4e0ab--- /dev/null+++ b/apps/docs/content/guides/database/debugging-functions.mdx@@ -0,0 +1,173 @@+---+id: 'debugging-functions'+title: 'Debugging database functions'+description: 'Logging and error handling inside Postgres functions.'+---++Add logs and error handling to a database function so you can see what it does at runtime. Logs matter most in a complex function.++For how to write and call a function, see [Database functions](/docs/guides/database/functions).++Good targets to log include:++- Values of (non-sensitive) variables+- Returned results from queries++## General logging++Use the `raise` keyword to write custom logs to the [Postgres logs](/dashboard/project/_/logs/postgres-logs) in the Dashboard. Three severity levels appear by default:++- `log`+- `warning`+- `exception` (error level)++```sql+create function logging_example(+ log_message text,+ warning_message text,+ error_message text+)+returns void+language plpgsql+as $$+begin+ raise log 'logging message: %', log_message;+ raise warning 'logging warning: %', warning_message;++ -- immediately ends function and reverts transaction+ raise exception 'logging error: %', error_message;+end;+$$;++select logging_example('LOGGED MESSAGE', 'WARNING MESSAGE', 'ERROR MESSAGE');+```++## Error handling++You can create custom errors with the `raise exception` keywords.++A common pattern is to throw an error when a variable doesn't meet a condition:++```sql+create or replace function error_if_null(some_val text)+returns text+language plpgsql+as $$+begin+ -- error if some_val is null+ if some_val is null then+ raise exception 'some_val should not be NULL';+ end if;+ -- return some_val if it is not null+ return some_val;+end;+$$;++select error_if_null(null);+```++Value checking is common, so Postgres provides the `assert` keyword as a shorthand. It takes the following format:++```sql+-- throw error when condition is false+assert <some condition>, 'message';+```++For example:++```sql+create function assert_example(name text)+returns uuid+language plpgsql+as $$+declare+ student_id uuid;+begin+ -- save a user's id into the user_id variable+ select+ id into student_id+ from attendance_table+ where student = name;++ -- throw an error if the student_id is null+ assert student_id is not null, 'assert_example() ERROR: student not found';++ -- otherwise, return the user's id+ return student_id;+end;+$$;++select assert_example('Harry Potter');+```++You can also capture and modify an error message with the `exception` keyword:++```sql+create function error_example()+returns void+language plpgsql+as $$+begin+ -- fails: cannot read from nonexistent table+ select * from table_that_does_not_exist;++ exception+ when others then+ raise exception 'An error occurred in function <function name>: %', sqlerrm;+end;+$$;+```++## Advanced logging++For a more complex function, or for harder debugging, log the following:++- Formatted variables+- Individual rows+- Start and end of function calls++```sql+create or replace function advanced_example(num int default 10)+returns text+language plpgsql+as $$+declare+ var1 int := 20;+ var2 text;+begin+ -- Logging start of function+ raise log 'logging start of function call: (%)', (select now());++ -- Logging a variable from a SELECT query+ select+ col_1 into var1+ from some_table+ limit 1;+ raise log 'logging a variable (%)', var1;++ -- It is also possible to avoid using variables, by returning the values of your query to the log+ raise log 'logging a query with a single return value(%)', (select col_1 from some_table limit 1);++ -- If necessary, you can even log an entire row as JSON+ raise log 'logging an entire row as JSON (%)', (select to_jsonb(some_table.*) from some_table limit 1);++ -- When using INSERT or UPDATE, the new value(s) can be returned+ -- into a variable.+ -- When using DELETE, the deleted value(s) can be returned.+ -- All three operations use "RETURNING value(s) INTO variable(s)" syntax+ insert into some_table (col_2)+ values ('new val')+ returning col_2 into var2;++ raise log 'logging a value from an INSERT (%)', var2;++ return var1 || ',' || var2;+exception+ -- Handle exceptions here if needed+ when others then+ raise exception 'An error occurred in function <advanced_example>: %', sqlerrm;+end;+$$;++select advanced_example();+```diff --git a/apps/docs/content/guides/database/extensions/pgaudit.mdx b/apps/docs/content/guides/database/extensions/pgaudit.mdxindex 7514e339dea..e67f1f4bc91 100644--- a/apps/docs/content/guides/database/extensions/pgaudit.mdx+++ b/apps/docs/content/guides/database/extensions/pgaudit.mdx@@ -344,7 +344,7 @@ To prevent PGAudit from monitoring the problematic roles, you'll want to change### Using PGAudit to debug database functions-Technically yes, but it is not the best approach. It is better to check out our [function debugging guide](/docs/guides/database/functions#general-logging) instead.+Technically yes, but it is not the best approach. It is better to check out our [function debugging guide](/docs/guides/database/debugging-functions#general-logging) instead.### Downloading database logs@@ -387,6 +387,6 @@ PGAudit's [official documentation](https://www.pgaudit.org) focuses on system an## Resources- [Official `PGAudit` documentation](https://www.pgaudit.org)-- [Database Function Logging](/docs/guides/database/functions#general-logging)+- [Database Function Logging](/docs/guides/database/debugging-functions#general-logging)- [Supabase Logging](/docs/guides/observability/logs)- [Self-Hosting Logs](/docs/reference/self-hosting-analytics/introduction)diff --git a/apps/docs/content/guides/database/functions.mdx b/apps/docs/content/guides/database/functions.mdxindex b077f4c036a..e4d01bbc927 100644--- a/apps/docs/content/guides/database/functions.mdx+++ b/apps/docs/content/guides/database/functions.mdx@@ -1,6 +1,6 @@---id: 'functions'-title: 'Database Functions'+title: 'Database functions'description: 'Creating and using Postgres functions.'video: 'https://www.youtube.com/v/MJZCCpCYEqk'---@@ -8,11 +8,24 @@ video: 'https://www.youtube.com/v/MJZCCpCYEqk'Postgres has built-in support for [SQL functions](https://www.postgresql.org/docs/current/sql-createfunction.html).These functions live inside your database, and you can call them from your app with [`rpc()`](../../reference/javascript/rpc).+- [Database functions vs Edge Functions](#database-functions-vs-edge-functions) compares the two. Start here if you aren't sure which one fits.+- [Create a database function](#create-a-database-function) has the steps, from a one-line function to one that takes parameters.+- [Secure a database function](#secure-a-database-function) covers which user the function runs as and who can call it.+- [Debugging database functions](/docs/guides/database/debugging-functions) covers logging and error handling.+## Quick demo<YouTube id="MJZCCpCYEqk" title="Creating and calling Postgres functions" />-## Getting started+## Database functions vs Edge Functions++For data-intensive operations, use database functions. They run inside your database, and you can call them remotely with the [REST and GraphQL API](../api).++For use cases that need low latency, use [Edge Functions](../../guides/functions). They're globally distributed and you write them in TypeScript.++## Create a database function++### Getting startedCreate a database function from the Dashboard, or write the SQL yourself against a[direct connection](../../guides/database/connecting-to-postgres).@@ -24,7 +37,7 @@ To use the Dashboard:3. Enter the SQL that creates or replaces your database function.4. Click **Run**. You can also press `cmd+enter` or `ctrl+enter`.-## Basic functions [#simple-functions]+### Basic functions [#simple-functions]Create a basic database function that returns the string "hello world".@@ -141,7 +154,7 @@ Reference: [`Rpc()`](../../reference/csharp/rpc)</$Show></Tabs>-## Returning data sets+### Returning data setsA database function can also return a data set from a [table](../../guides/database/tables) or a view.@@ -156,7 +169,7 @@ For example, take a database holding some Star Wars data:><TabPanel id="data" label="Data">-### Planets+#### Planets```| id | name |@@ -166,7 +179,7 @@ For example, take a database holding some Star Wars data:| 3 | Kashyyyk |```-### People+#### People```| id | name | planet_id |@@ -291,7 +304,7 @@ data = supabase.rpc('get_planets').eq('id', 1).execute()</$Show></Tabs>-## Passing parameters+### Passing parametersCreate a function that inserts a new planet into the `planets` table and returns the new ID. This function uses the `plpgsql` language.@@ -408,13 +421,7 @@ await supabase.Rpc("add_planet", new Dictionary<string, object> { { "name", "Jak</$Show></Tabs>-## Suggestions--### Database Functions vs Edge Functions--For data-intensive operations, use database functions. They run inside your database, and you can call them remotely with the [REST and GraphQL API](../api).--For use cases that need low latency, use [Edge Functions](../../guides/functions). They're globally distributed and you write them in TypeScript.+## Secure a database function### Security `definer` vs `invoker`@@ -469,174 +476,6 @@ By default, any role can run a database function. You can restrict execution ingrant execute on function public.hello_world to authenticated;```-### Debugging functions--Add logs to help you debug a function. Logs matter most in a complex function.--Good targets to log include:--- Values of (non-sensitive) variables-- Returned results from queries--#### General logging--Use the `raise` keyword to write custom logs to the [Postgres logs](/dashboard/project/_/logs/postgres-logs) in the Dashboard. Three severity levels appear by default:--- `log`-- `warning`-- `exception` (error level)--```sql-create function logging_example(- log_message text,- warning_message text,- error_message text-)-returns void-language plpgsql-as $$-begin- raise log 'logging message: %', log_message;- raise warning 'logging warning: %', warning_message;-- -- immediately ends function and reverts transaction- raise exception 'logging error: %', error_message;-end;-$$;--select logging_example('LOGGED MESSAGE', 'WARNING MESSAGE', 'ERROR MESSAGE');-```--#### Error handling--You can create custom errors with the `raise exception` keywords.--A common pattern is to throw an error when a variable doesn't meet a condition:--```sql-create or replace function error_if_null(some_val text)-returns text-language plpgsql-as $$-begin- -- error if some_val is null- if some_val is null then- raise exception 'some_val should not be NULL';- end if;- -- return some_val if it is not null- return some_val;-end;-$$;--select error_if_null(null);-```--Value checking is common, so Postgres provides the `assert` keyword as a shorthand. It takes the following format:--```sql--- throw error when condition is false-assert <some condition>, 'message';-```--For example:--```sql-create function assert_example(name text)-returns uuid-language plpgsql-as $$-declare- student_id uuid;-begin- -- save a user's id into the user_id variable- select- id into student_id- from attendance_table- where student = name;-- -- throw an error if the student_id is null- assert student_id is not null, 'assert_example() ERROR: student not found';-- -- otherwise, return the user's id- return student_id;-end;-$$;--select assert_example('Harry Potter');-```--You can also capture and modify an error message with the `exception` keyword:--```sql-create function error_example()-returns void-language plpgsql-as $$-begin- -- fails: cannot read from nonexistent table- select * from table_that_does_not_exist;-- exception- when others then- raise exception 'An error occurred in function <function name>: %', sqlerrm;-end;-$$;-```--#### Advanced logging--For a more complex function, or for harder debugging, log the following:--- Formatted variables-- Individual rows-- Start and end of function calls--```sql-create or replace function advanced_example(num int default 10)-returns text-language plpgsql-as $$-declare- var1 int := 20;- var2 text;-begin- -- Logging start of function- raise log 'logging start of function call: (%)', (select now());-- -- Logging a variable from a SELECT query- select- col_1 into var1- from some_table- limit 1;- raise log 'logging a variable (%)', var1;-- -- It is also possible to avoid using variables, by returning the values of your query to the log- raise log 'logging a query with a single return value(%)', (select col_1 from some_table limit 1);-- -- If necessary, you can even log an entire row as JSON- raise log 'logging an entire row as JSON (%)', (select to_jsonb(some_table.*) from some_table limit 1);-- -- When using INSERT or UPDATE, the new value(s) can be returned- -- into a variable.- -- When using DELETE, the deleted value(s) can be returned.- -- All three operations use "RETURNING value(s) INTO variable(s)" syntax- insert into some_table (col_2)- values ('new val')- returning col_2 into var2;-- raise log 'logging a value from an INSERT (%)', var2;-- return var1 || ',' || var2;-exception- -- Handle exceptions here if needed- when others then- raise exception 'An error occurred in function <advanced_example>: %', sqlerrm;-end;-$$;--select advanced_example();-```-## Resources- Official Client libraries: [JavaScript](../../reference/javascript/rpc) and [Flutter](../../reference/dart/rpc)@@ -644,16 +483,14 @@ select advanced_example();- Postgres Official Docs: [Chapter 9. Functions and Operators](https://www.postgresql.org/docs/current/functions.html)- Postgres Reference: [CREATE FUNCTION](https://www.postgresql.org/docs/9.1/sql-createfunction.html)-## Deep dive--### Create Database Functions+### Create a database function in the Dashboard<YouTube id="MJZCCpCYEqk" title="Creating a Postgres function in the dashboard" />-### Call Database Functions using JavaScript+### Call a database function from JavaScript<YouTube id="I6nnp9AINJk" title="Calling a Postgres function from JavaScript" />-### Using Database Functions to call an external API+### Call an external API from a database function<YouTube id="rARgrELRCwY" title="Calling an external API from a Postgres function" />diff --git a/apps/docs/content/guides/database/postgres/postgres-log-config.mdx b/apps/docs/content/guides/database/postgres/postgres-log-config.mdxindex f820fd05687..f31dc184de4 100644--- a/apps/docs/content/guides/database/postgres/postgres-log-config.mdx+++ b/apps/docs/content/guides/database/postgres/postgres-log-config.mdx@@ -823,16 +823,16 @@ Determines what _query generated_ logs (not background or networking logs) are rAs an example of how `log_min_messages` works, if the setting were changed to `error`, Postgres would stop recording logs with the severity levels `warning`, `notice`, `info`, and `debug1 ... debug5` events. However, it would continue recording all `error`, `log`, `fatal`, and `panic` occurrences.-| Severity | Description | Example log |-| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| **debug1 ... debug5** | Successively detailed debugging and server info, predominantly used by Postgres developers and extension maintainers. | `DEBUG1: rehashing catalog cache id 6...` |-| **info** | Information explicitly requested by the user during an operation. | `INFO: analyzing "public.example..."` <br/><br/> Example returned by the [`analyze verbose`](https://www.postgresql.org/docs/current/sql-analyze.html) command |-| **notice** | Helpful, non-essential information about automatic background actions. | `NOTICE: table "old_logs" does not exist, skipping` <br/><br/> Example returned by the [`drop table if exists`](https://www.postgresql.org/docs/current/sql-droptable.html) commands |-| **warning** | A query completed, but skipped requested actions. | `WARNING: no privileges were granted for "some_user"` <br/><br/> Example returned by the [`grant`](https://www.postgresql.org/docs/current/sql-grant.html) command |-| **error** | A specific query failed, but the overall database connection remains alive. | `ERROR: duplicate key value violates unique constraint "example_pkey"` |-| **log** | Operational events. Usually generated by [background activity log settings](/docs/guides/database/postgres/postgres-log-config#background-activity) or by [database functions](/docs/guides/database/functions?queryGroups=language&language=js#debugging-functions) | `LOG: connection received...` |-| **fatal** | An error that causes a database connection to abruptly terminate. | `FATAL: terminating connection due to administrator command` |-| **panic** | A critical, system-wide failure that forces the database to shut down and crash-recover. | `PANIC: could not locate a valid checkpoint record at 0/61013608` |+| Severity | Description | Example log |+| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| **debug1 ... debug5** | Successively detailed debugging and server info, predominantly used by Postgres developers and extension maintainers. | `DEBUG1: rehashing catalog cache id 6...` |+| **info** | Information explicitly requested by the user during an operation. | `INFO: analyzing "public.example..."` <br/><br/> Example returned by the [`analyze verbose`](https://www.postgresql.org/docs/current/sql-analyze.html) command |+| **notice** | Helpful, non-essential information about automatic background actions. | `NOTICE: table "old_logs" does not exist, skipping` <br/><br/> Example returned by the [`drop table if exists`](https://www.postgresql.org/docs/current/sql-droptable.html) commands |+| **warning** | A query completed, but skipped requested actions. | `WARNING: no privileges were granted for "some_user"` <br/><br/> Example returned by the [`grant`](https://www.postgresql.org/docs/current/sql-grant.html) command |+| **error** | A specific query failed, but the overall database connection remains alive. | `ERROR: duplicate key value violates unique constraint "example_pkey"` |+| **log** | Operational events. Usually generated by [background activity log settings](/docs/guides/database/postgres/postgres-log-config#background-activity) or by [database functions](/docs/guides/database/debugging-functions) | `LOG: connection received...` |+| **fatal** | An error that causes a database connection to abruptly terminate. | `FATAL: terminating connection due to administrator command` |+| **panic** | A critical, system-wide failure that forces the database to shut down and crash-recover. | `PANIC: could not locate a valid checkpoint record at 0/61013608` |<Admonition type="note">@@ -931,5 +931,5 @@ Review the [pgAudit docs](/docs/guides/database/extensions/pgaudit) for more con## Resources- [Advanced Log Filtering](/docs/guides/observability/advanced-log-filtering)-- [Database Function Logging](/docs/guides/database/functions#general-logging)+- [Database Function Logging](/docs/guides/database/debugging-functions#general-logging)- [Supabase Logging](/docs/guides/observability/logs)diff --git a/apps/docs/content/troubleshooting/how-to-interpret-and-explore-the-postgres-logs-OuCIOj.mdx b/apps/docs/content/troubleshooting/how-to-interpret-and-explore-the-postgres-logs-OuCIOj.mdxindex d588c5a938f..c0ab18146cb 100644--- a/apps/docs/content/troubleshooting/how-to-interpret-and-explore-the-postgres-logs-OuCIOj.mdx+++ b/apps/docs/content/troubleshooting/how-to-interpret-and-explore-the-postgres-logs-OuCIOj.mdx@@ -369,7 +369,7 @@ By default, only failed queries are logged. The [PGAudit extension](/docs/guides#### Logging within database functions-To track or debug functions, logging can be configured by following the [function debugging guide](/docs/guides/database/functions#general-logging)+To track or debug functions, logging can be configured by following the [function debugging guide](/docs/guides/database/debugging-functions#general-logging)## Frequently Asked Questions@@ -389,7 +389,7 @@ To see the default types of events that are logged, you can check this [guide](h- [Regex for filtering logs](https://github.com/orgs/supabase/discussions/22640)- [Debugging with the DB API logs](https://github.com/orgs/supabase/discussions/22849)-- [Debugging Database Functions](/docs/guides/database/functions#debugging-functions)+- [Debugging Database Functions](/docs/guides/database/debugging-functions)- [pg_audit](/docs/guides/database/extensions/pgaudit)- [Supabase Logging](/docs/guides/observability/logs)- [Self-Hosting Logs](/docs/reference/self-hosting-analytics/introduction)diff --git a/apps/docs/content/troubleshooting/understanding-postgresql-logging-levels-and-how-they-impact-your-project-KXiJRm.mdx b/apps/docs/content/troubleshooting/understanding-postgresql-logging-levels-and-how-they-impact-your-project-KXiJRm.mdxindex 83159679774..4f6ca7227c6 100644--- a/apps/docs/content/troubleshooting/understanding-postgresql-logging-levels-and-how-they-impact-your-project-KXiJRm.mdx+++ b/apps/docs/content/troubleshooting/understanding-postgresql-logging-levels-and-how-they-impact-your-project-KXiJRm.mdx@@ -117,4 +117,4 @@ We support PGAudit extension, which extends Postgres’s built-in logging capabiFor detailed configuration instructions and logging options, refer to the complete documentation: [PGAudit Configuration Guide](/docs/guides/database/extensions/pgaudit?queryGroups=database-method&database-method=dashboard#configure-the-extension)**c. Debugging Functions**-For more information on how to debug functions in Supabase, refer to the official guide: [Debugging Functions](/docs/guides/database/functions?queryGroups=language&language=js#debugging-functions).+For more information on how to debug functions in Supabase, refer to the official guide: [Debugging Functions](/docs/guides/database/debugging-functions).