Manage projects

With Neon, everything starts with the project. It is the top-level object in the Neon object hierarchy. A project can hold as many databases, and with the Neon Pro Plan, as many branches of those databases, as your application or workflow needs. However, tier limits define how many projects you can create. The Neon Free Tier limits you to one project per Neon account.

Learn more about projects and how to manage them in these sections:

• Default resources
• Project Settings
• Basic actions
• Advanced settings
• Manage projects from the API

Default resources

When you add a new project, Neon creates the following resources by default:

• A primary branch called main. You can create child branches from the primary branch or from any previously created branch. For more information, see Manage branches.
• A single read-write compute endpoint. This is the compute instance associated with the branch. For more information, see Manage computes.
• A ready-to-use database, called neondb, which lives in the project's primary branch.
• A default Postgres role that takes its name from your Neon account (the email, Google, GitHub, or partner account that you registered with).

About the Settings page

Once you open a project, you can use the Settings page to manage that particular project and configure any defaults.

You can tab between these sections:

• General — Change the name of your project or copy the project ID.
• Compute — Set the auto-suspend and sizing defaults for any new compute instances you create when branching.
• Storage — Choose how long Neon maintains a history of changes for all branches.
• Sharing — Let other users access your project's databases.
• Delete — Use with care! This action deletes your entire project and all its objects, and is irreversible.

Basic actions

Here are some basic actions you can take to add or manage projects:

• Create a project
• View projects
• Change a project name
• Delete a project
• Share a project

Create a project

The following instructions describe how to create additional Neon projects. If you are creating your very first Neon project, refer to the instructions in Sign up. Neon Free Tier users are limited to a single Neon project. Support for multiple projects is only available to Neon Pro Plan users.

To create a Neon project:

1. Navigate to the Neon Console.

2. Click New Project.

3. Specify values for Name, Postgres version, and Region. Project names are limited to 64 characters. If you are a Neon Pro Plan user, you can specify Compute size settings when creating a project. The settings you specify become the default settings for compute endpoints that you add to your project when creating branches or read replicas.

   • Neon supports fixed size computes and Autoscaling. For more information, see Compute size and Autoscaling configuration.
   • The Suspend compute after a period of inactivity setting defines the period of inactivity after which a compute endpoint is automatically suspended. For more information, see Auto-suspend configuration.

4. Click Create Project.

After creating a project, you are presented with a dialog that provides your connection details for a ready-to-use neondb database. The connection details include your password.

View projects

To view your projects:

1. Navigate to the Neon Console.
2. Select Home or the Neon logo at the top left of the Console.
3. The Projects page lists your projects, including any projects that have been shared with you.

Change the name or copy the ID of your project

You are permitted to change the name of your project at any point. The project ID is permanent.

To edit a Neon project:

1. Navigate to the Neon Console.
2. Select the project that you want to edit.
3. Select Settings.
4. Select General.
5. Make your changes and click Save.

Delete a project

Deleting a project is a permanent action, which also deletes any compute endpoints, branches, databases, and roles that belong to the project.

To delete a project:

1. Navigate to the Neon Console.
2. Select the project that you want to delete.
3. Select Settings.
4. Select Delete.
5. Click Delete project.
6. On the confirmation dialog, click Delete.

Share a project

Project sharing is a Neon Pro Plan feature that allows you to share your project with other Neon accounts.

To share a project:

1. In the Neon Console, select a project.
2. Select Settings.
3. Select Sharing.
4. Under Grant access to your project, enter the email address of the account you want to share access with.
5. Click Grant access.

The email you specify is added to the list of People who have access to the project. The Neon account associated with that email address is granted full access to the project with the exception privileges required to delete the project. When that user logs in to Neon, the shared project is listed on their Projects page, under Shared with me.

The costs associated with a shared project are charged to the Neon account that owns the project. For example, if you were to share your project with another Neon user account, any usage incurred by that user within your project is billed to your Neon account, not theirs.

For additional information, refer to our Project sharing guide.

Advanced settings

From the Settings page, you can also set defaults or apply bulk changes across your Neon objects:

• Reset default compute size (Neon Pro Plan only)
• Configure history retention range

Reset the default compute size

Compute size is the number of Compute Units (CUs) assigned to a Neon compute endpoint. The number of CUs determines the processing capacity of the compute endpoint. One CU is equal to 1 vCPU with 4 GB of RAM. Currently, a Neon compute endpoint can have anywhere from .25 CUs to 7 CUs. Larger compute sizes will be supported in a future release.

For Neon Free Tier users, Neon sets your compute size to a static shared 1 vCPU, with 1 GB of RAM for each branch (max 10 branches).

Neon Pro Plan users have the flexibility to choose a compute size for each branch's compute endpoint individually. By default, new branches inherit the compute endpoint size from your first branch (i.e., main). However, there may be times when you want to reset this default. For example, if you want to create a series of read-only replicas, where each replica typically requires less compute per branch.

To reset the default compute size, go to Settings > Compute.

You can choose from two options:

• Fixed Size: Select a fixed compute size ranging from .25 CUs to 7 CUs. A fixed-size compute does not scale to meet workload demand.
• Autoscaling: This option allows you to specify a minimum and maximum compute size. Neon scales the compute size up and down within the selected compute size boundaries in response to the current load. Currently, Autoscaling supports a range of 1/4 (.25) CU to 7 CUs. The 1/4 CU and 1/2 CU settings are shared compute. For information about how Neon implements the Autoscaling feature, see Autoscaling.

Example: default minimum and maximum autoscale settings

Configure history retention

By default, Neon retains a 7-day history of changes for all branches in a Neon project, which allows you to create a branch that restores data to any point within the defined retention period. The supported range is 0 to 7 days for Neon Free Tier users, and 0 to 30 days for Neon Pro Plan users. Please be aware that increasing the history retention period affects all branches in your project and increases project storage.

To configure the history retention period for a project:

1. Select a project in the Neon console.
2. On the Neon Dashboard, select Settings.
3. Select Storage.
4. Use the slider to select the history retention period.
5. Click Save.

Manage projects with the Neon API

Project actions performed in the Neon Console can also be performed using the Neon API. The following examples demonstrate how to create, view, and delete projects using the Neon API. For other project-related API methods, refer to the Neon API reference.

The jq option specified in each example is an optional third-party tool that formats the JSON response, making it easier to read. For information about this utility, see jq.

Prerequisites

A Neon API request requires an API key. For information about obtaining an API key, see Create an API key. In the cURL examples shown below, $NEON_API_KEY is specified in place of an actual API key, which you must provide when making a Neon API request.

Create a project with the API

The following Neon API method creates a project. The Neon Free Tier permits one project per account. To view the API documentation for this method, refer to the Neon API reference.

The API method appears as follows when specified in a cURL command. The myproject name value is a user-specified name for the project.

The response includes information about the roles, the ready-to-use database (neondb), the primary branch (main), and the read-write compute endpoint that is created with the project.

Response body

List projects with the API

The following Neon API method lists projects for your Neon account. To view the API documentation for this method, refer to the Neon API reference.

The API method appears as follows when specified in a cURL command:

Response body

Update a project with the API

The following Neon API method updates the specified project. To view the API documentation for this method, refer to the Neon API reference.

The API method appears as follows when specified in a cURL command. The project_id is a required parameter. The example changes the project name to project1.

Response body

Delete a project with the API

The following Neon API method deletes the specified project. To view the API documentation for this method, refer to the Neon API reference.

The API method appears as follows when specified in a cURL command. The project_id is a required parameter.

Response body