Embedded Postgres

Neon makes it easy to embed Postgres into your platform with one-second provisioning, autoscaling, and scale-to-zero, so each user gets an isolated database without the overhead. Databases are provisioned via API and fully integrated into your product, with no Neon signup or setup required by your users.

Learn how platforms embed Neon

Learn how Retool manages 300k+ Postgres databases and Koyeb offers serverless Postgres using Neon.

Why embed Neon?

Neon is uniquely built to scale Postgres fleets efficiently:

Instant provisioning — Create a new Postgres database in under 1 second via API
Scale to zero — Inactive databases scale to zero to save on compute cost
True isolation — Each user gets their own dedicated Neon project with complete data separation
Autoscaling — Databases scale compute resources automatically based on demand
Set quotas — Set consumption limits per project to manage usage and costs
Track usage — Track compute time, storage, and other metrics per project

The project-per-user model

When integrating Neon into your platform, we strongly recommend a project-per-user model rather than branch-per-user or database-per-user models.

What is a project?

In Neon, resources such as branches, databases, roles, and computes are organized within a Neon project. When a user signs up with Neon directly, they start by creating a project, which includes a default branch, database, role, and compute instance. We recommend the same approach for your integration.

Why project-per-user?

Data isolation — Each user's data is completely separate, ensuring the highest level of security and privacy. This also helps with compliance standards like GDPR.
Resource isolation — One user's usage patterns or actions don't impact others. Each user has dedicated compute resources.
Easier limits and billing — Neon's APIs for setting consumption limits and tracking usage work at the project level, making it straightforward to implement usage-based billing.
Regional compliance — Each project can be deployed in a specific region, making it easy to host customer data closer to their location or meet data residency requirements.
Independent recovery — Operations like instant point-in-time restore work at the branch level. In a project-per-user model, you can restore individual customer databases without impacting others.
Simpler to manage — Following Neon's established project-based structure is easier than working against it. The Neon API is designed around this model.

note

The project-per-user model implements a database-per-tenant architecture. For a deeper dive into this approach and how Neon compares to traditional solutions like RDS, read Data Isolation at Scale.

Getting started

Set up API access
To interact with the Neon platform, you'll need an API key:
1. Generate a Neon API key from your Neon account settings. See Creating API keys.
2. Store the key securely in your environment variables.
3. Use the API key to authenticate requests to the Neon API.
For detailed API documentation, refer to the Neon API Reference, which includes links to Neon API examples.
Alternatively, use our official SDKs for easier integration:
- TypeScript SDK
- Python SDK
- @neondatabase/toolkit (supports the Neon API for platform operations and the Neon serverless driver for connecting and running SQL queries)

Create projects for your users

Use the Create project API to provision a new Postgres database for each user:

curl --request POST \
     --url https://console.neon.tech/api/v2/projects \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
  "project": {
    "name": "user-database-123",
    "pg_version": 16,
    "region_id": "aws-us-east-1"
  }
}' | jq

The response includes connection details you can provide to your user. Projects are created in under 1 second.

Custom names

You can customize the default database and role names when creating a project. See the Create project API docs for details.

Set compute and scaling behavior

Configure how computes scale and when they suspend due to inactivity:

autoscaling_limit_min_cu — Minimum compute size (default: 0.25 CU)
autoscaling_limit_max_cu — Maximum compute size for autoscaling
suspend_timeout_seconds — Inactivity period before compute suspends

Example setting a compute to scale between 1 and 4 CU with a 10-minute suspend timeout:

curl --request POST \
     --url https://console.neon.tech/api/v2/projects \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
  "project": {
    "default_endpoint_settings": {
      "autoscaling_limit_min_cu": 1,
      "autoscaling_limit_max_cu": 4,
      "suspend_timeout_seconds": 600
    },
    "pg_version": 16
  }
}'

For more on autoscaling, see Autoscaling and Scale to zero.

Configure consumption limits
Set limits on compute time, storage, and data transfer to control costs and implement your pricing tiers. You can configure these limits when creating a project or update them later.
Here's an example setting limits for a "starter" tier user:
```
curl --request POST \
     --url https://console.neon.tech/api/v2/projects \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
  "project": {
    "settings": {
      "quota": {
        "active_time_seconds": 36000,
        "compute_time_seconds": 9000,
        "written_data_bytes": 1000000000,
        "data_transfer_bytes": 500000000,
        "logical_size_bytes": 100000000
      }
    },
    "name": "starter-tier-user",
    "pg_version": 16
  }
}'
```
When a quota is reached, the project's computes are automatically suspended until the next billing period or until you adjust the limits.
For detailed information about configuring limits, see Configure consumption limits.
Here's a fictional example of how you might structure your own pricing tiers using Neon's consumption quotas:
Resource Free Tier Pro Tier Enterprise
Compute (min/max) 0.25 / 0.25 CU 0.25 / 2 CU 1 / 8 CU
Active time 100 hours/month 750 hours/month Unlimited
Storage 512 MB 10 GB 100 GB+
Data transfer 5 GB 50 GB Custom
For real-world examples, see how Koyeb defines their database instance types and pricing.
Monitor usage
Query consumption metrics to track usage across your projects and implement billing:
```
curl --request GET \
     --url 'https://console.neon.tech/api/v2/consumption_history/projects?limit=100&from=2024-11-01T00:00:00Z&to=2024-11-30T23:59:59Z&granularity=daily' \
     --header 'accept: application/json' \
     --header "authorization: Bearer $NEON_API_KEY"
```
The API provides metrics for:
- active_time_seconds — Time computes were active
- compute_time_seconds — CPU seconds consumed
- written_data_bytes — Data written to storage
- data_transfer_bytes — Data transferred out (egress)
- synthetic_storage_size_bytes — Total storage used
For details on querying metrics, see Query consumption metrics.

Resource	Free Tier	Pro Tier	Enterprise
Compute (min/max)	0.25 / 0.25 CU	0.25 / 2 CU	1 / 8 CU
Active time	100 hours/month	750 hours/month	Unlimited
Storage	512 MB	10 GB	100 GB+
Data transfer	5 GB	50 GB	Custom

Key considerations

Before going to production, consider these important aspects:

Connection limits

Be aware of the connection limits associated with each compute size. Connection pooling allows for significantly more concurrent connections. If you expect a high number of connections, we recommend using a pooled connection string. To learn more, see Connection pooling.

Reserved names

Neon reserves certain names for roles and databases. See Reserved role names and Reserved database names.

Polling consumption data

Consumption data updates approximately every 15 minutes
Minimum recommended polling interval: 15 minutes
Rate limit: ~30 requests per minute per account
Polling does NOT wake suspended computes

See the consumption polling FAQ for more details.

Staying informed

Monitor these resources for updates that could impact your integration:

Neon Roadmap for recent deliveries and upcoming features
Neon Changelog for product updates
Neon Status Page for platform status
RSS Feeds for all of the above

Advanced features

Isolated development environments

Neon's branching feature lets your users create isolated copies of their database for development and testing. Branches are copy-on-write clones that initially share data with their parent, though storage costs accumulate as changes are made to the branch.

Each user can:

Create instant database branches for testing
Reset branches to production state
Delete branches when done

This is particularly valuable for platforms where users need to test schema changes or experiment with data safely. Branching is fully supported by the Neon API. For examples, see Branching with the Neon API.

Schema migrations

If you're managing the same schema across many user databases, consider using tools like:

Integration support

We're here to help you build your integration:

info

Integrators of Neon can contact their Neon representative directly for assistance with their integration.

Learn how platforms embed Neon

Why embed Neon?

The project-per-user model

What is a project?

Why project-per-user?

note

Getting started

Set up API access

Create projects for your users

Custom names

Set compute and scaling behavior

Configure consumption limits

Monitor usage

Key considerations

Connection limits

Reserved names

Polling consumption data

Staying informed

Advanced features

Isolated development environments

Schema migrations

Integration support

Neon API Reference

Talk to Sales

info

On this page