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:
By passing the API key directly to the client.
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
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.
- 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.
- 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