Document steps for configuring Sentry Self-Hosted with an external PostgreSQL database (instead of Docker-local DB)

[franciscomasi]

Problem Statement

Hi 👋

I’m currently setting up Sentry Self-Hosted using an external PostgreSQL database (e.g. AWS RDS) instead of the PostgreSQL service bundled in the default docker-compose setup.

While the standard installation documentation is very good, it’s not clear or centralized how to properly configure this setup, specifically:

• Which services should be disabled (PostgreSQL, pgbouncer, etc.)
• Which environment variables must be set to point to an external database
• Where these variables should be defined (.env, overrides, etc.)
• Whether these changes should be done before or after running install.sh
• Additional considerations (migrations, permissions, SSL, external pgbouncer, etc.)

Although it’s possible to infer this by inspecting docker-compose.yml and existing configs, having an official documented guide would be extremely helpful, as using a managed database is a very common production scenario.

Thanks for the great work on Sentry, and for considering this documentation improvement 🙌

Solution Brainstorm

No response

[aldy505]

We don't put this on the documentation because Sentry has a policy that anything written on the documentation is officially supported by Sentry, and we offer help for it. Using external databases is possible, but we just don't document it because there are so many unknown variables (authentication schemes, I/O per second throughput requirements, etc).

To answer to your questions...

Which services should be disabled (PostgreSQL, pgbouncer, etc.)

Yes, just pgbouncer and postgres.

Which environment variables must be set to point to an external database

Only this:

self-hosted/sentry/sentry.conf.example.py

Lines 45 to 54 in 66a3091

	DATABASES = {
	"default": {
	"ENGINE": "sentry.db.postgres",
	"NAME": "postgres",
	"USER": "postgres",
	"PASSWORD": "",
	"HOST": "pgbouncer",
	"PORT": "",
	}
	}

Where these variables should be defined (.env, overrides, etc.)

The same with the above.

Whether these changes should be done before or after running install.sh

Before.

Additional considerations (migrations, permissions, SSL, external pgbouncer, etc.)

I would really recommend to use AWS S3 (because you said RDS) rather than going through the hassle of configuring RDS to work with Sentry. As you go, your Sentry instance will probably get storage problem. When that happen, my only recommendation is to use an external storage: https://develop.sentry.dev/self-hosted/production-enhancements/external-storage/

Another set of problem that you want to look out first: https://develop.sentry.dev/self-hosted/reference-architecture/separate-ingest-box/