Neon integration on Vercel: Create a branch for every Preview DeploymentLearn More
Manage

Manage projects

A project is the top-level object in the Neon object hierarchy. Tier limits define how many projects you can create. Neon's free tier permits one project per Neon account.

A Neon project is created with the following resources by default:

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

Create a project

Neon Free Tier users can create a single project. Paid plans can have multiple projects.

To create a Neon project:

  1. Navigate to the Neon Console.
  2. If you are creating your very first project, click Create your first project. Otherwise, click New Project.
  3. Specify a name, a PostgreSQL version, a region, and click Create Project.

Upon creating a project, you are presented with a dialog that provides your connection details for the project, including your password. The password is required to connect to databases in the project from a client or application. Store your password in a safe location.

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.

Edit a project

Only changing the project name and enabling or disabling connection pooling are permitted when editing a project.

To edit a Neon project:

  1. Navigate to the Neon Console.
  2. Select the project that you want to edit.
  3. Select Settings > General.
  4. 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 > General.
  4. Click Delete project.
  5. On the confirmation dialog, click Delete.

Share a project

Neon paid plan users can share a project with other Neon users.

To share a project:

  1. In the Neon Console, select a project.
  2. Select Settings.
  3. Under Grant access to your project, enter the email address of the person you want to share access with.
  4. 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. When that user logs in to Neon, the shared project is listed on their Projects page, under Shared with me.

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.

note

The API examples that follow may not show all of the user-configurable request body attributes that are available to you. To view all of the attributes for a particular method, refer to method's request body schema in 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.

POST /projects

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

curl 'https://console.neon.tech/api/v2/projects' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "project": {
    "name": "myproject"
  }
}' | jq

Response:

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

{
  "project": {
    "cpu_used_sec": 0,
    "id": "odd-cell-528527",
    "platform_id": "aws",
    "region_id": "aws-us-east-2",
    "name": "myproject",
    "provisioner": "k8s-pod",
    "pg_version": 15,
    "locked": false,
    "created_at": "2023-01-04T17:33:11Z",
    "updated_at": "2023-01-04T17:33:11Z",
    "proxy_host": "us-east-2.aws.neon.tech",
    "branch_logical_size_limit": 3072
  },
  "connection_uris": [
    {
      "connection_uri": "postgres://casey:kFbAy47krZeV@odd-cell-528527.us-east-2.aws.neon.tech/neondb"
    }
  ],
  "roles": [
    {
      "branch_id": "br-falling-frost-286006",
      "name": "casey",
      "password": "kFbAy47krZeV",
      "protected": false,
      "created_at": "2023-01-04T17:33:11Z",
      "updated_at": "2023-01-04T17:33:11Z"
    },
    {
      "branch_id": "br-falling-frost-286006",
      "name": "web_access",
      "protected": true,
      "created_at": "2023-01-04T17:33:11Z",
      "updated_at": "2023-01-04T17:33:11Z"
    }
  ],
  "databases": [
    {
      "id": 1138408,
      "branch_id": "br-falling-frost-286006",
      "name": "neondb",
      "owner_name": "casey",
      "created_at": "2023-01-04T17:33:11Z",
      "updated_at": "2023-01-04T17:33:11Z"
    }
  ],
  "operations": [
    {
      "id": "b7c32d83-6402-49c8-b40b-0388309549da",
      "project_id": "odd-cell-528527",
      "branch_id": "br-falling-frost-286006",
      "action": "create_timeline",
      "status": "running",
      "failures_count": 0,
      "created_at": "2023-01-04T17:33:11Z",
      "updated_at": "2023-01-04T17:33:11Z"
    },
    {
      "id": "756f2b87-f45c-4a61-9b21-6cd3f3c48c68",
      "project_id": "odd-cell-528527",
      "branch_id": "br-falling-frost-286006",
      "endpoint_id": "ep-jolly-moon-631024",
      "action": "start_compute",
      "status": "scheduling",
      "failures_count": 0,
      "created_at": "2023-01-04T17:33:11Z",
      "updated_at": "2023-01-04T17:33:11Z"
    }
  ],
  "branch": {
    "id": "br-falling-frost-286006",
    "project_id": "odd-cell-528527",
    "name": "main",
    "current_state": "init",
    "pending_state": "ready",
    "created_at": "2023-01-04T17:33:11Z",
    "updated_at": "2023-01-04T17:33:11Z"
  },
  "endpoints": [
    {
      "host": "ep-jolly-moon-631024.us-east-2.aws.neon.tech",
      "id": "ep-jolly-moon-631024",
      "project_id": "odd-cell-528527",
      "branch_id": "br-falling-frost-286006",
      "autoscaling_limit_min_cu": 1,
      "autoscaling_limit_max_cu": 1,
      "region_id": "aws-us-east-2",
      "type": "read_write",
      "current_state": "init",
      "pending_state": "active",
      "settings": {
        "pg_settings": {}
      },
      "pooler_enabled": false,
      "pooler_mode": "transaction",
      "disabled": false,
      "passwordless_access": true,
      "created_at": "2023-01-04T17:33:11Z",
      "updated_at": "2023-01-04T17:33:11Z",
      "proxy_host": "us-east-2.aws.neon.tech"
    }
  ]
}

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.

GET /projects

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

curl 'https://console.neon.tech/api/v2/projects' \
 -H 'Accept: application/json' \
 -H 'Authorization: Bearer $NEON_API_KEY' | jq

Response:

{
  "projects": [
    {
      "cpu_used_sec": 0,
      "id": "purple-shape-491160",
      "platform_id": "aws",
      "region_id": "aws-us-east-2",
      "name": "purple-shape-491160",
      "provisioner": "k8s-pod",
      "pg_version": 15,
      "locked": false,
      "created_at": "2023-01-03T18:22:56Z",
      "updated_at": "2023-01-03T18:22:56Z",
      "proxy_host": "us-east-2.aws.neon.tech",
      "branch_logical_size_limit": 3072
    }
  ]
}

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.

PATCH /projects/{project_id}

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.

curl 'https://console.neon.tech/api/v2/projects/odd-cell-528527' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "project": {
    "name": "project1"
  }
}'

Response:

{
  "project": {
    "cpu_used_sec": 0,
    "id": "odd-cell-528527",
    "platform_id": "aws",
    "region_id": "aws-us-east-2",
    "name": "project1",
    "provisioner": "k8s-pod",
    "pg_version": 15,
    "locked": false,
    "created_at": "2023-01-04T17:33:11Z",
    "updated_at": "2023-01-04T17:36:17Z",
    "proxy_host": "us-east-2.aws.neon.tech",
    "branch_logical_size_limit": 3072
  },
  "operations": []
}

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.

DELETE /projects/{project_id}

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

curl -X 'DELETE' \
  'https://console.neon.tech/api/v2/projects/odd-cell-528527' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer $NEON_API_KEY'

Response:

{
  "project": {
    "cpu_used_sec": 0,
    "id": "odd-cell-528527",
    "platform_id": "aws",
    "region_id": "aws-us-east-2",
    "name": "project1",
    "provisioner": "k8s-pod",
    "pg_version": 15,
    "locked": false,
    "created_at": "2023-01-04T17:33:11Z",
    "updated_at": "2023-01-04T17:36:17Z",
    "proxy_host": "us-east-2.aws.neon.tech",
    "branch_logical_size_limit": 3072
  }
}

Need help?

Send a request to support@neon.tech, or join the Neon community forum.

PreviousAPI keys
NextBranches
Edit this page
Was this page helpful?