--- title: "Custom Domains" description: "Use your own domain for PgBeam connection strings with automatic TLS certificate provisioning and renewal. Scale plan only." canonical: "https://pgbeam.com/docs/custom-domains" last-updated: "2026-10-30T13:45:52.000Z" --- # Custom Domains > Use your own domain for PgBeam connection strings with automatic TLS certificate provisioning and renewal. Scale plan only. URL: https://pgbeam.com/docs/custom-domains Replace the default `*.proxy.pgbeam.app` hostname in your connection string with your own domain. Your applications connect to `db.yourcompany.com` instead of `abc.proxy.pgbeam.app`, while PgBeam handles TLS certificates automatically. > **Scale plan required** > > Custom domains are available on the **Scale plan** only. See [Plans & > Pricing](/docs/plans) for details. ## Why use a custom domain * **Portability.** If you move between proxy providers, your connection strings stay the same. No application changes needed. * **Branding.** Internal tools and dashboards show your domain instead of a third-party hostname. * **Security policy compliance.** Some organizations require all external connections to use company-owned domains. ## Prerequisites * A **Scale plan** subscription * Access to your domain's **DNS settings** (through your registrar or DNS provider like Cloudflare, Route 53, etc.) * A project with at least one configured database ## Setup ### Add the domain **Dashboard** From the dashboard, go to your project, then **Domains**, and click **Add Domain**. Enter your domain (e.g., `db.example.com`). **API** ```bash curl -X POST https://api.pgbeam.com/v1/projects/{projectId}/domains \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"domain": "db.example.com"}' ``` **CLI** ```bash pgbeam domains add db.example.com ``` The response includes your **verification token** and DNS instructions. ### Add DNS records Add all three records to your domain's DNS: | Record | Host | Value | Purpose | | ------- | -------------------------------- | -------------------------------------- | --------------------------- | | `CNAME` | `db.example.com` | `abc.proxy.pgbeam.app` | Routes traffic to PgBeam | | `TXT` | `_pgbeam-verify.db.example.com` | `pgbeam-verify=` | Proves domain ownership | | `CNAME` | `_acme-challenge.db.example.com` | `_acme-challenge.abc.proxy.pgbeam.app` | Delegates TLS cert issuance | Replace `abc` with your project's subdomain and `` with the verification token from the previous step. > **DNS propagation** > > DNS changes can take anywhere from a few minutes to 24 hours to propagate, > depending on your DNS provider and existing TTL settings. Most providers > complete this within 1-10 minutes. ### Verify the domain After DNS propagates, trigger verification: **Dashboard** Click **Verify** next to the domain in your project's domain settings. **API** ```bash curl -X POST \ https://api.pgbeam.com/v1/projects/{projectId}/domains/{domainId}/verify \ -H "Authorization: Bearer " ``` **CLI** ```bash pgbeam domains verify ``` PgBeam checks two things: 1. The TXT record exists and matches the verification token 2. The CNAME points to your PgBeam project subdomain ### Update your connection string Once verified, use your custom domain in your application: ```bash title=".env" DATABASE_URL=postgresql://user:pass@db.example.com:5432/mydb ``` TLS is handled automatically. PgBeam provisions a certificate for your domain and uses SNI to match incoming connections to your project. ## TLS certificate management PgBeam provisions and renews TLS certificates for your custom domain automatically. The ACME challenge CNAME you added in the DNS step delegates the certificate challenge, so PgBeam can issue and renew certificates without any further action from you. * **Provisioning** happens within minutes of successful domain verification. * **Renewal** happens automatically before the certificate expires. * **Revocation** happens automatically when you remove the custom domain. You do not need to upload or manage certificates manually. ## Multiple custom domains You can add multiple custom domains to a single project. Each domain gets its own TLS certificate and DNS verification. This is useful when you want different domains for different environments or services while routing to the same PgBeam project: ```bash # Production DATABASE_URL=postgresql://user:pass@db.example.com:5432/mydb # Staging DATABASE_URL=postgresql://user:pass@db-staging.example.com:5432/mydb ``` ## Remove a custom domain **Dashboard** Go to your project's **Domains** settings and click **Remove** next to the domain. **API** ```bash curl -X DELETE \ https://api.pgbeam.com/v1/projects/{projectId}/domains/{domainId} \ -H "Authorization: Bearer " ``` **CLI** ```bash pgbeam domains delete ``` After removal: * The TLS certificate is revoked * Connections to the custom domain stop working * The default `abc.proxy.pgbeam.app` hostname continues to work * You should remove the DNS records from your DNS provider ## Troubleshooting ### Verification failures | Issue | Likely cause | Fix | | -------------------- | ----------------------------------------- | ------------------------------------------------------------------ | | TXT record not found | DNS propagation delay | Wait and retry. Check with `dig TXT _pgbeam-verify.db.example.com` | | CNAME mismatch | Target is not the exact project subdomain | Verify the CNAME points to `abc.proxy.pgbeam.app` exactly | | CNAME lookup failed | Missing trailing dot at some providers | Try `abc.proxy.pgbeam.app.` (with trailing dot) | ### Certificate issues | Issue | Likely cause | Fix | | --------------------- | ------------------------------------- | ----------------------------------------------------------------------- | | Certificate not ready | ACME challenge CNAME missing or wrong | Verify `_acme-challenge` CNAME record is correct | | Certificate expired | ACME challenge CNAME was removed | Re-add the ACME challenge CNAME to enable auto-renewal | | TLS error on connect | Client does not trust the certificate | Update system CA bundle; PgBeam certs are trusted by all modern systems | ### Cloudflare-specific notes If your DNS is managed by Cloudflare, make sure the CNAME record has the **proxy toggle disabled** (DNS-only / grey cloud). Cloudflare's proxy intercepts TCP traffic and will break PostgreSQL wire protocol connections. ## Further reading * [Plans & Limits](/docs/plans): Custom domains are available on the Scale plan * [Routing & Regions](/docs/routing): How global routing works with custom domains * [Troubleshooting](/docs/troubleshooting): General connection debugging