About Neon

Neon is a serverless Postgres database which offers autoscaling, branching, and bottomless storage.

Neon's branching feature is particularly well-suited for development and ephemeral environments, as you can now instantly have an isolated database (or more) for your environment.

Bunnyshell <> Neon connector

Bunnyshell can leverage Neon to create database branches when an Environment is deployed, and have them destroyed when an Environment is deleted from Bunnyshell.

Effectively, this means being able to create ephemeral PostgreSQL databases for ephemeral environments.

Neon can be connected to Bunnyshell by adding a GenericComponent within the Environment.

Pre-requisites

You will need to supply from Neon:

• the API token
  read more in Neon's documentation
• the Project ID
  go to Home > {{ YOUR_PROJECT }} > Settings and get the Project ID
• the source Branch ID
  go to Home > {{ YOUR_PROJECT }} > Branches > {{ YOUR_SOURCE_BRANCH }} and get the ID (it starts with br-)

How to add the Connector

From the UI

You can add a Neon Connector from the Add Component menu within the Environment details screen or the Configuration editor.
Just go to Add Component > Connectors > Neon.

Manually

You can find the connector in our Github repository: https://github.com/bunnyshell/connectors/tree/main/neon-database

The component example is featured in component.yaml file from the repository, while the actual scripts can be found in the scripts folder.

After adding the code to the Configuration editor, make sure to replace the placeholders:

• [[NEON_API_TOKEN]] (see Pre-requisites)
• [[NEON_PROJECT_ID]] (see Pre-requisites)
• [[NEON_SOURCE_BRANCH_ID]] (see Pre-requisites)

How to use the Connector

In the backend Component(s) which use the database, you will need to set the host exported from the Neon Component as an environment variable, so your app can connect to the database.

components:
    - 
        name: backend
        kind: Application
        ...
        dockerCompose:
            environment:
                POSTGRES_HOST: '{{ components.neon-database.exported.DB_HOST }}'
                ...

Neon branch name

You can name your Neon branches as you like, as long as they're unique. The name can be passed to the Neon Component as an environment variable called TARGET_BRANCH_NAME.

For example, you could use TARGET_BRANCH_NAME as bns-{{ env.unique}}.
{{ env.unique}} is an unique identifier for an Environment in Bunnyshell and will be interpolated in the actual value of the Environment variable, resulting in something similar to bns-4wgffz.

Multiple Neon databases in an Environment

You can use as many Neon databases as you need in a single Environment.
Just make sure the component names and the TARGET_BRANCH_NAME have distinct values.