Custom Domains

Use your own domain for PgBeam connection strings with automatic TLS certificate provisioning and renewal. Scale plan only.

Replace the default *.aws.pgbeam.app hostname in your connection string with your own domain. Your applications connect to db.yourcompany.com instead of abc.aws.pgbeam.app, while PgBeam handles TLS certificates automatically.

Scale plan required

Custom domains are available on the Scale plan only. See Plans & Pricing 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

From the dashboard, go to your project, then Domains, and click Add Domain. Enter your domain (e.g., db.example.com).

curl -X POST https://api.pgbeam.com/v1/projects/{projectId}/custom-domains \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"domain": "db.example.com"}'

pgbeam projects domains add --domain 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.aws.pgbeam.app`	Routes traffic to PgBeam
`TXT`	`_pgbeam-verify.db.example.com`	`pgbeam-verify=<token>`	Proves domain ownership
`CNAME`	`_acme-challenge.db.example.com`	`_acme-challenge.abc.aws.pgbeam.app`	Delegates TLS cert issuance

Replace abc with your project's subdomain and <token> 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 propagate within 1-10 minutes.

Verify the domain

After DNS propagates, trigger verification:

Click Verify next to the domain in your project's domain settings.

curl -X POST \
  https://api.pgbeam.com/v1/projects/{projectId}/custom-domains/{domainId}/verify \
  -H "Authorization: Bearer <key>"

pgbeam projects domains verify --domain db.example.com

PgBeam checks two things:

The TXT record exists and matches the verification token
The CNAME points to your PgBeam project subdomain

Update your connection string

Once verified, use your custom domain in your application:

.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:

# 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

Go to your project's Domains settings and click Remove next to the domain.

curl -X DELETE \
  https://api.pgbeam.com/v1/projects/{projectId}/custom-domains/{domainId} \
  -H "Authorization: Bearer <key>"

pgbeam projects domains delete --domain db.example.com

After removal:

The TLS certificate is revoked
Connections to the custom domain stop working
The default abc.aws.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.aws.pgbeam.app` exactly
CNAME lookup failed	Missing trailing dot at some providers	Try `abc.aws.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.