Neon Postgres Database

You can configure Encore to provision a Neon Postgres database instead of the default offering for any Cloud.
Neon is a serverless database provider that offers a fully managed and autoscalable Postgres database.

Connect your Neon account

To start using Neon with Encore, you need to add your Neon API key to your Encore application. You can sign up for a Neon account at neon.tech. Once you have an account, you can find your API key in the Neon Console

Then, head over to the Neon settings page by going to Encore's Cloud Dashboard > (Select your app) > App Settings > Integrations > Neon.

Click the "Connect Account" button, give it a name, and enter your API key.

Create an environment with Neon

Neon organizes databases in projects. A project consist of a main branch and any number of feature branches. Branches in Neon works the same way as branches in your code. This allows you to create a new branch for each feature or bug fix, and test your changes in isolation.

When configuring your Encore environment to use Neon, you can choose which project and branch to use. To get started, head to Encore's Cloud Dashboard > (Select your app) > Environments > Create Environment. In the Database section, select Neon database.

Create a new Neon project and branch

If you're starting off a blank slate, you can let Encore create a new Neon project and branch for you. Select New Neon project and choose a Neon account and region. We recommend picking a region close to your compute and that you use the suggested project and branch names, but you're free to choose any configuration you like.

Branch from an existing Encore environment

If you already have an Encore environment with Neon, you can branch your database from that environment. Simply select Branch from Encore environment and choose the environment you want to branch from. This option will be disabled if you don't have any environments using Neon.

Branch from an existing Neon branch

You can also choose to manually select a Neon branch to branch from. This is useful if you have an existing Neon project, but it's not currently being used by any Encore environments. Select Branch from Neon project, then choose the account, project and branch you want to use.

Import an existing Neon branch

The final option is to import an existing Neon branch. This is useful if you have an existing database you want to use. Be wary that this option will not create a new branch but operate on the existing data. Select Import Neon branch, then choose the account, project and branch you want to use.

Edit your Neon environment

Once the environment is created, you can edit the Neon settings by going to Encore's Cloud Dashboard > (Select your app) > Environments > (Select your environment) > Infrastructure. Here you can view and edit your Neon account resources. As a saftety precaution, we've disabled editing of imported resources to prevent accidental changes to shared data.

Neon project

The retention history specifies how long Neon will keep changes to your data. The default is 1 day, but depending on your Neon plan, you can increase this to up to 30 days.

Neon endpoint

Each branch is assigned a unique endpoint which essentially is the serverless compute handling your database. You can edit the endpoint to set the CPU limits and the suspend timeout. The suspend timeout is the time Neon will wait before suspending the compute when it's not in use. The default is 5 minutes, but you can increase this to up to a week (depending on your Neon plan).

Use Neon for PR environments

Neon is a great choice for PR environments as it allows you to branch off a populated database and test your changes in isolation.

To configure which branch to use for PR environments, head to Encore's Cloud Dashboard > (Select your app) > App Settings > Preview Environments and select the environment with the database you want to branch from. Hit save and you're all done.