Neon’s IP allowlist feature lets you lock down your database access to only trusted IP addresses, preventing unauthorized connections.
Let’s see it in action. Imagine you have a web application running on a specific server. You want to ensure that only your application’s server can connect to your Neon database.
Here’s a simplified Dockerfile for a hypothetical Node.js app that might connect to Neon:
FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD [ "node", "server.js" ]
And here’s a snippet from a hypothetical server.js that establishes a connection to Neon:
const neon = require('neon-js'); // Assuming a Neon client library
async function connectToNeon() {
const connectionString = process.env.NEON_DATABASE_URL; // e.g., postgres://user:password@ep-xxxxx.us-east-1.aws.neon.tech/dbname
try {
const client = await neon.connect(connectionString);
console.log("Successfully connected to Neon!");
// Perform database operations here
await client.end();
} catch (error) {
console.error("Failed to connect to Neon:", error);
}
}
connectToNeon();
Without an IP allowlist, this application could potentially run from anywhere with internet access, provided it has the NEON_DATABASE_URL.
Now, let’s configure Neon to only allow connections from the IP address of your application server.
The Core Problem: Network Perimeter Security
Databases are prime targets. By default, many cloud databases are accessible from any IP address, relying solely on credentials for security. This is like leaving your house unlocked and just putting a strong lock on the door handle. Anyone who gets the key (your password) can walk right in. The IP allowlist adds a crucial layer: it’s like a gatekeeper at your property line who only lets people through if they are on a pre-approved list of visitors.
How Neon’s IP Allowlist Works Internally
When you enable the IP allowlist and add specific IP addresses, Neon’s network infrastructure intercepts incoming connection attempts. Before even reaching your database’s authentication layer, Neon checks the source IP address of the connection. If that IP address is not on your configured allowlist, the connection is immediately rejected at the network level. This is highly efficient, as it prevents unauthorized traffic from consuming any database resources.
Configuring the IP Allowlist in Neon
You can manage your IP allowlist through the Neon Console or via the Neon API.
Using the Neon Console:
- Navigate to your Neon project.
- Go to Project Settings.
- Select Network Security.
- Under IP Allowlist, click Add IP Address.
- Enter the IP address you want to allow. This can be a single IP address (e.g.,
203.0.113.5) or a CIDR block (e.g.,192.168.1.0/24) for a range of IPs. - Click Save.
Example Configuration:
Let’s say your application server has the public IP address 203.0.113.42. You would add 203.0.113.42 to your IP allowlist. If your application runs on a set of servers within your VPC with private IPs like 10.0.1.10 to 10.0.1.20, you’d add the CIDR block 10.0.1.0/24 (assuming this covers your subnet).
Using the Neon API (CLI Example):
You can use the neonctl CLI (or the REST API directly) to manage your allowlist.
First, ensure you have neonctl installed and configured.
To add an IP address:
neonctl ip-allowlist add --project <your-project-name> --address 203.0.113.42
To list existing allowlist entries:
neonctl ip-allowlist list --project <your-project-name>
To remove an IP address:
neonctl ip-allowlist remove --project <your-project-name> --address 203.0.113.42
Key Levers You Control
- Specific IP Addresses: Allowing only known, static IPs. Ideal for dedicated servers or workstations.
- CIDR Blocks: Permitting entire subnets. Useful for allowing all servers within a particular VPC or network range.
- Dynamic IPs (with caveats): If your application server has a dynamic IP that changes, you’ll need a mechanism to update the allowlist automatically. This is often done by having your application server report its current IP to a service that then updates the Neon allowlist via the API.
- VPC Peering/Private Connectivity: For even tighter security, you can often combine IP allowlisting with private network connectivity (like AWS VPC peering or Google Cloud Private Service Connect), where you might only need to allow specific internal IP ranges or even no public IPs at all if the connection is entirely within your cloud provider’s network.
The One Thing Most People Don’t Know
When you add a CIDR block like 192.168.1.0/24, Neon doesn’t just check the source IP of the connection originating from your client. It also considers the IP address that your database connection string is pointing to. If you are using a Neon endpoint that resolves to multiple underlying IP addresses (which can happen for high availability or scaling), and your allowlist is too narrow (e.g., only allowing the IP of a single load balancer node that might change), you could inadvertently block legitimate connections. It’s generally best to allow the IP range of the network your application resides in, rather than trying to pinpoint individual Neon endpoint IPs.
Next Steps
After securing your database with an IP allowlist, the next logical step is to implement connection pooling to manage database connections efficiently and improve application performance.