Skip to content

ip-allowlist.mdx

Latest commit

 

History

History
144 lines (114 loc) · 4.3 KB

ip-allowlist.mdx

File metadata and controls

144 lines (114 loc) · 4.3 KB
title IP Filtering
icon Shield
description Restrict database connections to specific IP addresses or CIDR ranges using per-project IP filtering with optional labels.

IP filtering lets you restrict which client IP addresses can connect to a project through PgBeam. When enabled, connections from IPs outside the allowlist are rejected before authentication — they never reach the upstream database.

How it works

Each project has an optional list of CIDR filtering rules. When the list is non-empty, PgBeam checks every incoming connection's source IP against the rules during the TLS handshake, before any PostgreSQL protocol exchange.

Filter state Behavior
Empty (default) All IPs are allowed
One or more CIDR rules Only matching IPs are allowed; others are rejected

Rejected connections receive a FATAL error and the connection is closed immediately:

FATAL: connection rejected: IP not in allowlist
SQLSTATE: 08004

Configure IP filtering

You can manage IP filtering from the dashboard, API, or CLI. Each entry consists of a CIDR range and an optional label. Use /32 for a single IPv4 address or /128 for a single IPv6 address.

<Tabs items={["Dashboard", "API", "CLI"]}> Navigate to your project and go to Settings > Security. Toggle IP filtering on, then add CIDR blocks with optional labels. Changes take effect within seconds across all data plane regions.

```bash curl -X PATCH \ https://api.pgbeam.com/v1/projects/{projectId} \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "allowed_cidrs": [ { "cidr": "203.0.113.0/24", "label": "Office" }, { "cidr": "198.51.100.42/32", "label": "CI/CD" }, { "cidr": "2001:db8::/32", "label": "IPv6 range" } ] }' ``` ```bash pgbeam projects update \ --allowed-cidrs "203.0.113.0/24,198.51.100.42/32,2001:db8::/32" ```

To disable IP filtering, set it to an empty array:

curl -X PATCH \
  https://api.pgbeam.com/v1/projects/{projectId} \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{ "allowed_cidrs": [] }'

Limits

  • Maximum 50 CIDR entries per project
  • Both IPv4 and IPv6 CIDR notation are supported
  • Each entry supports an optional human-readable label (max 100 characters)
  • A plain IP without prefix length defaults to /32 (IPv4) or /128 (IPv6)
  • Changes propagate to all data plane regions within seconds via the config streaming channel

Common patterns

Allow a single office IP

{ "allowed_cidrs": [{ "cidr": "203.0.113.42/32", "label": "Office" }] }

Allow a VPC range and a developer IP

{
  "allowed_cidrs": [
    { "cidr": "10.0.0.0/8", "label": "VPC" },
    { "cidr": "198.51.100.1/32", "label": "Dev laptop" }
  ]
}

Allow IPv6 ranges

{
  "allowed_cidrs": [
    { "cidr": "2001:db8::/32", "label": "IPv6 prefix" },
    { "cidr": "fd00::/8", "label": "Private IPv6" }
  ]
}
Make sure to include the IP ranges of all environments that connect through PgBeam — production servers, CI/CD pipelines, developer machines, and any monitoring tools. Forgetting an IP range will block those connections.

Interaction with other features

IP allowlisting is checked before authentication, connection pooling, and all other proxy features. The evaluation order for an incoming connection is:

  1. TLS handshake and SNI-based project lookup
  2. IP allowlist check (if configured)
  3. Authentication (credentials forwarded to upstream)
  4. Connection pooling and query relay

This means:

  • Blocked IPs never consume a connection slot
  • Blocked IPs never trigger auth rate limiting
  • The upstream database never sees traffic from disallowed IPs

Further reading