neon-api — Python client for the Neon API.

This is the documentation for the neon_api package. It is a Python client for the Neon API. neon_api empowers developers by providing a comprehensive Python wrapper around the Neon API. This enables seamless integration of Neon’s cloud database capabilities into Python applications, facilitating a wide range of operations such as managing API keys, projects, branches, databases, endpoints, roles, and operations directly from your codebase.

With neon_api, developers can:

  • Automate the provisioning and management of Neon cloud databases.

  • Programmatically control and manipulate database endpoints and roles.

  • Streamline workflows by integrating database operations into CI/CD pipelines.

  • Enhance application security by managing API keys and permissions through code.

  • Leverage the power of Neon’s cloud database without the need for manual intervention or the Neon console.

This project simplifies the complexity of interacting with the Neon API, making it more accessible for developers to build scalable, data-driven applications with ease. Pydantic dataclasses are used to represent the data structures returned by the API, and the client provides a relatively transparent interface to the Neon API.

Installation

To install the package, run the following command:

$ pip install neon-api

Note

The package requires Python 3.9 or later.

Usage

To use the package, you need to have a valid API key. You can obtain an API key from the Neon console. Once you have an API key, you can use the neon_api package to interact with the Neon API.

There are two ways to initialize the client:

  1. By passing the API key directly to the client.

  2. By setting the API key as an environment variable and using the from_environ method.

We recommend using the second method to avoid exposing your API key in your codebase:

$ export NEON_API_KEY=your_api_key

Then, from Python…

from neon_api import NeonAPI

neon = NeonAPI.from_environ()

Quickstart

Below is an example of how to use the package to interact with the Neon API:

from neon_api import NeonAPI

# Initialize the client.
neon = NeonAPI.from_environ() or NeonAPI(api_key='your_api_key')

# Get the current user
user = neon.me()
print(user)

# Get a list of API keys
keys = neon.api_keys()
print(keys)

# Create a new API key
new_key = neon.api_key_create(name="new_key")
print(new_key)

# Revoke an API key
revoked_key = neon.api_key_revoke(api_key_id="api_key_id_to_revoke")
print(revoked_key)

Please reference the API Reference section for a comprehensive list of available methods and classes.

API Reference

The following sections provide detailed information about the classes and methods available in the neon_client package

Module–level functions

neon_api.from_environ()[source]

Create a NeonAPI instance from environment variables.

neon_api.from_token(token)[source]

Create a NeonAPI instance from a token.

Classes

class neon_api.NeonAPI(api_key: str, *, base_url: str = None)[source]

Bases: object

api_key_create(**json: dict) → Dict[str, Any][source]

Create a new API key.

Parameters:

json – The JSON paypload to send to the server.

Returns:

A dataclass representing the API key.

Example usage:

>>> neon.api_key_create(name="My API Key")

More info: https://api-docs.neon.tech/reference/createapikey

api_key_revoke(api_key_id: str) → Dict[str, Any][source]

Revoke an API key.

Parameters:

api_key_id – The ID of the API key to revoke.

Returns:

A dataclass representing the API key.

More info: https://api-docs.neon.tech/reference/revokeapikey

api_keys() → List[Dict[str, Any]][source]

Get a list of API keys.

Returns:

A dataclass representing the API key.

More info: https://api-docs.neon.tech/reference/listapikeys

branch(project_id: str, branch_id: str) → Dict[str, Any][source]

Get a branch.

Parameters:

  • project_id – The ID of the project.

  • branch_id – The ID of the branch.

Returns:

A dataclass representing the branch.

More info: https://api-docs.neon.tech/reference/getprojectbranch

branch_create(project_id: str, **json: dict) → Dict[str, Any][source]

Create a new branch. Accepts all keyword arguments for json body.

Parameters:

  • project_id – The ID of the project.

  • json – The JSON paypload to send to the server.

Returns:

A dataclass representing the branch.

More info: https://api-docs.neon.tech/reference/createprojectbranch

branch_delete(project_id: str, branch_id: str) → Dict[str, Any][source]

Delete a branch by branch_id.

Parameters:

  • project_id – The ID of the project.

  • branch_id – The ID of the branch.

Returns:

A dataclass representing the branch.

More info: https://api-docs.neon.tech/reference/deleteprojectbranch

branch_set_as_primary(project_id: str, branch_id: str) → Dict[str, Any][source]

Set a branch as primary by branch_id.

Parameters:

  • project_id – The ID of the project.

  • branch_id – The ID of the branch.

Returns:

A dataclass representing the branch.

More info: https://api-docs.neon.tech/reference/setprimaryprojectbranch

branch_update(project_id: str, branch_id: str, **json: dict) → Dict[str, Any][source]

Update a branch by branch_id. Accepts all keyword arguments for json body.

Parameters:

  • project_id – The ID of the project.

  • branch_id – The ID of the branch.

  • json – The JSON paypload to send to the server.

Returns:

A dataclass representing the branch.

More info: https://api-docs.neon.tech/reference/updateprojectbranch

branches(project_id: str, *, cursor: str = None, limit: int = None) → Dict[str, Any][source]

Get a list of branches.

Parameters:

  • project_id – The ID of the project.

  • cursor – The cursor for pagination (default is None).

  • limit – The maximum number of projects to retrieve (default is None).

Returns:

A list of dataclasses representing the projects.

More info: https://api-docs.neon.tech/reference/listprojectbranches

consumption(*, cursor: str = None, limit: int = None, from_date: datetime = None, to_date: datetime = None) → Dict[str, Any][source]

Experimental — get a list of consumption metrics for all projects.

Parameters:

  • cursor – The cursor for pagination (default is None).

  • limit – The maximum number of projects to retrieve (default is None).

  • from_date – The start date for the consumption metrics (default is None).

  • to_date – The end date for the consumption metrics (default is None).

Returns:

A dataclass representing the consumption metrics.

More info: https://api-docs.neon.tech/reference/listprojectsconsumption

database(project_id: str, branch_id: str, database_id: str) → Dict[str, Any][source]

Get a database.

Parameters:

  • project_id – The ID of the project.

  • branch_id – The ID of the branch.

  • database_id – The ID of the database.

Returns:

A dataclass representing the database.

More info: https://api-docs.neon.tech/reference/getprojectbranchdatabase

database_create(project_id: str, branch_id: str, **json: dict) → Dict[str, Any][source]

Create a new database. Accepts all keyword arguments for json body.

Parameters:

  • project_id – The ID of the project.

  • branch_id – The ID of the branch.

  • json – The JSON paypload to send to the server.

Returns:

A dataclass representing the database.

More info: https://api-docs.neon.tech/reference/createprojectbranchdatabase

database_delete(project_id: str, branch_id: str, database_id: str) → Dict[str, Any][source]

Delete a database by database_id.

Parameters:

  • project_id – The ID of the project.

  • branch_id – The ID of the branch.

  • database_id – The ID of the database.

Returns:

A dataclass representing the database.

More info: https://api-docs.neon.tech/reference/deleteprojectbranchdatabase

database_update(project_id: str, branch_id: str, database_id: str, **json: dict) → Dict[str, Any][source]

Update a database. Accepts all keyword arguments for json body.

Parameters:

  • project_id – The ID of the project.

  • branch_id – The ID of the branch.

  • database_id – The ID of the database.

  • json – The JSON paypload to send to the server.

Returns:

A dataclass representing the database.

More info: https://api-docs.neon.tech/reference/updateprojectbranchdatabase

databases(project_id: str, branch_id: str, *, cursor: str = None, limit: int = None) → List[Dict[str, Any]][source]

Get a list of databases.

Parameters:

  • project_id – The ID of the project.

  • branch_id – The ID of the branch.

  • cursor – The cursor for pagination (default is None).

  • limit – The maximum number of projects to retrieve (default is None).

Returns:

A list of dataclasses representing the database.

More info: https://api-docs.neon.tech/reference/listprojectbranchdatabases

endpoint(project_id: str, endpoint_id: str) → Dict[str, Any][source]

Get an endpoint for a given branch.

Parameters:

  • project_id – The ID of the project.

  • endpoint_id – The ID of the endpoint.

Returns:

A dataclass representing the endpoint.

More info: https://api-docs.neon.tech/reference/getprojectendpoint

endpoint_create(project_id: str, **json: dict) → Dict[str, Any][source]

Create a new endpoint. Accepts all keyword arguments for json body.

Parameters:

  • project_id – The ID of the project.

  • json – The JSON paypload to send to the server.

Returns:

A dataclass representing the endpoint.

More info: https://api-docs.neon.tech/reference/createprojectendpoint

endpoint_delete(project_id: str, endpoint_id: str) → Dict[str, Any][source]

Delete an endpoint by endpoint_id.

Parameters:

  • project_id – The ID of the project.

  • endpoint_id – The ID of the endpoint.

Returns:

A dataclass representing the endpoint.

More info: https://api-docs.neon.tech/reference/deleteprojectendpoint

endpoint_start(project_id: str, endpoint_id: str)[source]

Start an endpoint by endpoint_id.

Parameters:

  • project_id – The ID of the project.

  • endpoint_id – The ID of the endpoint.

Returns:

A dataclass representing the endpoint.

More info: https://api-docs.neon.tech/reference/startprojectendpoint

endpoint_suspend(project_id: str, endpoint_id: str)[source]

Suspend an endpoint by endpoint_id.

Parameters:

  • project_id – The ID of the project.

  • endpoint_id – The ID of the endpoint.

Returns:

A dataclass representing the endpoint.

More info: https://api-docs.neon.tech/reference/suspendprojectendpoint

endpoint_update(project_id: str, endpoint_id: str, **json: dict) → Dict[str, Any][source]

Update an endpoint. Accepts all keyword arguments for json body.

Parameters:

  • project_id – The ID of the project.

  • endpoint_id – The ID of the endpoint.

  • json – The JSON paypload to send to the server.

Returns:

A dataclass representing the endpoint.

More info: https://api-docs.neon.tech/reference/updateprojectendpoint

endpoints(project_id: str) → Dict[str, Any][source]

Get a list of endpoints for a given branch

Parameters:

project_id – The ID of the project.

Returns:

A list of dataclasses representing the endpoints.

More info: https://api-docs.neon.tech/reference/listprojectendpoints

classmethod from_environ()[source]

Create a new Neon API client from the NEON_API_KEY environment variable.

me() → Dict[str, Any][source]

Get the current user.

More info: https://api-docs.neon.tech/reference/getcurrentuserinfo

operation(project_id: str, operation_id: str) → Dict[str, Any][source]

Get an operation.

Parameters:

  • project_id – The ID of the project.

  • operation_id – The ID of the operation.

Returns:

A dataclass representing the operation.

More info: https://api-docs.neon.tech/reference/getprojectoperation

operations(project_id: str, *, cursor: str = None, limit: int = None) → Dict[str, Any][source]

Get a list of operations.

Parameters:

  • project_id – The ID of the project.

  • cursor – The cursor for pagination (default is None).

  • limit – The maximum number of projects to retrieve (default is None).

Returns:

A list of dataclasses representing the operations.

More info: https://api-docs.neon.tech/reference/listprojectoperations

project(project_id: str) → Dict[str, Any][source]

Get a project.

Parameters:

project_id – The ID of the project.

Returns:

A dataclass representing the project.

More info: https://api-docs.neon.tech/reference/getproject

project_create(**json: dict) → Dict[str, Any][source]

Create a new project. Accepts all keyword arguments for json body.

Parameters:

json – The JSON paypload to send to the server.

Returns:

A dataclass representing the project.

More info: https://api-docs.neon.tech/reference/createproject

project_delete(project_id: str) → Dict[str, Any][source]

Delete a project.

Parameters:

project_id – The ID of the project.

Returns:

A dataclass representing the project.

More info: https://api-docs.neon.tech/reference/deleteproject

project_permissions(project_id: str) → Dict[str, Any][source]

Get a project permissions.

Parameters:

project_id – The ID of the project.

Returns:

A dataclass representing the project permissions.

More info: https://api-docs.neon.tech/reference/listprojectpermissions

project_permissions_grant(project_id: str, **json: dict) → Dict[str, Any][source]

Update a project permissions. Accepts all keyword arguments for json body.

Parameters:

  • project_id – The ID of the project.

  • json – The JSON paypload to send to the server.

Returns:

A dataclass representing the project permissions.

More info: https://api-docs.neon.tech/reference/grantpermissiontoproject

project_permissions_revoke(project_id: str, **json: dict) → Dict[str, Any][source]

Update a project permissions. Accepts all keyword arguments for json body.

Parameters:

  • project_id – The ID of the project.

  • json – The JSON paypload to send to the server.

Returns:

A dataclass representing the project permissions.

More info: https://api-docs.neon.tech/reference/revokepermissionfromproject

project_update(project_id: str, **json: dict) → Dict[str, Any][source]

Updates a project. Accepts all keyword arguments for json body.

Parameters:

  • project_id – The ID of the project.

  • json – The JSON paypload to send to the server.

Returns:

A dataclass representing the project.

More info: https://api-docs.neon.tech/reference/updateproject

projects(*, shared: bool = False, cursor: str = None, limit: int = None) → List[Dict[str, Any]][source]

Get a list of projects. If shared is True, get a list of shared projects.

Parameters:

  • shared – Whether to retrieve shared projects (default is False).

  • cursor – The cursor for pagination (default is None).

  • limit – The maximum number of projects to retrieve (default is None).

Returns:

A list of dataclasses representing the projects.

More info: https://api-docs.neon.tech/reference/listprojects

role(project_id: str, branch_id: str, role_name: str) → Dict[str, Any][source]

Get a role for a given branch.

Parameters:

  • project_id – The ID of the project.

  • branch_id – The ID of the branch.

  • role_name – The name of the role.

Returns:

A dataclass representing the role.

More info: https://api-docs.neon.tech/reference/getprojectbranchrole

role_create(project_id: str, branch_id: str, role_name: str) → Dict[str, Any][source]

Create a new role. Accepts all keyword arguments for json body.

Parameters:

  • project_id – The ID of the project.

  • branch_id – The ID of the branch.

  • role_name – The name of the role.

Returns:

A dataclass representing the role.

More info: https://api-docs.neon.tech/reference/createprojectbranchrole

role_delete(project_id: str, branch_id: str, role_name: str) → Dict[str, Any][source]

Delete a role by given role name.

Parameters:

  • project_id – The ID of the project.

  • branch_id – The ID of the branch.

  • role_name – The name of the role.

Returns:

A dataclass representing the role.

More info: https://api-docs.neon.tech/reference/deleteprojectbranchrole

role_password_reset(project_id: str, branch_id: str, role_name: str) → Dict[str, Any][source]

Reset a role password.

Parameters:

  • project_id – The ID of the project.

  • branch_id – The ID of the branch.

  • role_name – The name of the role.

Returns:

A dataclass representing the role.

More info: https://api-docs.neon.tech/reference/resetprojectbranchrolepassword

role_password_reveal(project_id: str, branch_id: str, role_name: str) → Dict[str, Any][source]

Get a role password.

Parameters:

  • project_id – The ID of the project.

  • branch_id – The ID of the branch.

  • role_name – The name of the role.

Returns:

A dataclass representing the role password.

More info: https://api-docs.neon.tech/reference/getprojectbranchrolepassword

roles(project_id: str, branch_id: str) → Dict[str, Any][source]

Get a list of roles for a given branch.

Parameters:

  • project_id – The ID of the project.

  • branch_id – The ID of the branch.

Returns:

A list of dataclasses representing the roles.

More info: https://api-docs.neon.tech/reference/listprojectbranchroles

Indices and tables