From 513f1e1bd94f697039e491074c598606c1742891 Mon Sep 17 00:00:00 2001 From: Saxon Fletcher Date: Fri, 19 Jun 2026 13:06:59 +1000 Subject: [PATCH 1/2] Remove monaco outline (#47102) Removes an always on clipped outline in editor. Will look at focus styles as part of editor refactor. ## Summary by CodeRabbit * **Style** * Updated the code editor styling to provide a cleaner visual presentation by refining outline properties. --- apps/studio/styles/monaco.css | 1 + 1 file changed, 1 insertion(+) diff --git a/apps/studio/styles/monaco.css b/apps/studio/styles/monaco.css index 959851fdf0a19..fc59de11691de 100644 --- a/apps/studio/styles/monaco.css +++ b/apps/studio/styles/monaco.css @@ -25,6 +25,7 @@ .monaco-diff-editor { --vscode-editor-background: hsl(var(--background-dash-sidebar)) !important; --vscode-editorGutter-background: hsl(var(--background-dash-sidebar)) !important; + outline: none !important; } .gutter { From 801244463acda506b4797f303e67cb3a048ecafa Mon Sep 17 00:00:00 2001 From: Miranda Limonczenko Date: Thu, 18 Jun 2026 20:42:45 -0700 Subject: [PATCH 2/2] chore(docs) Demote h1s in the doc body to avoid multiple h1s (#47061) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes DOCS-875 **Before:** Screenshot 2026-06-17 at 2 19 31 PM **Caption:** "Errors" at the bottom of the screen is just as large as the title. The right sidebar shows h3s. Source: https://supabase.com/docs/guides/database/prisma/prisma-troubleshooting#solution-server-has-closed-the-connection **After:** Screenshot 2026-06-17 at 2 20 44 PM **Caption:** The "Errors" at the bottom of the screen is smaller than the main h1. The right drops the "Solutions" headers. Source: https://docs-git-demote-h1s-in-body-docs-supabase.vercel.app/docs/guides/database/prisma/prisma-troubleshooting#solution-server-has-closed-the-connection ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## Problem The `title` frontmatter generates an `h1`. However, several pages have multiple h1s. ## Fix This PR demotes pages with h1s in the markdown body to h2s and so on. See [a troubleshooting page in production](https://supabase.com/docs/guides/troubleshooting/supabase--your-network-ipv4-and-ipv6-compatibility-cHe3BP) and in [in preview](https://docs-git-demote-h1s-in-body-docs-supabase.vercel.app/docs/guides/troubleshooting/supabase--your-network-ipv4-and-ipv6-compatibility-cHe3BP). ## Future improvements Possibly, we can add a linting rule to prevent this in the future. We'd also want to check that the heading hierarchy is always consistent. ## Summary by CodeRabbit ## Summary by CodeRabbit * **Documentation** * Updated multiple guides and troubleshooting articles to enforce consistent heading hierarchy and improved section nesting for clearer in-page structure. * Refreshed troubleshooting pages with cleaner table of contents and navigation, including added guide links and re-leveled subsections. * Reformatted Prisma troubleshooting content (including a deprecated redirect) without changing the underlying guidance. * Added a warning about manually setting database connection limits and adjusted related warning/formatting across the max-connections guide. --------- Co-authored-by: Nik Richers --- .../prisma/prisma-troubleshooting.mdx | 42 ++++++------- apps/docs/content/guides/database/testing.mdx | 10 ++-- .../backup-restore.mdx | 36 +++++------ apps/docs/content/guides/security.mdx | 6 +- .../guides/security/soc-2-compliance.mdx | 12 ++-- .../content/guides/telemetry/log-drains.mdx | 18 +++--- .../disabling-prepared-statements-qL8lEL.mdx | 12 ++-- ...rpreting-api-errors-in-the-logs-7xREI9.mdx | 24 ++++---- ...change-max-database-connections-_BQ8P5.mdx | 14 ++--- ...t-and-explore-the-postgres-logs-OuCIOj.mdx | 60 +++++++++---------- ...ing-supabase-grafana-cpu-charts-9JSlkC.mdx | 6 +- .../pgcron-debugging-guide-n1KTaz.mdx | 22 +++---- .../prisma-error-management-Cm5P_o.mdx | 36 +++++------ ...00-status-authentication-errors-7bU5U8.mdx | 42 ++++++------- ...-query-performance-with-indexes-q8PoC9.mdx | 6 +- ...ork-ipv4-and-ipv6-compatibility-cHe3BP.mdx | 16 ++--- 16 files changed, 181 insertions(+), 181 deletions(-) diff --git a/apps/docs/content/guides/database/prisma/prisma-troubleshooting.mdx b/apps/docs/content/guides/database/prisma/prisma-troubleshooting.mdx index ff3757e0eab09..4918a182eb219 100644 --- a/apps/docs/content/guides/database/prisma/prisma-troubleshooting.mdx +++ b/apps/docs/content/guides/database/prisma/prisma-troubleshooting.mdx @@ -25,15 +25,15 @@ These options, called "query parameters," can be used to address specific errors connection_string.../postgres?KEY1=VALUE&KEY2=VALUE&KEY3=VALUE ``` -# Errors +## Errors {/* supa-mdx-lint-disable-next-line Rule001HeadingCase */} -## ... prepared statement already exists +### Prepared statement already exists Supavisor in transaction mode (port 6543) does not support [prepared statements](https://www.postgresql.org/docs/current/sql-prepare.html), which Prisma will try to create in the background. -### Solution: [#solution-prepared-statement-exists] +#### Solution: [#solution-prepared-statement-exists] - Add `pgbouncer=true` to the connection string. This turns off prepared statements in Prisma. @@ -43,17 +43,17 @@ Supavisor in transaction mode (port 6543) does not support [prepared statements] --- -## Can't reach database server at: +### Can't reach the database server -Prisma couldn't establish a connection with Postgres or Supavisor before the timeout +Prisma couldn't establish a connection with Postgres or Supavisor before the timeout. -### Possible causes: [#possible-causes-cant-reach-database-server-at] +#### Possible causes: [#possible-causes-cant-reach-database-server-at] - **Database overload**: The database server is under heavy load, causing Prisma to struggle to connect. - **Malformed connection string**: The connection string used by Prisma is incorrect or incomplete. - **Transient network issues**: Temporary network problems are disrupting the connection. -### Solutions: [#solution-cant-reach-database-server-at] +#### Solutions: [#solution-cant-reach-database-server-at] - **Check database health**: Use the [Observability Dashboard](/dashboard/project/_/observability/database) to monitor CPU, memory, and I/O usage. If the database is overloaded, consider increasing your [compute size](/docs/guides/platform/compute-add-ons) or [optimizing your queries](/docs/guides/database/query-optimization). - **Verify connection string**: Double-check the connection string in your Prisma configuration to ensure it matches in your [project connect page](/dashboard/project/_?showConnect=true). @@ -65,17 +65,17 @@ Prisma couldn't establish a connection with Postgres or Supavisor before the tim --- -## Timed out fetching a new connection from the connection pool: +### Timed out fetching a new connection from the connection pool Prisma is unable to allocate connections to pending queries fast enough to meet demand. -### Possible causes: [#possible-causes-timed-out-fetching-a-new-connection] +#### Possible causes: [#possible-causes-timed-out-fetching-a-new-connection] - **Overwhelmed server**: The server hosting Prisma is under heavy load, limiting its ability to manage connections. By default, Prisma will create the default `num_cpus * 2 + 1` worth of connections. A common cause for server strain is increasing the `connection_limit` significantly past the default. - **Insufficient pool size**: The Supavisor pooler does not have enough connections available to quickly satisfy Prisma's requests. - **Slow queries**: Prisma's queries are taking too long to execute, preventing it from releasing connections for reuse. -### Solutions: [#solution-timed-out-fetching-a-new-connection] +#### Solutions: [#solution-timed-out-fetching-a-new-connection] - **Increase the pool timeout**: Increase the `pool_timeout` parameter in your Prisma configuration to give the pooler more time to allocate connections. - **Reduce the connection limit**: If you've explicitly increased the `connection_limit` parameter in your Prisma configuration, try reducing it to a more reasonable value. @@ -85,43 +85,43 @@ Prisma is unable to allocate connections to pending queries fast enough to meet --- -## Server has closed the connection +### Server has closed the connection According to this [GitHub Issue for Prisma](https://github.com/prisma/prisma/discussions/7389), this error may be related to large return values for queries. It may also be caused by significant database strain. -### Solutions: [#solution-server-has-closed-the-connection] +#### Solutions: [#solution-server-has-closed-the-connection] - **Limit row return sizes**: Try to limit the total amount of rows returned for particularly large requests. - **Minimize database strain**:Check the Reports Page for database strain. If there is obvious strain, consider [optimizing](/docs/guides/database/query-optimization) or increasing compute size --- -## Drift detected: Your database schema is not in sync with your migration history +### Drift detected: Your database schema is not in sync with your migration history Prisma relies on migration files to ensure your database aligns with Prisma's model. External schema changes are detected as "drift", which Prisma will try to overwrite, potentially causing data loss. -### Possible causes: [#possible-causes-your-database-schema-is-not-in-sync] +#### Possible causes: [#possible-causes-your-database-schema-is-not-in-sync] - **Supabase Managed Schemas**: Supabase may update managed schemas like auth and storage to introduce new features. Granting Prisma access to these schemas can lead to drift during updates. - **External Schema Modifications**: Your team or another tool might have modified the database schema outside of Prisma, causing drift. -### Solution: [#solution-your-database-schema-is-not-in-sync] +#### Solution: [#solution-your-database-schema-is-not-in-sync] - **Baselining migrations**: [baselining](https://www.prisma.io/docs/orm/prisma-migrate/workflows/baselining) re-syncs Prisma by capturing the current database schema as the starting point for future migrations. --- -## Max client connections reached +### Max client connections reached Postgres or Supavisor rejected a request for more connections -### Possible causes:[#possible-causes-max-client-connections-reached] +#### Possible causes:[#possible-causes-max-client-connections-reached] - **When working in transaction mode (port 6543):** The error "Max client connections reached" occurs when clients try to form more connections with the pooler than it can support. - **When working in session mode (port 5432):** The max amount of clients is restricted to the "Pool Size" value in the [Database Settings](/dashboard/project/_/database/settings). If the "Pool Size" is set to 15, even if the pooler can handle 200 client connections, it will still be effectively capped at 15 for each unique ["database-role+database" combination](https://github.com/orgs/supabase/discussions/21566). - **When working with direct connections**: Postgres is already servicing the max amount of connections -### Solutions [#solutions-causes-max-client-connections-reached] +#### Solutions [#solutions-causes-max-client-connections-reached] - **Transaction Mode for serverless apps**: If you are using serverless functions (Supabase Edge, Vercel, AWS Lambda), switch to transaction mode (port 6543). It handles more connections than session mode or direct connections. - **Reduce the number of Prisma connections**: A single client-server can establish multiple connections with a pooler. Typically, serverless setups do not need many connections. Starting with fewer, like five or three, or even just one, is often sufficient. In serverless setups, begin with `connection_limit=1`, increasing cautiously if needed to avoid maxing out connections. @@ -132,15 +132,15 @@ Postgres or Supavisor rejected a request for more connections --- -## Cross schema references are only allowed when the target schema is listed in the schemas property of your data-source +### Cross schema references are only allowed when the target schema is listed in the schemas property of your data-source A Prisma migration is referencing a schema it is not permitted to manage. -### Possible causes: [#possible-causes-cross-schema-references] +#### Possible causes: [#possible-causes-cross-schema-references] - A migration references a schema that Prisma is not permitted to manage -### Solutions: [#solutions-cross-schema-references] +#### Solutions: [#solutions-cross-schema-references] - Multi-schema support: If the external schema isn't Supabase managed, list the relevant schemas on the `datasource` block in your `schema.prisma` file. diff --git a/apps/docs/content/guides/database/testing.mdx b/apps/docs/content/guides/database/testing.mdx index a4e93b38eeb55..17c9a5abd3e95 100644 --- a/apps/docs/content/guides/database/testing.mdx +++ b/apps/docs/content/guides/database/testing.mdx @@ -10,13 +10,13 @@ To ensure that queries return the expected data, RLS policies are correctly appl - Secondly, you can test through the Supabase CLI, which is a more low-level approach where you write tests in SQL. -# Testing using the Supabase CLI +## Testing using the Supabase CLI You can use the Supabase CLI to test your database. The minimum required version of the CLI is [v1.11.4](https://github.com/supabase/cli/releases). To get started: - [Install the Supabase CLI](/docs/guides/cli) on your local machine -## Creating a test +### Creating a test Create a tests folder inside the `supabase` folder: @@ -30,7 +30,7 @@ Create a new file with the `.sql` extension which will contain the test. touch ./supabase/tests/database/hello_world.test.sql ``` -## Writing tests +### Writing tests All `sql` files use [pgTAP](/docs/guides/database/extensions/pgtap) as the test runner. @@ -51,7 +51,7 @@ select * from finish(); rollback; ``` -## Running tests +### Running tests To run the test, you can use: @@ -69,7 +69,7 @@ Files=1, Tests=1, 1 wallclock secs ( 0.01 usr 0.00 sys + 0.04 cusr 0.02 csys Result: PASS ``` -## More resources +### More resources - [Testing RLS policies](/docs/guides/database/extensions/pgtap#testing-rls-policies) - [pgTAP extension](/docs/guides/database/extensions/pgtap) diff --git a/apps/docs/content/guides/platform/migrating-within-supabase/backup-restore.mdx b/apps/docs/content/guides/platform/migrating-within-supabase/backup-restore.mdx index 8bcf027f60656..c686e8ca188a9 100644 --- a/apps/docs/content/guides/platform/migrating-within-supabase/backup-restore.mdx +++ b/apps/docs/content/guides/platform/migrating-within-supabase/backup-restore.mdx @@ -4,9 +4,9 @@ subtitle: 'Learn how to backup and restore projects using the Supabase CLI' breadcrumb: 'Migrations' --- -# Migrating the database +## Migrating the database -## Backup database using the CLI +### Back up database using the CLI @@ -74,7 +74,7 @@ breadcrumb: 'Migrations' -## Before you begin +### Before you begin -## Restore backup using CLI +### Restore backup using CLI @@ -197,9 +197,9 @@ breadcrumb: 'Migrations' -## Special considerations +### Special considerations -#### Preserving migration history +##### Preserving migration history If you were using Supabase CLI for managing migrations on your old database and would like to preserve the migration history in your newly restored project, you need to insert the migration records separately using the following commands. @@ -214,7 +214,7 @@ psql \ --dbname "$NEW_DB_URL" ``` -#### Schema changes to `auth` and `storage` +##### Schema changes to `auth` and `storage` If you have modified the `auth` and `storage` schemas in your old project, such as adding triggers or Row Level Security(RLS) policies, you have to restore them separately. The Supabase CLI can help you diff the changes to these schemas using the following commands. @@ -223,13 +223,13 @@ supabase link --project-ref "$OLD_PROJECT_REF" supabase db diff --linked --schema auth,storage > changes.sql ``` -## Troubleshooting notes +### Troubleshooting notes -#### Disabling triggers during restore: +##### Disabling triggers during restore: Setting `session_replication_role` to `replica` disables triggers during the migration, preventing columns from being double encrypted. -#### Custom roles require passwords +##### Custom roles require passwords If you created any [custom roles](/dashboard/project/_/database/roles) with the `LOGIN` attribute, you must manually set their passwords in the new project. This can be done with the SQL command: @@ -237,7 +237,7 @@ If you created any [custom roles](/dashboard/project/_/database/roles) with the alter user "YOUR_USER" with password 'SOME_NEW_PASSWORD'; ``` -#### `supabase_admin` permission errors +##### `supabase_admin` permission errors If you encounter permission errors related to `supabase_admin` during restore: @@ -248,7 +248,7 @@ If you encounter permission errors related to `supabase_admin` during restore: ALTER ... OWNER TO "supabase_admin" ``` -#### `cli_login_postgres` role grant error +##### `cli_login_postgres` role grant error If you encounter the error: @@ -264,7 +264,7 @@ DETAIL: Only roles with the ADMIN option on role "postgres" may grant this role GRANT "postgres" TO "cli_login_postgres" WITH INHERIT FALSE GRANTED BY "supabase_admin"; ``` -#### `cli_login_postgres` role issues after cloning +##### `cli_login_postgres` role issues after cloning The `cli_login_role` must be created by the `supabase_admin` role. If the migration process cloned over the role before the CLI could generate its own version, it may encounter the error: @@ -279,9 +279,9 @@ To resolve the issue, drop the custom `cli_login_postgres` role. Then the CLI ca DROP ROLE IF EXISTS cli_login_postgres; ``` -# Migrating edge functions +## Migrating edge functions -## Steps (using the Supabase CLI): +### Steps (using the Supabase CLI): @@ -326,7 +326,7 @@ DROP ROLE IF EXISTS cli_login_postgres; -## Steps (using the Supabase Dashboard): +### Steps (using the Supabase Dashboard): @@ -369,7 +369,7 @@ Dependencies defined through [import maps](/docs/guides/functions/dependencies#u -# Migrating storage objects +## Migrating storage objects @@ -808,6 +808,6 @@ Dependencies defined through [import maps](/docs/guides/functions/dependencies#u -## Resources +### Resources - [Connecting with PSQL](/docs/guides/database/psql) diff --git a/apps/docs/content/guides/security.mdx b/apps/docs/content/guides/security.mdx index 0e95b4c0dd46c..5f0e5c810499f 100644 --- a/apps/docs/content/guides/security.mdx +++ b/apps/docs/content/guides/security.mdx @@ -8,20 +8,20 @@ hideToc: true Supabase is a hosted platform to get you started without needing to manage any infrastructure yourself. The hosted platform comes with many security and compliance controls managed by Supabase. -# Compliance +## Compliance Supabase is SOC 2 Type 2 compliant and regularly audited. All projects at Supabase are governed by the same set of compliance controls. The [SOC 2 Compliance Guide](/docs/guides/security/soc-2-compliance) explains Supabase's SOC 2 responsibilities and controls in more detail. The [HIPAA Compliance Guide](/docs/guides/security/hipaa-compliance) explains Supabase's HIPAA responsibilities. Additional [security and compliance controls](/docs/guides/deployment/shared-responsibility-model#managing-healthcare-data) for projects that deal with electronic Protected Health Information (ePHI) and require HIPAA compliance are available through the HIPAA add-on. -# Platform configuration +## Platform configuration As a hosted platform, Supabase provides additional security controls to further enhance the security posture depending on organizations' own requirements or obligations. These can be found under the [dedicated security page](/dashboard/org/_/security) under organization settings. And are described in greater detail [here](/docs/guides/security/platform-security). -# Product configuration +## Product configuration Each product offered by Supabase comes with customizable security controls and these security controls help ensure that applications built on Supabase are secure, compliant, and resilient against various threats. diff --git a/apps/docs/content/guides/security/soc-2-compliance.mdx b/apps/docs/content/guides/security/soc-2-compliance.mdx index d9fa83916ba3a..073dd07e5b7f2 100644 --- a/apps/docs/content/guides/security/soc-2-compliance.mdx +++ b/apps/docs/content/guides/security/soc-2-compliance.mdx @@ -21,32 +21,32 @@ Our [HIPAA documentation](/docs/guides/security/hipaa-compliance) provides more -# Meeting compliance requirements +## Meeting compliance requirements SOC 2 compliance is a critical aspect of data security for Supabase and our customers. Being fully SOC 2 compliant is a shared responsibility and here’s a breakdown of the responsibilities for both parties: -### Supabase responsibilities +#### Supabase responsibilities 1. **Security Measures**: Supabase implements robust security controls to protect customer data. These includes measures to prevent data breaches and ensure the confidentiality and integrity of the information managed and stored by the platform. Supabase is obliged to be vigilant about security risks and must demonstrate that our security measures meet industry standards through regular audits. 2. **Compliance Audits**: Supabase undergoes SOC 2 audits yearly to verify that our data management practices comply with the Trust Services Criteria (TSC), which include security, availability, processing integrity, confidentiality, and privacy. These audits are conducted by an independent third party. 3. **Incident Response**: Supabase has an incident response plan in place to handle data breaches efficiently. This plan outlines how the organization detects issues, responds to incidents, and manages system vulnerabilities. 4. **Reporting**: Upon a successful audit, Supabase receive a SOC 2 report that details our compliance status. This report is available to customers as a SOC 2 Type 2 report, and allows customers and stakeholders to assure that Supabase has implemented adequate and the requisite safeguards to protect sensitive information. -### Customer responsibilities +#### Customer responsibilities 1. **Compliance Requirements**: Understand your own compliance requirements. While SOC 2 compliance is not a legal requirement, many enterprise customers require their providers to have a SOC 2 report. This is because it provides assurance that the provider has implemented robust controls to protect customer data. 2. **Due Diligence**: Customers must perform due diligence when selecting Supabase as a provider. This includes reviewing the SOC 2 Type 2 report to ensure that Supabase meets the expected security standards. Customers should also understand the division of responsibilities between themselves and Supabase to avoid duplication of effort. 3. **Monitoring and Review**: Customers should regularly monitor and review Supabase’s compliance status. 4. **Control Compliance**: If a customer needs to be SOC 2 compliant, they should themselves implement the requisite controls and undergo a SOC 2 audit. -### Shared responsibilities +#### Shared responsibilities 1. **Data Security**: Both customers and Supabase share the responsibility of ensuring data security. While the Supabase, as the provider, implements the security controls, the customer must ensure that their use of the Supabase platform does not compromise these controls. 2. **Control Compliance**: Supabase asserts through our SOC 2 that all requisite security controls are met. Customers wishing to also be SOC 2 compliant need to go through their own SOC 2 audit, verifying that security controls are met on the customer's side. In summary, SOC 2 compliance involves a shared responsibility between Supabase and our customers to ensure the security and integrity of data. Supabase, as a provider, must implement and maintain robust security measures, customers must perform due diligence and monitor Supabase's compliance status, while also implement their own compliance controls to protect their sensitive information. -## Frequently asked questions +### Frequently asked questions **How often is Supabase SOC 2 audited?** @@ -78,7 +78,7 @@ While SOC 2 itself does not mandate specific data residency requirements, organi SOC 2 is non-industry specific and provides a framework for the security and privacy of data. This is however not sufficient in most cases when dealing with Protected Healthcare Information (PHI), which requires additional privacy and legal controls. When dealing with PHI in the United States or for United States customers, HIPAA is mandatory. -## Resources +### Resources 1. [System and Organization Controls: SOC Suite of Services](https://www.aicpa-cima.com/resources/landing/system-and-organization-controls-soc-suite-of-services) 2. [Shared Responsibility Model](/docs/guides/deployment/shared-responsibility-model) diff --git a/apps/docs/content/guides/telemetry/log-drains.mdx b/apps/docs/content/guides/telemetry/log-drains.mdx index c2c7d069aef02..a00f0519eff6c 100644 --- a/apps/docs/content/guides/telemetry/log-drains.mdx +++ b/apps/docs/content/guides/telemetry/log-drains.mdx @@ -8,7 +8,7 @@ Log drains send all logs of the Supabase stack to one or more desired destinatio You can read about the initial announcement [here](/blog/log-drains) and vote for your preferred drains in [this discussion](https://github.com/orgs/supabase/discussions/28324?sort=top). -# Supported destinations +## Supported destinations The following table lists the supported destinations and the required setup configuration: @@ -23,7 +23,7 @@ The following table lists the supported destinations and the required setup conf HTTP requests are batched with a max of 250 logs or 1 second intervals, whichever happens first. Logs are compressed via Gzip if the destination supports it. -## Generic HTTP endpoint +### Generic HTTP endpoint Logs are sent as a POST request with a JSON body. Both HTTP/1 and HTTP/2 protocols are supported. Custom headers can optionally be configured for all requests. @@ -138,7 +138,7 @@ Deno.serve(async (req) => { -## Datadog logs +### Datadog logs Logs sent to Datadog have the name of the log source set on the `service` field of the event and the source set to `Supabase`. Logs are gzipped before they are sent to Datadog. @@ -187,7 +187,7 @@ To setup Datadog log drain, generate a Datadog API key [here](https://app.datado If you are interested in other log drains, upvote them [here](https://github.com/orgs/supabase/discussions/28324) -## Loki +### Loki Logs sent to the Loki HTTP API are specifically formatted according to the HTTP API requirements. See the official Loki HTTP API documentation for [more details](https://grafana.com/docs/loki/latest/reference/loki-http-api/#ingest-logs). @@ -199,7 +199,7 @@ The `event_message` and `timestamp` fields will be dropped from the events to av Loki must be configured to accept **structured metadata**, and it is advised to increase the default maximum number of structured metadata fields to at least 500 to accommodate large log event payloads of different products. -## Sentry +### Sentry Logs are sent to Sentry as part of [Sentry's Logging Product](https://docs.sentry.io/product/explore/logs/). Ingesting Supabase logs as Sentry errors is currently not supported. @@ -213,7 +213,7 @@ All fields from the log event are attached as attributes to the Sentry log, whic If you are self-hosting Sentry, Sentry Logs are only supported in self-hosted version [25.9.0](https://github.com/getsentry/self-hosted/releases/tag/25.9.0) and later. -## Axiom +### Axiom Logs sent to a specified Axiom's dataset as JSON of a raw log event, with timestamp modified to be parsed by ingestion endpoint. @@ -227,7 +227,7 @@ To set up the Axiom log drain, you have to: - API token 4. Watch for events in the Stream panel of Axiom Console -## Amazon S3 +### Amazon S3 Logs are written to an existing S3 bucket that you own. @@ -245,7 +245,7 @@ Ensure the AWS account tied to the Access Key ID has permissions to write to the -## OpenTelemetry protocol (OTLP) +### OpenTelemetry protocol (OTLP) Logs are sent to any OTLP-compatible endpoint using the OpenTelemetry Protocol over HTTP with Protocol Buffers encoding. @@ -352,6 +352,6 @@ Refer to your observability platform's documentation for specific authentication -## Pricing +### Pricing For a detailed breakdown of how charges are calculated, refer to [Manage Log Drain usage](/docs/guides/platform/manage-your-usage/log-drains). diff --git a/apps/docs/content/troubleshooting/disabling-prepared-statements-qL8lEL.mdx b/apps/docs/content/troubleshooting/disabling-prepared-statements-qL8lEL.mdx index fa187a3db9dbc..bddc58bf5f7cd 100644 --- a/apps/docs/content/troubleshooting/disabling-prepared-statements-qL8lEL.mdx +++ b/apps/docs/content/troubleshooting/disabling-prepared-statements-qL8lEL.mdx @@ -13,7 +13,7 @@ database_id = "04801b69-e7eb-4f40-8d41-81110397bbc2" Each ORM or library configures prepared statements differently. Here are settings for some common ones. If you don't see yours, make a comment -# Prisma: +## Prisma: add ?pgbouncer=true to end of connection string: @@ -21,7 +21,7 @@ add ?pgbouncer=true to end of connection string: postgres://[db-user].[project-ref]:[db-password]@aws-0-[aws-region].pooler.supabase.com:6543/[db-name]?pgbouncer=true ``` -# Drizzle: +## Drizzle: Add a prepared false flag to the client: @@ -29,7 +29,7 @@ Add a prepared false flag to the client: export const client = postgres(connectionString, { prepare: false }) ``` -# Node Postgres +## Node Postgres [Just omit the "name" value in a query definition](https://node-postgres.com/features/queries#prepared-statements): @@ -41,16 +41,16 @@ const query = { } ``` -# Psycopg +## Psycopg set the [prepare_threshold](https://www.psycopg.org/psycopg3/docs/api/connections.html#psycopg.Connection.prepare_threshold) to `None`. -# asyncpg +## asyncpg Follow the recommendation in the [asyncpg docs](https://magicstack.github.io/asyncpg/current/faq.html#why-am-i-getting-prepared-statement-errors) > disable automatic use of prepared statements by passing `statement_cache_size=0` to [asyncpg.connect()](https://magicstack.github.io/asyncpg/current/api/index.html#asyncpg.connection.connect) and [asyncpg.create_pool()](https://magicstack.github.io/asyncpg/current/api/index.html#asyncpg.pool.create_pool) (and, obviously, avoid the use of [Connection.prepare()](https://magicstack.github.io/asyncpg/current/api/index.html#asyncpg.connection.Connection.prepare)); -# Rust's Deadpool or `tokio-postgres`: +## Rust's Deadpool or `tokio-postgres`: - Check [GitHub Discussion](https://github.com/bikeshedder/deadpool/issues/340#event-13642472475) diff --git a/apps/docs/content/troubleshooting/discovering-and-interpreting-api-errors-in-the-logs-7xREI9.mdx b/apps/docs/content/troubleshooting/discovering-and-interpreting-api-errors-in-the-logs-7xREI9.mdx index 7fa689324a8ed..252b274381a42 100644 --- a/apps/docs/content/troubleshooting/discovering-and-interpreting-api-errors-in-the-logs-7xREI9.mdx +++ b/apps/docs/content/troubleshooting/discovering-and-interpreting-api-errors-in-the-logs-7xREI9.mdx @@ -9,7 +9,7 @@ database_id = "188986c9-019d-4f26-baaf-6f58cec8fa7a" > A complimentary [guide](https://github.com/orgs/supabase/discussions/26224) was made for the Postgres logs -# Navigating the API logs: +## Navigating the API logs: The Database API is powered by a [ PostgREST web-server](https://postgrest.org/en/v12/), recording every request to the API Edge Network logs. To precisely navigate them, use the [Log Explorer](/dashboard/project/_/logs/explorer). These logs are managed through [Logflare](/blog/supabase-logs-self-hosted) and can be queried with a subset of BigQuery SQL syntax. @@ -45,9 +45,9 @@ The most useful fields for debugging are: > NOTE: not every field is included below. For a full list, check the API Edge field reference in the [Log Explorer](/dashboard/project/_/logs/explorer) -## Request object +### Request object -### Cloudflare geographic data: +#### Cloudflare geographic data: **Suggested use cases:** @@ -79,7 +79,7 @@ cross join unnest(request) AS request; cross join unnest(cf) AS cf; ``` -### IP and browser/environment data: +#### IP and browser/environment data: **Suggested use cases:** @@ -107,7 +107,7 @@ cross join unnest(request) AS request; cross join unnest(headers) AS headers; ``` -### Query type and formatting data: +#### Query type and formatting data: **Suggested use cases:** @@ -137,9 +137,9 @@ cross join unnest(request) AS request; cross join unnest(sb) AS sb; ``` -## Response object +### Response object -### Status code: +#### Status code: **Suggested use cases:** @@ -162,9 +162,9 @@ from cross join unnest(response) as response; ``` -# Finding errors +## Finding errors -### API level errors +#### API level errors The `metadata.request.url` contains PostgREST formatted queries. @@ -213,7 +213,7 @@ where PostgREST has an [error reference table](https://postgrest.org/en/v12/references/errors.html) that you can use to interpret status codes. -### Database-level errors +#### Database-level errors However, some errors that are reported through the Database API occur at the Postgres level. If it is not clear which error occurred you should reference the timestamp of the error and try to see if you can find it in the Postgres logs. @@ -248,11 +248,11 @@ limit 100; Like PostgREST, Postgres has a [reference table](https://www.postgresql.org/docs/current/errcodes-appendix.html) for interpreting error codes. -## PostgREST server and Cloudflare errors +### PostgREST server and Cloudflare errors In some cases, errors may emerge because of Cloudflare or PostgREST server errors. For 500 and above errors, you may want to check your [PostgREST](/dashboard/project/_/logs/postgrest-logs) logs and the [Cloudflare docs.](https://developers.cloudflare.com/support/troubleshooting/cloudflare-errors/troubleshooting-cloudflare-5xx-errors/#error-502-bad-gateway-or-error-504-gateway-timeout)) -# Practical examples: +## Practical examples: **Find All Errors:** diff --git a/apps/docs/content/troubleshooting/how-to-change-max-database-connections-_BQ8P5.mdx b/apps/docs/content/troubleshooting/how-to-change-max-database-connections-_BQ8P5.mdx index 42a667aaeb8e7..e1c69e3ee291a 100644 --- a/apps/docs/content/troubleshooting/how-to-change-max-database-connections-_BQ8P5.mdx +++ b/apps/docs/content/troubleshooting/how-to-change-max-database-connections-_BQ8P5.mdx @@ -12,7 +12,7 @@ cli = [ "supabase-postgres-config-update" ] > WARNING: Manually configuring the connection count hard codes it. This means if you upgrade or downgrade your database, the connection count will not auto-resize. You will have to make sure to manually update it. -# Changing max database connections: +## Changing max database connections Each compute instance has a default direct connection and pooler connection settings. You can find the most recent settings in the [compute docs](/docs/guides/platform/compute-add-ons#disk-io): @@ -30,7 +30,7 @@ Each compute instance has a default direct connection and pooler connection sett | 12XL | 500 | 9,000 | | 16XL | 500 | 12,000 | -## Configuring direct connections limits +### Configuring direct connections limits > Note: the Supavisor connection limits are hard-coded and cannot be changed without upgrading the compute size: @@ -50,21 +50,21 @@ Then you could run the following SQL in the SQL Editor to see if the changes wen SHOW max_connections; ``` -# Dangers of increasing the direct connection limits +## Dangers of increasing the direct connection limits **Three** factors must be taken into consideration when adjusting the direct connection limit: -### Process schedulers and Postgres internals: +#### Process schedulers and Postgres internals Allowing too many direct connections in your database can overburden Postgres schedulers and other internal modules. This will result in a noticeable decrease in query throughput, despite having more connections available. EnterpriseDB wrote a wonderful [article](https://www.enterprisedb.com/postgres-tutorials/why-you-should-use-connection-pooling-when-setting-maxconnections-postgres) that outlines some of the considerations. The default connection values are set based on a solid understanding of Postgres architecture, and straying too far from them is _likely_ to hinder performance. However, with some experimentation, you might discover a value better suited to your specific needs. Still, unless there's a compelling reason to adjust the setting, it's generally advisable to stick with the defaults or change the values judiciously.' -### Memory +#### Memory > If you do not know how to monitor memory and CPU with Supabase Grafana, [check here](https://github.com/orgs/supabase/discussions/27141). -#### Each direct connection is a running process that will consume active memory +##### Each direct connection is a running process that will consume active memory This is a Grafana Chart of unhealthy memory usage: @@ -92,7 +92,7 @@ select ) || ' * ' || current_setting('maintenance_work_mem') || ')) / ' || current_setting('work_mem'); ``` -### CPU +#### CPU The below chart is an example of what can occur to the CPU if 100s of connections are inappropriately opened/closed every second or many CPU intensive queries are run in parallel 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.mdx index 18f13fae035ae..811abe5dc6309 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 @@ -8,11 +8,11 @@ database_id = "8b000bb4-180b-4a6c-b280-ba02965060f6" > A complimentary guide was made for the [API logs](https://github.com/orgs/supabase/discussions/22849) -# Debugging and monitoring Postgres with logs +## Debugging and monitoring Postgres with logs Logs provide insights into Postgres operations. They help meet compliance requirements, detect suspicious activity, and troubleshoot problems. -## Table of contents +### Table of contents - Querying Logs - `postgres_logs` Table Structure @@ -33,7 +33,7 @@ Logs provide insights into Postgres operations. They help meet compliance requir - Frequently Asked Questions - Other resources -## Querying logs +### Querying logs The most practical way to explore and filter logs is through the [Logs Explorer](/dashboard/project/_/logs/explorer). @@ -47,7 +47,7 @@ Although there are many strategies to filter logs, such as `like` and `in` state The `postgres_logs` table contains Postgres events. -### `postgres_logs` table structure +#### `postgres_logs` table structure The table contains 3 fundamental columns: @@ -73,9 +73,9 @@ cross join unnest(metadata) AS metadata cross join unnest(parsed) AS parsed; ``` -### Parsed metadata fields +#### Parsed metadata fields -#### Query information +##### Query information | Field | Description | Example | | --------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------- | @@ -88,7 +88,7 @@ cross join unnest(parsed) AS parsed; - Identifying slow queries - Identifying failing queries -#### Error/Warning information +##### Error/Warning information | Field | Description | Example | | --------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | @@ -103,7 +103,7 @@ cross join unnest(parsed) AS parsed; - Filter by error severity or SQL code - Get hints, details, and context about error events -#### Connection/Identification information +##### Connection/Identification information | Field | Description | Example | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | @@ -124,9 +124,9 @@ cross join unnest(parsed) AS parsed; - Filter connections by sessions for debugging - identify extension events -## Filtering logs +### Filtering logs -### Excluding routine events +#### Excluding routine events Most Postgres logs during normal periods are routine events, such as connection authorizations and checkpoints. To see the default types of events that are logged, you can check this [guide](https://gist.github.com/TheOtherBrian1/991d32c2b00dbc75d29b80d4cdf41aa7). @@ -139,7 +139,7 @@ where not regexp_contains(event_message, '^cron|PgBouncer|checkpoint|connection received|authenticated|authorized'); ``` -### By timeframe +#### By timeframe To investigate issues around a specific period: @@ -150,7 +150,7 @@ where timestamp between '2024-05-06 04:44:00' and '2024-05-06 04:45:00' ``` -### By error severity +#### By error severity This filter finds all errors, fatals, and panics: @@ -169,7 +169,7 @@ where Failure events include an sql_state_code that can be referenced in the [Postgres Docs](https://www.postgresql.org/docs/current/errcodes-appendix.html) -### By query +#### By query > NOTE: Unless pg_audit is configured, only failed queries are logged @@ -187,11 +187,11 @@ Queries can use complex syntax, so it is often helpful to isolate by referenced - `^`: look for values at start of string - `|`: or operator -## By APIs/roles +### By APIs/roles All failed queries, including those from PostgREST, Auth, and external libraries (e.g., Prisma) are logged with helpful error messages for debugging. -#### Server/Role mapping +##### Server/Role mapping API servers have assigned database roles for connecting to the database: @@ -217,7 +217,7 @@ where ... ``` -## By Dashboard queries +### By Dashboard queries Queries from the Supabase Dashboard are executed under the `postgres` role and include the comment `-- source: dashboard`. To isolate or exclude Dashboard requests during debugging, you can filter by this comment. @@ -228,7 +228,7 @@ where regexp_contains(parsed.query, '-- source: dashboard') ``` -## Full example for finding errors +### Full example for finding errors ```sql select @@ -255,9 +255,9 @@ order by timestamp desc limit 100; ``` -# Logging for compliance and security +## Logging for compliance and security -### Customized object and role activity logging +#### Customized object and role activity logging > ⚠️ NOTE: This is specifically designated for those using the `postgres` role or [custom roles](/docs/guides/database/postgres/roles) to interact with their database. Those using the Database REST API should reference the [Database API Logging Guide](https://github.com/orgs/supabase/discussions/22849) instead. @@ -279,7 +279,7 @@ where parsed.user_name = 'API_role' ``` -### Filtering by IP +#### Filtering by IP > If you are connecting from a known, limited range of IP addresses, you should enable [network restrictions](/docs/guides/platform/network-restrictions). @@ -306,7 +306,7 @@ order by ip_count desc limit 100; ``` -# Reviewing log settings +## Reviewing log settings The `pg_settings` table describes system and logging configurations. @@ -337,11 +337,11 @@ where and name like '%log%'; ``` -## Changing log settings +### Changing log settings > WARNING: lenient settings can lead to over-logging, impacting database performance while creating noise in the logs. -#### Severity levels +##### Severity levels The `log_min_messages` variable determines what is severe enough to log. Here are the severity thresholds from the [Postgres docs](https://www.postgresql.org/docs/current/runtime-config-logging.html). @@ -365,7 +365,7 @@ alter role postgres set log_min_messages = ''; show log_min_messages; -- default WARNING ``` -#### Configuring queries logged +##### Configuring queries logged By default, only failed queries are logged. The [PGAudit extension](/docs/guides/database/extensions/pgaudit) extends Postgres's built-in logging abilities. It can be used to selectively track all queries in your database by: @@ -374,25 +374,25 @@ By default, only failed queries are logged. The [PGAudit extension](/docs/guides - database object - entire database -#### Logging within database functions +##### 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) -# Frequently Asked Questions +## Frequently Asked Questions -#### How to join different log tables +##### How to join different log tables No, log tables are independent from each other and do not share any primary/foreign key relations for joining. -#### How to download logs +##### How to download logs At the moment, the way to download logs is through the Log Dashboard as a CSV -#### What is logged? +##### What is logged? To see the default types of events that are logged, you can check this [guide](https://gist.github.com/TheOtherBrian1/991d32c2b00dbc75d29b80d4cdf41aa7). -### Other resources: +#### Other resources: - [Regex for filtering logs](https://github.com/orgs/supabase/discussions/22640) - [Debugging with the DB API logs](https://github.com/orgs/supabase/discussions/22849) diff --git a/apps/docs/content/troubleshooting/interpreting-supabase-grafana-cpu-charts-9JSlkC.mdx b/apps/docs/content/troubleshooting/interpreting-supabase-grafana-cpu-charts-9JSlkC.mdx index 7d49046e4a06d..940c7afc7d426 100644 --- a/apps/docs/content/troubleshooting/interpreting-supabase-grafana-cpu-charts-9JSlkC.mdx +++ b/apps/docs/content/troubleshooting/interpreting-supabase-grafana-cpu-charts-9JSlkC.mdx @@ -9,7 +9,7 @@ database_id = "ef05da0a-f8bc-44a4-9719-5ae811dba104" > [Guide](/docs/guides/monitoring-troubleshooting/metrics#deploying-supabase-grafana) for setting up Supabase Grafana -# CPU +## CPU Here are examples of unhealthy CPU utilization: @@ -25,13 +25,13 @@ The CPU chart shows 4 distinct metrics of interest: As the CPU peaks towards 100%, queries and database tasks will begin to throttle, as they won't have enough time or access to the CPU. -### Other useful Supabase Grafana guides: +#### Other useful Supabase Grafana guides: - [Connections](https://github.com/orgs/supabase/discussions/27141) - [Disk](https://github.com/orgs/supabase/discussions/27003) - [Memory](https://github.com/orgs/supabase/discussions/27021) -### Optimizing: +#### Optimizing 1. [Optimize your queries](/docs/guides/database/query-optimization). 2. [Add indexes](https://github.com/orgs/supabase/discussions/22449) if possible. diff --git a/apps/docs/content/troubleshooting/pgcron-debugging-guide-n1KTaz.mdx b/apps/docs/content/troubleshooting/pgcron-debugging-guide-n1KTaz.mdx index 7c027809550af..5269a1661dca3 100644 --- a/apps/docs/content/troubleshooting/pgcron-debugging-guide-n1KTaz.mdx +++ b/apps/docs/content/troubleshooting/pgcron-debugging-guide-n1KTaz.mdx @@ -9,7 +9,7 @@ database_id = "9a55c946-877f-46ae-8b57-51934e02a36c" This is a general guide for debugging pg_cron. Below lists issues and how to debug them -# Cannot create/edit/delete cron jobs +## Cannot create/edit/delete cron jobs Cron jobs can only be modified with the respective SQL functions: @@ -23,13 +23,13 @@ If you are trying to make changes, use the cron functions. If the cron functions --- -# Cron Jobs are not running +## Cron Jobs are not running > You should consider initiating a software upgrade in the [Infrastructure Settings](/dashboard/project/_/settings/infrastructure) if your Postgres version is below v15.6.1.122. Upgrading will give you access to pg_cron v1.6.4+, which has many bug fixes and auto-revive capabilities. -## Debugging steps: +### Debugging steps: -### Check to see if "pg_cron scheduler" is active +#### Check to see if `pg_cron scheduler` is active pg_cron operates as the `pg_cron scheduler` process within Postgres. Use the below query to check if the worker is active @@ -56,7 +56,7 @@ If the query does not return a row, the worker has died. To revive it, you must
-### Check the `cron.job_run_details` table for more information +#### Check the `cron.job_run_details` table for more information pg_cron creates logs in its own table `cron.job_run_details`. The below query checks for issues from the past 5 days : @@ -77,7 +77,7 @@ Respond to the errors exposed appropriately.
-### Check if there are too many cron jobs running concurrently +#### Check if there are too many cron jobs running concurrently pg_cron supports up to 32 concurrent jobs, each using a database connection. If too many jobs are running simultaneously, space them out to prevent connection overload and job failure. @@ -110,7 +110,7 @@ You can view your concurrent peak connection usage throughout the day at the bot
-### Check for database strain +#### Check for database strain Unfortunately, excessive resource strain can slow down or disrupt jobs. @@ -125,7 +125,7 @@ It is important to make sure you are running the latest release of pg_cron (1.6.
-### Check the log explorer for more information +#### Check the log explorer for more information Although pg*cron records errors in the `cron.job_run_details` table, in rare cases, more information can be found in the general Postgres logs. You can check the [Log Explorer](/dashboard/project/*/logs/explorer) for failure events with the following query @@ -156,7 +156,7 @@ If you're interested in modifying the query, there is an advanced [guide](https:
-### Create custom logs within cron jobs +#### Create custom logs within cron jobs If it's still not clear what is occurring you may be able to capture more logs by running the pg_cron query inside a database function: @@ -188,12 +188,12 @@ You can then search for your custom messages in the [Logs Interface](/dashboard/
-### Upgrading pg_cron version +#### Upgrading pg_cron version The current version of pg*cron on Supabase is 1.6.4. It comes with a [few bug fixes](https://github.com/citusdata/pg_cron/releases/tag/v1.6.4). You should consider upgrading to Postgres v15.6.1.122+ in the[ Infrastructure Settings](/dashboard/project/*/settings/infrastructure) to get the latest extension.
-### Contacting support and the maintainers +#### Contacting support and the maintainers Although Supabase includes the extension, it is maintained by Citus (a Microsoft subsidiary). You can contact Support for more help, but you should also consider creating an issue in the [pg_cron repo](https://github.com/citusdata/pg_cron). diff --git a/apps/docs/content/troubleshooting/prisma-error-management-Cm5P_o.mdx b/apps/docs/content/troubleshooting/prisma-error-management-Cm5P_o.mdx index 17f7609587088..430d7d11e0c19 100644 --- a/apps/docs/content/troubleshooting/prisma-error-management-Cm5P_o.mdx +++ b/apps/docs/content/troubleshooting/prisma-error-management-Cm5P_o.mdx @@ -27,7 +27,7 @@ message = "Drift detected: Your database schema is not in sync with your migrati > This guide has been deprecated. Use the troubleshooting guide in the [Supabase docs](/docs/guides/database/prisma/prisma-troubleshooting). -# Addressing specific errors: +## Addressing specific errors Prisma, unlike other libraries, uses [query parameters for configurations](https://www.prisma.io/docs/orm/overview/databases/postgresql#arguments). @@ -37,7 +37,7 @@ Some can be used to address specific errors and can be appended to end of your c .../postgres?KEY1=VALUE&KEY2=VALUE&KEY3=VALUE ``` -## `Can't reach database server at`: +### Can't reach database server Increase `connect_timeout` to 30s and check to make sure you are using a valid connection string. @@ -45,7 +45,7 @@ Increase `connect_timeout` to 30s and check to make sure you are using a valid c .../postgres?connect_timeout=30 ``` -## `Timed out fetching a new connection from the connection pool`: +### Timed out fetching a new connection from the connection pool Increase `pool_timeout` to 30s . @@ -53,7 +53,7 @@ Increase `pool_timeout` to 30s . .../postgres?pool_timeout=30 ``` -## `... prepared statement "" already exists` +### Prepared statement already exists Add pgbouncer=true to the connection string. @@ -61,23 +61,23 @@ Add pgbouncer=true to the connection string. .../postgres?pgbouncer=true ``` -## `Max client connections reached` +### Max client connections reached Check out this [guide](https://github.com/orgs/supabase/discussions/22305) for managing this error -## `Server has closed the connection` +### Server has closed the connection According to this [GitHub Issue for Prisma](https://github.com/prisma/prisma/discussions/7389), it may be related to large return values for queries. Try to limit the total amount of rows returned for particularly large requests. -## `Drift detected: Your database schema is not in sync with your migration history` +### Drift detected: Your database schema is not in sync with your migration history Prisma will try to act as the source of truth for your database structures. If you `CREATE`, `DROP`, or `ALTER` database objects outside of a Prisma Migration, it is likely to detect drift and may offer to correct the situation by purging your schemas. To circumvent this issue, try [baselining your migrations](https://www.prisma.io/docs/orm/prisma-migrate/workflows/baselining). Some users have discussed how they managed this problem in a [GitHub Discussion.](https://github.com/prisma/prisma/issues/19100#top) -# Management suggestions +## Management suggestions -## Make a custom role for Prisma to increase observability +### Make a custom role for Prisma to increase observability **Imagine your database as a house, and users as the people with keys.** @@ -85,7 +85,7 @@ Some users have discussed how they managed this problem in a [GitHub Discussion. - it's usually safer to give Prisma its own key! This way, it can only access the rooms (tables) it needs. - Plus, with separate keys, it's easier to see what Prisma is doing in your house with monitoring tools, such as [PGAudit](/docs/guides/database/extensions/pgaudit?queryGroups=database-method&database-method=sql) and [pg_stat_activity](/docs/guides/platform/performance). -### Creating the Prisma user: +#### Creating the Prisma user ```sql create user "prisma" with password 'secret_password' bypassrls createdb; @@ -93,7 +93,7 @@ create user "prisma" with password 'secret_password' bypassrls createdb; > Prisma requires the [`createdb` modifier](/blog/postgres-roles-and-privileges#role-attributes) to create shadow databases. It uses them to help manage migrations. -### Give Postgres ownership of the new user: +#### Give Postgres ownership of the new user This allows you to view Prisma migration changes in the [Dashboard](/dashboard/project/_/editor) @@ -101,7 +101,7 @@ This allows you to view Prisma migration changes in the [Dashboard](/dashboard/p grant "prisma" to "postgres"; ``` -### Keep it safe! +#### Keep it safe! Use a strong password for Prisma. Bitwarden provides a free [password generator](https://bitwarden.com/password-generator/) that can make one for you. @@ -111,7 +111,7 @@ If you need to change it later, you can use the below SQL: alter user "prisma" with password 'new_password'; ``` -### Grant Prisma access +#### Grant Prisma access The below example gives Prisma full authority over all database objects in the public schema: @@ -129,7 +129,7 @@ The below example gives Prisma full authority over all database objects in the p > For more guidance on specifying access, check out this [article](/blog/postgres-roles-and-privileges#creating-objects-and-assigning-privileges) on privileges -## Optimize Prisma queries: +### Optimize Prisma queries In the [Query Performance Advisor](/dashboard/project/_/database/query-performance), you can view long-running or frequently accessed queries by role: @@ -141,7 +141,7 @@ In the [Query Performance Advisor](/dashboard/project/_/database/query-performan Selecting a query can reveal suggestions to improve its performance -## Configuring connections +### Configuring connections Useful Links: @@ -150,7 +150,7 @@ Useful Links: Supabase provides 3 database connection strings that can be used simultaneously if necessary. You can find them on the dashboard by clicking [Connect](/dashboard/project/_?showConnect=true). -### Direct connection: +#### Direct connection Best used with stationary servers, such as VMs and long-standing containers, but it only works in IPv6 environments unless the [IPv4 Add-On](/dashboard/project/_/settings/addons) is enabled. If you are unsure if your network is IPv6 compatible, [check here](https://github.com/orgs/supabase/discussions/27034). @@ -160,7 +160,7 @@ Best used with stationary servers, such as VMs and long-standing containers, but postgresql://postgres:[PASSWORD]@db.[PROJECT REF].supabase.co:5432/postgres ``` -### Supavisor in session mode (port 5432): +#### Supavisor in session mode (port 5432) ```md # Example Connection @@ -172,7 +172,7 @@ An alternative to direct connections when working in IPv4-only environments. > Session mode is a good option for migrations -### Supavisor in transaction mode (port 6543): +#### Supavisor in transaction mode (port 6543) ```md # Example Connection diff --git a/apps/docs/content/troubleshooting/resolving-500-status-authentication-errors-7bU5U8.mdx b/apps/docs/content/troubleshooting/resolving-500-status-authentication-errors-7bU5U8.mdx index 264992e271f5c..b9b532be6080f 100644 --- a/apps/docs/content/troubleshooting/resolving-500-status-authentication-errors-7bU5U8.mdx +++ b/apps/docs/content/troubleshooting/resolving-500-status-authentication-errors-7bU5U8.mdx @@ -10,19 +10,19 @@ database_id = "031ba6d7-4928-4d95-a2da-bff8dbb740ec" http_status_code = 500 --- -# Resolving 500 status authentication errors +## Resolving 500 status authentication errors A 500 error in Auth typically indicates an issue with an external dependency, such as your database or SMTP provider, rather than with Auth itself. This guide will help you explore the Auth logs to identify the underlying cause. -### Prerequisites +#### Prerequisites -#### Open the log explorer +##### Open the log explorer Ensure you have access to the [Dashboard's Log Explorer](/dashboard/project/_/logs/explorer) and set the time range appropriately: ![image](/docs/img/troubleshooting/152d65ad-f0ed-47cf-8dcb-1e31c6221e71.png) -#### Improving log readability +##### Improving log readability Logs are displayed in a table format, which can be challenging to read. Double-clicking on a row will expand it for easier viewing: @@ -32,9 +32,9 @@ Logs are displayed in a table format, which can be challenging to read. Double-c src="https://github.com/user-attachments/assets/6f4c833c-ae15-41e1-9aa8-48ebd58741a1" /> -## Section 1: Checking for database-level errors +### Section 1: Checking for database-level errors -### Query for recent database errors +#### Query for recent database errors Use the following SQL query to check for any recent errors the Auth server encountered while interacting with your database: @@ -62,15 +62,15 @@ limit 100; If no results are returned, proceed to Section 2. -### Common database-level errors +#### Common database-level errors There are few known categories of auth/database level errors: -### Constraint related (sql_state_code = 23503 or 23\*) +#### Constraint related (sql_state_code = 23503 or 23\*) If you’ve manually created a foreign key relationship between your tables and those in the `auth` schema, a constraint may prevent the Auth server from updating the `auth.users` table. -#### Solution +##### Solution The log will show the name of the constraint. You need `DROP` it: @@ -90,11 +90,11 @@ ALTER TABLE ADD CONSTRAINT FOREIGN KEY ( OWNER TO supabase Alternatively, you can run the SQL script in this [GitHub Gist](https://gist.github.com/TheOtherBrian1/4714a333432b80660ff71b136b298fb8) to change all -### Trigger related: +#### Trigger related: If errors reference a database function, this indicates a trigger error on one of the auth tables (likely auth.users). If you do not want to keep the trigger/function, you can just quickly drop it, otherwise, continue reading to know how to fix the issue: @@ -116,7 +116,7 @@ DROP FUNCTION () CASCADE; -- DROP TRIGGER on auth.; ``` -#### Solutions: +##### Solutions: Get the function's definition with this query: @@ -126,11 +126,11 @@ from pg_proc where proname = ''; ``` -##### Trigger has insufficient privileges ( sql_state_code = 42501) +###### Trigger has insufficient privileges ( sql_state_code = 42501) If the error is related to insufficient privileges, your trigger function is missing a security definer tag, which allows it to access schemas outside of auth. You must `REPLACE` the function with the appropriate security definer settings ([example](/docs/guides/database/functions?queryGroups=language&language=js#security-definer-vs-invoker)) -##### Trigger references a table or column that does not exist (sql_state_code = 42P01) +###### Trigger references a table or column that does not exist (sql_state_code = 42P01) The trigger may be referencing a table or column that no longer exists. In that case do one of the three: @@ -139,13 +139,13 @@ The trigger may be referencing a table or column that no longer exists. In that - remove the trigger - recreate the database object that the trigger referenced -### Corrupted schema +#### Corrupted schema If you made any customizations to the auth schema, such as adding RLS, modifying table columns, or adding/dropping tables, it can break migrations done by the Auth Server. It's necessary to remove these changes and restore the auth schema to its original form. -## Section 2: Checking Auth level errors +### Section 2: Checking Auth level errors -### Query for Auth errors +#### Query for Auth errors Run this SQL query in the Log Explorer to find Auth-related errors: @@ -167,7 +167,7 @@ where order by timestamp ``` -### Database migration errors +#### Database migration errors > `running db migrations: Migrator: problem creating schema migrations` @@ -175,7 +175,7 @@ This is a continuation of the "Corrupted Schema" error from the Postgres Section If you are running older versions of auth, you may experience a migration bug. If so, checkout this [guide](https://github.com/orgs/supabase/discussions/20722) for a resolution. If it doesn't work, contact Support. -### SMTP errors +#### SMTP errors The logs may contain messages about `gomail`. It means that auth is struggling to communicate with the SMTP provider. This often implies that: @@ -186,7 +186,7 @@ The logs may contain messages about `gomail`. It means that auth is struggling t The log will be able to provide some context for what is occurring, but it is important to check with your external SMTP provider to make sure everything is properly configured. -## Step 3: Checking email templates +### Step 3: Checking email templates Incomplete or incorrect email templates can also cause 500 errors. If your templates have unclosed variable tags or HTML elements, or use forbidden characters, this might be the issue. diff --git a/apps/docs/content/troubleshooting/steps-to-improve-query-performance-with-indexes-q8PoC9.mdx b/apps/docs/content/troubleshooting/steps-to-improve-query-performance-with-indexes-q8PoC9.mdx index edabf7e92c2be..d159b35512bb9 100644 --- a/apps/docs/content/troubleshooting/steps-to-improve-query-performance-with-indexes-q8PoC9.mdx +++ b/apps/docs/content/troubleshooting/steps-to-improve-query-performance-with-indexes-q8PoC9.mdx @@ -10,13 +10,13 @@ database_id = "fb1cbd42-e172-44b2-af2b-fda5aecde5c2" cli = [ "supabase-inspect-db" ] --- -# Optimizing your database +## Optimizing your database This is an intermediate and actionable guide for Postgres optimization within the Supabase ecosystem. > Consider checking out [Index_advisor](/docs/guides/database/extensions/index_advisor) and the [performance advisor](/dashboard/project/_/database/performance-advisor) now available in the Dashboard! -## Installing Supabase Grafana +### Installing Supabase Grafana Supabase has an [open-source Grafana Repo](https://github.com/supabase/supabase-grafana) that displays real-time metrics of your database. Although the [Observability Dashboard](/dashboard/project/_/observability) provides similar metrics, it averages the data by the hour or day. Having visibility over how your database responds to changes helps to ensure that the database is not stressed by the index-building process. @@ -25,7 +25,7 @@ _Visual of Grafana Dashboard_ It can be run locally within Docker or can be deployed for free to fly.io. Installation instructions can be found in [Supabase's metrics docs](/docs/guides/telemetry/metrics/grafana-self-hosted) -## Query optimization through indexes +### Query optimization through indexes Disk (storage) is relatively slow compared to memory, so Postgres will take frequently accessed data and cache it in memory for fast access. diff --git a/apps/docs/content/troubleshooting/supabase--your-network-ipv4-and-ipv6-compatibility-cHe3BP.mdx b/apps/docs/content/troubleshooting/supabase--your-network-ipv4-and-ipv6-compatibility-cHe3BP.mdx index 538446d3c95b0..35751edb9fc51 100644 --- a/apps/docs/content/troubleshooting/supabase--your-network-ipv4-and-ipv6-compatibility-cHe3BP.mdx +++ b/apps/docs/content/troubleshooting/supabase--your-network-ipv4-and-ipv6-compatibility-cHe3BP.mdx @@ -7,18 +7,18 @@ keywords = [ "ipv4", "ipv6", "network", "compatibility", "address" ] database_id = "f27145c7-0ff5-4621-a364-5d5704bce0ff" --- -# Network compatibility with your Supabase database +## Network compatibility with your Supabase database The internet uses a system called the Internet Protocol (IP) to route communication between devices. There are two main versions: - **IPv4**: Introduced in 1980, it's the original version. - **IPv6**: Launched in 1999, it offers a much larger address space and is the preferred future-proof option. -### Supabase and IPv6: +#### Supabase and IPv6 All Supabase databases provide a direct connection string that maps to an IPv6 address. -### Working with IPv6 incompatible hosts: +#### Working with IPv6 incompatible hosts Here are your options if your server platform doesn't support IPv6: @@ -28,7 +28,7 @@ Here are your options if your server platform doesn't support IPv6: > Note: the IPv4 Add-On costs an hour, which equates to ~ if left on for a full month (~720 hours) -### Checking IPv6 support: +#### Checking IPv6 support The majority of services are IPv6 compatible. However, there are a few prominent ones that only accept IPv4 connections: @@ -45,7 +45,7 @@ curl -6 https://ifconfig.co/ip If the command returns an IPv6 address, the network is IPv6 compatible. -### Finding your database's IP address: +#### Finding your database's IP address To determine your current IP address, you can use an IP address [lookup website](https://whatismyipaddress.com/hostname-ip) or the terminal command: @@ -57,7 +57,7 @@ This command queries the domain name servers to find the IP address of the given Example IPv6 Address: `2a05:d014:1c06:5f0c:d7a9:8616:bee2:30df` -### Identifying your connections: +#### Identifying your connections The pooler and direct connection strings can be found on the dashboard by clicking [Connect](/dashboard/project/_?showConnect=true). @@ -68,14 +68,14 @@ The pooler and direct connection strings can be found on the dashboard by clicki postgresql://postgres:[YOUR-PASSWORD]@db.ajrbwkcuthywfihaarmflo.supabase.co:5432/postgres ``` -#### Supavisor in transaction mode (port 6543) +##### Supavisor in transaction mode (port 6543) ```sh # Example transaction string postgresql://postgres.ajrbwkcuthywddfihrmflo:[YOUR-PASSWORD]@aws-0-us-east-1.pooler.supabase.com:6543/postgres ``` -#### Supavisor in session mode (port 5432) +##### Supavisor in session mode (port 5432) ```sh # Example session string