Integration
Neon Integration
Serverless PostgreSQL with branching, used for preview environments that carry their own data and for workloads that idle between bursts.
- Preview environments with their own database per pull request
- Migration rehearsal against production shaped data before release
- Reporting stores kept separate from the transactional database
- Low traffic internal tools where scale to zero is the correct economics
- Point in time recovery without overwriting the live database
Overview
What this integration involves
Neon is managed PostgreSQL with storage and compute separated. Compute scales with load and can stop entirely when idle, and storage supports copy on write branches.
Branching is the feature that changes a workflow. A branch is a full database created in seconds, so a pull request can have its own data without copying a production dump or sharing a staging database with four other changes.
The tradeoff to design around is cold start. A compute that has scaled to zero takes a moment to wake, which is fine for an internal tool and wrong on the critical path of a marketing page.
Surface
Capabilities we use
Database branching
A branch shares storage with its parent through copy on write and diverges as changes are made. Define branch creation, reset and deletion in the environment lifecycle, and monitor compute and storage usage.
Autoscaling compute
Compute can adjust within a configured range and suspend when scale to zero is enabled. Resume behavior, supported configurations and account limits should be checked for the selected plan; storage and other resource usage remain separate concerns.
Connection pooling
A built in pooler accepts far more client connections than PostgreSQL would, which is what makes serverless functions workable against a relational database.
Point in time restore
Restore to a timestamp within the retention window by creating a branch at that point, which makes recovery a non destructive operation.
Standard PostgreSQL
Ordinary SQL, ordinary extensions, ordinary tooling. Nothing about the schema is specific to the platform, so moving is a data transfer rather than a rewrite.
Data flow
Step by step
- 01
Open a pull request
The pipeline creates a preview branch from an approved baseline containing synthetic or appropriately masked data. Branch isolation does not itself anonymise inherited records.
- 02
Run migrations against the branch
Pending migrations are applied to the branch, which is also the most realistic test of the migration itself, since it runs against production shaped data.
- 03
Point the preview deployment at it
The branch connection string is set as an environment variable on the preview deployment, so the reviewer exercises the change against its own data.
- 04
Review with isolated test data
Database writes affect the preview branch. External email, payment and webhook destinations also need test credentials or disabled side effects; a separate database alone does not isolate those services.
- 05
Delete on merge
The pipeline deletes the branch when the pull request closes, so branches do not accumulate.
- 06
Apply to production
The same migrations run against the production branch as part of the deployment, having already been executed against a copy of the same data.
Architecture
How the pieces connect
- 01Pull requesttoPipeline
opened
- 02PipelinetoPreview branch
create from parent
- 03Sanitised baselinetoPreview branch
shared storage
- 04PipelinetoPreview deployment
set connection
- 05Preview deploymenttoConnection pooler
Application data exchange
- 06Connection poolertoPreview branch
Application data exchange
Events
Webhooks we handle
- Pipeline events that create a branch when a pull request opens
- Pipeline events that delete a branch when a pull request closes
- Deployment hooks that run migrations before a release is promoted
- Alerting on compute usage and storage growth
Reliability
What makes it hold
Always connect through the pooler
Serverless functions open connections faster than PostgreSQL accepts them. Application traffic uses the pooled endpoint. The direct endpoint is reserved for migrations and administrative sessions that need session level features.
Design around cold start
Where suspend is enabled, the first request after idle waits for compute to resume. Public pages are statically generated so they never depend on it, and where a warm database matters the idle timeout is extended instead.
Retry on connection errors
A connection can drop during a scaling event. The data layer retries idempotent reads automatically and surfaces write failures rather than retrying blindly.
Statement timeouts
A timeout is set at the connection level so a pathological query fails rather than holding a connection and starving the pool.
Branch lifecycle management
Branches are deleted when their pull request closes, and a scheduled job removes orphans. Unmanaged branches are the main source of surprise cost.
Security
How it is secured
- Connections require TLS, and the pooled endpoint is the only one exposed to application environments.
- Separate roles for application access and migrations, with the application role holding no schema change rights.
- Connection strings live in the platform secret store, scoped per environment.
- Preview branches inherit production data, so any dataset containing personal information is masked before branching is enabled for previews.
- IP restrictions applied where the platform and the workload allow it.
FAQ
Questions people actually ask
Is a branch a full copy of the data?
Logically yes, physically no. Branches share storage with the parent and only diverge as they are written to, which is why creating one is fast and cheap.
Does preview data include real customer records?
Only if you allow it. Where the production database holds personal information we mask before branching for previews, because a preview URL is a much wider audience than production.
What is the cold start penalty?
A short wait while compute resumes, measured in hundreds of milliseconds to a couple of seconds depending on configuration. We keep it off the critical path of public pages and extend the idle timeout where it would be visible.
Can we move to another PostgreSQL host later?
Yes. It is standard PostgreSQL, so the schema, the migrations and the data transfer in the ordinary way. Only branching is platform specific, and that is a workflow rather than an application dependency.
How do you avoid connection exhaustion?
By using the pooled endpoint for all application traffic, keeping statement timeouts short, and never holding a connection across an await that waits on a third party.
Let’s talk about the system you need.
Tell us where the current process breaks down. We can map the workflow, examine the integration requirements and define a practical scope for the build.
- A mutual NDA is signed before project details are shared.
- Scope is fixed in writing before any build starts.
- You own the source code, the IP and the documentation at delivery.
- Support plans are available and tailored on a discovery or technical call.