Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs(security): document log_connections=off default and re-enable path (#47199)

Nik Richersd1f71464f12b
diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
index d4ce3c8084f..3b07a4cf095 100644
--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
@@ -2773,6 +2773,10 @@ export const platform: NavMenuConstant = {
},
{ name: 'Performance Tuning', url: '/guides/platform/performance' as `/${string}` },
{ name: 'SSL Enforcement', url: '/guides/platform/ssl-enforcement' as `/${string}` },
+ {
+ name: 'Postgres Connection Logging',
+ url: '/guides/platform/postgres-connection-logging' as `/${string}`,
+ },
{
name: 'Default Platform Permissions',
url: '/guides/platform/permissions' as `/${string}`,
diff --git a/apps/docs/content/guides/database/custom-postgres-config.mdx b/apps/docs/content/guides/database/custom-postgres-config.mdx
index efb45d922de..5e382e5cf11 100644
--- a/apps/docs/content/guides/database/custom-postgres-config.mdx
+++ b/apps/docs/content/guides/database/custom-postgres-config.mdx
@@ -149,6 +149,10 @@ Use the examples below with `supabase --experimental --project-ref <project-ref>
| [wal_sender_timeout](https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-WAL-SENDER-TIMEOUT) | CLI only | No | `--config wal_sender_timeout=60s` |
| [work_mem](https://www.postgresql.org/docs/current/runtime-config-resource.html#GUC-WORK-MEM) | CLI + SQL | No | `--config work_mem=64MB` |
+#### Management API only parameters
+
+Some Postgres settings are configurable through the [Management API](/docs/reference/api/v1-update-postgres-config) but not the CLI. These include logging settings such as `log_connections`. See [Postgres connection logging](/docs/guides/platform/postgres-connection-logging) for details.
+
#### Managing Postgres configuration with the CLI
To start:
diff --git a/apps/docs/content/guides/deployment/shared-responsibility-model.mdx b/apps/docs/content/guides/deployment/shared-responsibility-model.mdx
index 41c934fd008..e6d82cc9638 100644
--- a/apps/docs/content/guides/deployment/shared-responsibility-model.mdx
+++ b/apps/docs/content/guides/deployment/shared-responsibility-model.mdx
@@ -98,6 +98,7 @@ You can use Supabase to store and process Protected Health Information (PHI). Yo
- Enabling [Point in Time Recovery](/docs/guides/platform/backups#point-in-time-recovery) which requires at least a [small compute add-on](/docs/guides/platform/compute-add-ons).
- Turning on [SSL Enforcement](/docs/guides/platform/ssl-enforcement).
- Enabling [Network Restrictions](/docs/guides/platform/network-restrictions).
+- Keeping [Postgres connection logging](/docs/guides/platform/postgres-connection-logging) enabled. Supabase sets `log_connections` to off by default for new projects. Projects that need HIPAA compliance should keep connection logging on for audit trails, and the Security Advisor warns if it is disabled.
- Complying with encryption requirements in the HIPAA Security Rule. Data is encrypted at rest and in transit by Supabase. You can consider encrypting the data at your application layer.
- Not storing PHI in [public Storage buckets](/docs/guides/storage/buckets/fundamentals#public-buckets).
- Not [transferring projects](/docs/guides/platform/project-transfer) to a non-HIPAA organization.
diff --git a/apps/docs/content/guides/platform/hipaa-projects.mdx b/apps/docs/content/guides/platform/hipaa-projects.mdx
index 2e91554e454..78f1864bce1 100644
--- a/apps/docs/content/guides/platform/hipaa-projects.mdx
+++ b/apps/docs/content/guides/platform/hipaa-projects.mdx
@@ -24,5 +24,6 @@ These include:
- Enabling [Point in Time Recovery](/docs/guides/platform/backups#point-in-time-recovery) which requires at least a [small compute add-on](/docs/guides/platform/compute-add-ons).
- Turning on [SSL Enforcement](/docs/guides/platform/ssl-enforcement).
- Enabling [Network Restrictions](/docs/guides/platform/network-restrictions).
+- Keeping [Postgres connection logging](/docs/guides/platform/postgres-connection-logging) enabled.
Additional security checks and controls will be added as the security advisor is extended and additional security controls are made available.
diff --git a/apps/docs/content/guides/platform/postgres-connection-logging.mdx b/apps/docs/content/guides/platform/postgres-connection-logging.mdx
new file mode 100644
index 00000000000..866336b8046
--- /dev/null
+++ b/apps/docs/content/guides/platform/postgres-connection-logging.mdx
@@ -0,0 +1,79 @@
+---
+id: 'postgres-connection-logging'
+title: 'Postgres connection logging'
+description: 'Enable or disable Postgres connection logging for audit and compliance.'
+---
+
+For security monitoring and compliance audits, Postgres can log connection lifecycle events to your project's [Postgres logs](/docs/guides/telemetry/logs#postgres), including events such as `connection received`, `connection authenticated`, and `connection authorized`.
+
+## Default behavior
+
+By default, Supabase sets `log_connections` to off for new projects and you must enable it first. This behavior matches common managed Postgres defaults and reduces log volume from high-frequency connection events.
+
+Existing projects may retain different settings depending on plan and compliance configuration:
+
+- **Team, Enterprise, and HIPAA organizations** — Connection logging is typically enabled to support audit requirements.
+- **HIPAA projects** — Supabase enables connection logging when a project is marked as high compliance. The [Security Advisor](/dashboard/project/_/advisors/security) warns if connection logging is later disabled.
+
+## Compliance considerations
+
+<Admonition type="note">
+
+If you need connection audit evidence for SOC 2 or other compliance programs, you must enable it explicitly.
+
+</Admonition>
+
+Connection logging supports audit and monitoring controls required by some compliance programs:
+
+- **HIPAA** — High-compliance projects should keep connection logging enabled. See the [shared responsibility model for healthcare data](/docs/guides/deployment/shared-responsibility-model#managing-healthcare-data) and [HIPAA compliance guide](/docs/guides/security/hipaa-compliance).
+- **SOC 2** — Users who need connection audit evidence should enable logging and retain logs according to their own policies. See the [SOC 2 compliance guide](/docs/guides/security/soc-2-compliance).
+
+Disabling connection logging does not affect other Supabase logging (for example, [Platform Audit Logs](/docs/guides/security/platform-audit-logs), [Auth Audit Logs](/docs/guides/auth/audit-logs), or [pgAudit](/docs/guides/telemetry/logs#configuring-pgauditlog)).
+
+## Manage connection logging via the dashboard
+
+You can configure connection logging from the **Log connections** setting in the [Database Settings](/dashboard/project/_/database/settings) section of the Dashboard.
+
+Ensure that you have [Owner or Admin permissions](/docs/guides/platform/access-control#manage-team-members) for the project.
+
+<Admonition type="note">
+
+Connection events appear in Postgres logs. In the [Logs Explorer](/dashboard/project/_/logs-explorer), connection lifecycle messages may be hidden by default to reduce noise. Use the connection logs filter in the sidebar to show or hide them.
+
+</Admonition>
+
+## Manage connection logging via the Management API
+
+You can also manage connection logging using the [Management API](/docs/reference/api/v1-update-postgres-config):
+
+```bash
+# Get your access token from https://supabase.com/dashboard/account/tokens
+export SUPABASE_ACCESS_TOKEN="your-access-token"
+export PROJECT_REF="your-project-ref"
+
+# Get current Postgres config
+curl -X GET "https://api.supabase.com/v1/projects/$PROJECT_REF/config/database/postgres" \
+ -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"
+
+# Enable connection logging
+curl -X PUT "https://api.supabase.com/v1/projects/$PROJECT_REF/config/database/postgres" \
+ -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "log_connections": true
+ }'
+
+# Disable connection logging
+curl -X PUT "https://api.supabase.com/v1/projects/$PROJECT_REF/config/database/postgres" \
+ -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "log_connections": false
+ }'
+```
+
+To verify the setting, use the SQL Editor:
+
+```sql
+show log_connections;
+```
diff --git a/apps/docs/content/guides/security/hipaa-compliance.mdx b/apps/docs/content/guides/security/hipaa-compliance.mdx
index 59b96c4d85b..c387b5c6947 100644
--- a/apps/docs/content/guides/security/hipaa-compliance.mdx
+++ b/apps/docs/content/guides/security/hipaa-compliance.mdx
@@ -51,6 +51,10 @@ The main differentiator comes down to purpose and scope.
Yes. Supabase applies the same SOC 2 controls to all environments, with additional controls being applied to HIPAA environments.
+**Does Supabase log database connections by default?**
+
+No. Supabase sets Postgres `log_connections` to off by default for new projects. HIPAA and high-compliance projects should keep [connection logging](/docs/guides/platform/postgres-connection-logging) enabled. The Security Advisor warns if it is disabled.
+
**How often is Supabase audited?**
Supabase undergoes annual audits. The HIPAA controls are audited during the same audit period as the SOC 2 controls.
@@ -64,3 +68,4 @@ Supabase undergoes annual audits. The HIPAA controls are audited during the same
5. [Configuring HIPAA projects](/docs/guides/platform/hipaa-projects) on Supabase
6. [Shared Responsibility Model](/docs/guides/deployment/shared-responsibility-model)
7. [HIPAA shared responsibility](/docs/guides/deployment/shared-responsibility-model#managing-healthcare-data)
+8. [Postgres connection logging](/docs/guides/platform/postgres-connection-logging)
diff --git a/apps/docs/content/guides/security/product-security.mdx b/apps/docs/content/guides/security/product-security.mdx
index 08600a1d290..f47e9b1d1c2 100644
--- a/apps/docs/content/guides/security/product-security.mdx
+++ b/apps/docs/content/guides/security/product-security.mdx
@@ -23,6 +23,7 @@ Various products at Supabase have their own hardening and configuration guides,
- [Custom claims and role based access control](/docs/guides/api/custom-claims-and-role-based-access-control-rbac)
- [Managing Postgres roles](/docs/guides/database/postgres/roles)
- [Managing secrets with Vault](/docs/guides/database/vault)
+- [Postgres connection logging](/docs/guides/platform/postgres-connection-logging)
- [Superuser access and unsupported operations](docs/guides/database/postgres/roles-superuser)
## Storage
diff --git a/apps/docs/content/guides/security/soc-2-compliance.mdx b/apps/docs/content/guides/security/soc-2-compliance.mdx
index 073dd07e5b7..7e202e4d2a4 100644
--- a/apps/docs/content/guides/security/soc-2-compliance.mdx
+++ b/apps/docs/content/guides/security/soc-2-compliance.mdx
@@ -38,6 +38,7 @@ SOC 2 compliance is a critical aspect of data security for Supabase and our cust
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.
+5. **Audit logging**: Supabase sets [Postgres connection logging](/docs/guides/platform/postgres-connection-logging) to off by default for new projects. If your SOC 2 program requires connection audit evidence, enable connection logging and define how you retain and review those logs.
#### Shared responsibilities
@@ -82,3 +83,4 @@ When dealing with PHI in the United States or for United States customers, HIPAA
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)
+3. [Postgres connection logging](/docs/guides/platform/postgres-connection-logging)
diff --git a/apps/docs/content/guides/telemetry/logs.mdx b/apps/docs/content/guides/telemetry/logs.mdx
index 60fec5f516f..9f5d9ae85bc 100644
--- a/apps/docs/content/guides/telemetry/logs.mdx
+++ b/apps/docs/content/guides/telemetry/logs.mdx
@@ -143,6 +143,14 @@ Do not log Personal Identifiable Information (PII) within the `User-Agent` heade
</Admonition>
+## Logging Postgres connections
+
+Postgres can log connection lifecycle events to your project's Postgres logs, for example when a client connects or authenticates. By default, Supabase sets `log_connections` to off for new projects and you must enable it first.
+
+To enable connection logging for audit or compliance, see [Postgres connection logging](/docs/guides/platform/postgres-connection-logging).
+
+In the [Logs Explorer](/dashboard/project/_/logs-explorer), connection lifecycle messages may be hidden by default. Use the connection logs filter in the sidebar to show them.
+
## Logging Postgres queries
To enable query logs for other categories of statements: