Skip to content

custom-domains.mdx

Latest commit

 

History

History
221 lines (166 loc) · 7.74 KB

custom-domains.mdx

File metadata and controls

221 lines (166 loc) · 7.74 KB
title Custom Domains
icon Globe
description 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.

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 
<Tabs items={["Dashboard", "API", "CLI"]}>
  <Tab value="Dashboard">
    From the dashboard, go to your project, then **Domains**, and click
    **Add Domain**. Enter your domain (e.g., `db.example.com`).
  </Tab>

  <Tab value="API">
    ```bash
    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"}'
    ```
  </Tab>

  <Tab value="CLI">
    ```bash
    pgbeam projects domains add --domain db.example.com
    ```
  </Tab>
</Tabs>

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.

<Callout type="info" title="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.
</Callout>
### Verify the domain 
After DNS propagates, trigger verification:

<Tabs items={["Dashboard", "API", "CLI"]}>
  <Tab value="Dashboard">
    Click **Verify** next to the domain in your project's domain settings.
  </Tab>

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

  <Tab value="CLI">
    ```bash
    pgbeam projects domains verify --domain db.example.com
    ```
  </Tab>
</Tabs>

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:

# 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

<Tabs items={["Dashboard", "API", "CLI"]}> Go to your project's Domains settings and click Remove next to the domain.

```bash curl -X DELETE \ https://api.pgbeam.com/v1/projects/{projectId}/custom-domains/{domainId} \ -H "Authorization: Bearer " ``` ```bash 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.

Further reading