branches

Creates, updates, deletes, gets or lists a branches resource.

Overview

Name	branches
Type	Resource
Id	netlify.database.branches

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
connection_string	string	The connection string for the database branch
metadata	object	Metadata associated with the branch

list

Name	Datatype	Description
name	string	The branch name
branch_id	string	The branch identifier
compute	object	Compute endpoint status for a branch
connection_string	string	The connection string for the branch
created_at	string (dateTime)	When the branch was created
last_active_at	string (dateTime)	When the branch was last active
logical_size_bytes	integer (int64)	The logical size of the branch in bytes
metadata	object	Metadata associated with the branch
state	string	The current state of the branch (init, creating, resetting, ready, archived)
updated_at	string (dateTime)	When the branch was last updated

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	site_id, branch_id	role	Returns the database branch connection string for a specific branch.
list	select	site_id		Returns all branches for the site's database with compute status and metadata.
create	insert	site_id, branch_id		Creates a new database branch. If a branch already exists for the specified branch ID, returns the existing connection string.
delete	delete	site_id, branch_id		Deletes a database branch.
reset	exec	site_id, branch_id	force, role	Resets a non-production database branch by re-forking it from a source branch (defaults to the production branch). If the target branch is already in sync with the source, returns the existing connection string without performing a reset, unless force=true is passed. The production branch cannot be reset.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
branch_id	string	The branch ID to reset
site_id	string
force	boolean	If true, resets the branch even when it is already in sync with the source.
role	string	The database role to use for the returned connection string. Defaults to netlifydb_owner if not specified.

SELECT examples

get

Returns the database branch connection string for a specific branch.

SELECT
connection_string,
metadata
FROM netlify.database.branches
WHERE site_id = '{{ site_id }}' -- required
AND branch_id = '{{ branch_id }}' -- required
AND role = '{{ role }}'
;

list

Returns all branches for the site's database with compute status and metadata.

SELECT
name,
branch_id,
compute,
connection_string,
created_at,
last_active_at,
logical_size_bytes,
metadata,
state,
updated_at
FROM netlify.database.branches
WHERE site_id = '{{ site_id }}' -- required
;

INSERT examples

create

Creates a new database branch. If a branch already exists for the specified branch ID, returns the existing connection string.

INSERT INTO netlify.database.branches (
parent_branch_id,
branch_id,
metadata,
site_id
)
SELECT 
'{{ parent_branch_id }}',
'{{ branch_id }}' /* required */,
'{{ metadata }}',
'{{ site_id }}'
RETURNING
connection_string,
metadata
;

Manifest

# Description fields are for documentation purposes
- name: branches
props:
  - name: site_id
    value: "{{ site_id }}"
    description: Required parameter for the branches resource.
  - name: parent_branch_id
    value: "{{ parent_branch_id }}"
    description: |
      The ID of the parent branch to create the new branch from. Defaults to the production branch if not specified.
  - name: branch_id
    value: "{{ branch_id }}"
    description: |
      The branch identifier
  - name: metadata
    value: "{{ metadata }}"
    description: |
      Arbitrary metadata to associate with the branch

DELETE examples

delete

Deletes a database branch.

DELETE FROM netlify.database.branches
WHERE site_id = '{{ site_id }}' --required
AND branch_id = '{{ branch_id }}' --required
;

Lifecycle Methods

reset

Resets a non-production database branch by re-forking it from a source branch (defaults to the production branch). If the target branch is already in sync with the source, returns the existing connection string without performing a reset, unless force=true is passed. The production branch cannot be reset.

EXEC netlify.database.branches.reset 
@site_id='{{ site_id }}' --required, 
@branch_id='{{ branch_id }}' --required, 
@force={{ force }}, 
@role='{{ role }}' 
@@json=
'{
"source_branch_id": "{{ source_branch_id }}"
}'
;