database_instances

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

Overview

Name	database_instances
Type	Resource
Id	databricks_workspace.database.database_instances

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
name	string	The name of the instance. This is the unique identifier for the instance.
effective_usage_policy_id	string	The policy that is applied to the instance. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
usage_policy_id	string	The desired usage policy to associate with the instance.
capacity	string	The sku of the instance. Valid values are "CU_1", "CU_2", "CU_4", "CU_8".
▶child_instance_refs	array	The refs of the child instances. This is only available if the instance is parent instance.
creation_time	string	The timestamp when the instance was created.
creator	string	The email of the creator of the instance.
▶custom_tags	array	Custom tags associated with the instance. This field is only included on create and update responses.
effective_capacity	string	Deprecated. The sku of the instance; this field will always match the value of capacity. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
▶effective_custom_tags	array	The recorded custom tags associated with the instance. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
effective_enable_pg_native_login	boolean	Whether the instance has PG native password login enabled. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
effective_enable_readable_secondaries	boolean	Whether secondaries serving read-only traffic are enabled. Defaults to false. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
effective_node_count	integer	The number of nodes in the instance, composed of 1 primary and 0 or more secondaries. Defaults to 1 primary and 0 secondaries. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
effective_retention_window_in_days	integer	The retention window for the instance. This is the time window in days for which the historical data is retained. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
effective_stopped	boolean	Whether the instance is stopped. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
enable_pg_native_login	boolean	Whether to enable PG native password login on the instance. Defaults to false.
enable_readable_secondaries	boolean	Whether to enable secondaries to serve read-only traffic. Defaults to false.
node_count	integer	The number of nodes in the instance, composed of 1 primary and 0 or more secondaries. Defaults to 1 primary and 0 secondaries. This field is input only, see effective_node_count for the output.
▶parent_instance_ref	object	DatabaseInstanceRef is a reference to a database instance. It is used in the DatabaseInstance<br /> object to refer to the parent instance of an instance and to refer the child instances of an<br /> instance. To specify as a parent instance during creation of an instance, the lsn and<br /> branch_time fields are optional. If not specified, the child instance will be created from the<br /> latest lsn of the parent. If both lsn and branch_time are specified, the lsn will be used to<br /> create the child instance.
pg_version	string	The version of Postgres running on the instance.
read_only_dns	string	The DNS endpoint to connect to the instance for read only access. This is only available if enable_readable_secondaries is true.
read_write_dns	string	The DNS endpoint to connect to the instance for read+write access.
retention_window_in_days	integer	The retention window for the instance. This is the time window in days for which the historical data is retained. The default value is 7 days. Valid values are 2 to 35 days.
state	string	The current state of the instance. (AVAILABLE, DELETING, FAILING_OVER, STARTING, STOPPED, UPDATING)
stopped	boolean	Whether to stop the instance. An input only param, see effective_stopped for the output.
uid	string	An immutable UUID identifier for the instance.

list

Name	Datatype	Description
name	string	The name of the instance. This is the unique identifier for the instance.
effective_usage_policy_id	string	The policy that is applied to the instance. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
usage_policy_id	string	The desired usage policy to associate with the instance.
capacity	string	The sku of the instance. Valid values are "CU_1", "CU_2", "CU_4", "CU_8".
▶child_instance_refs	array	The refs of the child instances. This is only available if the instance is parent instance.
creation_time	string	The timestamp when the instance was created.
creator	string	The email of the creator of the instance.
▶custom_tags	array	Custom tags associated with the instance. This field is only included on create and update responses.
effective_capacity	string	Deprecated. The sku of the instance; this field will always match the value of capacity. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
▶effective_custom_tags	array	The recorded custom tags associated with the instance. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
effective_enable_pg_native_login	boolean	Whether the instance has PG native password login enabled. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
effective_enable_readable_secondaries	boolean	Whether secondaries serving read-only traffic are enabled. Defaults to false. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
effective_node_count	integer	The number of nodes in the instance, composed of 1 primary and 0 or more secondaries. Defaults to 1 primary and 0 secondaries. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
effective_retention_window_in_days	integer	The retention window for the instance. This is the time window in days for which the historical data is retained. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
effective_stopped	boolean	Whether the instance is stopped. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
enable_pg_native_login	boolean	Whether to enable PG native password login on the instance. Defaults to false.
enable_readable_secondaries	boolean	Whether to enable secondaries to serve read-only traffic. Defaults to false.
node_count	integer	The number of nodes in the instance, composed of 1 primary and 0 or more secondaries. Defaults to 1 primary and 0 secondaries. This field is input only, see effective_node_count for the output.
▶parent_instance_ref	object	DatabaseInstanceRef is a reference to a database instance. It is used in the DatabaseInstance<br /> object to refer to the parent instance of an instance and to refer the child instances of an<br /> instance. To specify as a parent instance during creation of an instance, the lsn and<br /> branch_time fields are optional. If not specified, the child instance will be created from the<br /> latest lsn of the parent. If both lsn and branch_time are specified, the lsn will be used to<br /> create the child instance.
pg_version	string	The version of Postgres running on the instance.
read_only_dns	string	The DNS endpoint to connect to the instance for read only access. This is only available if enable_readable_secondaries is true.
read_write_dns	string	The DNS endpoint to connect to the instance for read+write access.
retention_window_in_days	integer	The retention window for the instance. This is the time window in days for which the historical data is retained. The default value is 7 days. Valid values are 2 to 35 days.
state	string	The current state of the instance. (AVAILABLE, DELETING, FAILING_OVER, STARTING, STOPPED, UPDATING)
stopped	boolean	Whether to stop the instance. An input only param, see effective_stopped for the output.
uid	string	An immutable UUID identifier for the instance.

find_by_uid

Name	Datatype	Description
name	string	The name of the instance. This is the unique identifier for the instance.
effective_usage_policy_id	string	The policy that is applied to the instance. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
usage_policy_id	string	The desired usage policy to associate with the instance.
capacity	string	The sku of the instance. Valid values are "CU_1", "CU_2", "CU_4", "CU_8".
▶child_instance_refs	array	The refs of the child instances. This is only available if the instance is parent instance.
creation_time	string	The timestamp when the instance was created.
creator	string	The email of the creator of the instance.
▶custom_tags	array	Custom tags associated with the instance. This field is only included on create and update responses.
effective_capacity	string	Deprecated. The sku of the instance; this field will always match the value of capacity. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
▶effective_custom_tags	array	The recorded custom tags associated with the instance. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
effective_enable_pg_native_login	boolean	Whether the instance has PG native password login enabled. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
effective_enable_readable_secondaries	boolean	Whether secondaries serving read-only traffic are enabled. Defaults to false. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
effective_node_count	integer	The number of nodes in the instance, composed of 1 primary and 0 or more secondaries. Defaults to 1 primary and 0 secondaries. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
effective_retention_window_in_days	integer	The retention window for the instance. This is the time window in days for which the historical data is retained. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
effective_stopped	boolean	Whether the instance is stopped. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.
enable_pg_native_login	boolean	Whether to enable PG native password login on the instance. Defaults to false.
enable_readable_secondaries	boolean	Whether to enable secondaries to serve read-only traffic. Defaults to false.
node_count	integer	The number of nodes in the instance, composed of 1 primary and 0 or more secondaries. Defaults to 1 primary and 0 secondaries. This field is input only, see effective_node_count for the output.
▶parent_instance_ref	object	DatabaseInstanceRef is a reference to a database instance. It is used in the DatabaseInstance<br /> object to refer to the parent instance of an instance and to refer the child instances of an<br /> instance. To specify as a parent instance during creation of an instance, the lsn and<br /> branch_time fields are optional. If not specified, the child instance will be created from the<br /> latest lsn of the parent. If both lsn and branch_time are specified, the lsn will be used to<br /> create the child instance.
pg_version	string	The version of Postgres running on the instance.
read_only_dns	string	The DNS endpoint to connect to the instance for read only access. This is only available if enable_readable_secondaries is true.
read_write_dns	string	The DNS endpoint to connect to the instance for read+write access.
retention_window_in_days	integer	The retention window for the instance. This is the time window in days for which the historical data is retained. The default value is 7 days. Valid values are 2 to 35 days.
state	string	The current state of the instance. (AVAILABLE, DELETING, FAILING_OVER, STARTING, STOPPED, UPDATING)
stopped	boolean	Whether to stop the instance. An input only param, see effective_stopped for the output.
uid	string	An immutable UUID identifier for the instance.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	name, deployment_name		Get a Database Instance.
list	select	deployment_name	page_size, page_token	List Database Instances.
find_by_uid	select	uid, deployment_name		Find a Database Instance by uid.
create	insert	deployment_name, database_instance		Create a Database Instance.
update	update	name, update_mask, deployment_name, database_instance		Update a Database Instance.
delete	delete	name, deployment_name	force, purge	Delete a Database Instance.

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
deployment_name	string	The Databricks Workspace Deployment Name (default: dbc-abcd0123-a1bc)
name	string	Name of the instance to delete.
uid	string	UID of the cluster to get.
update_mask	string
force	boolean	By default, a instance cannot be deleted if it has descendant instances created via PITR. If this flag is specified as true, all descendent instances will be deleted as well.
page_size	integer	Upper bound for items returned.
page_token	string	Pagination token to go to the next page of Database Instances. Requests first page if absent.
purge	boolean	Deprecated. Omitting the field or setting it to true will result in the field being hard deleted. Setting a value of false will throw a bad request.

SELECT examples

get

Get a Database Instance.

SELECT
name,
effective_usage_policy_id,
usage_policy_id,
capacity,
child_instance_refs,
creation_time,
creator,
custom_tags,
effective_capacity,
effective_custom_tags,
effective_enable_pg_native_login,
effective_enable_readable_secondaries,
effective_node_count,
effective_retention_window_in_days,
effective_stopped,
enable_pg_native_login,
enable_readable_secondaries,
node_count,
parent_instance_ref,
pg_version,
read_only_dns,
read_write_dns,
retention_window_in_days,
state,
stopped,
uid
FROM databricks_workspace.database.database_instances
WHERE name = '{{ name }}' -- required
AND deployment_name = '{{ deployment_name }}' -- required
;

list

List Database Instances.

SELECT
name,
effective_usage_policy_id,
usage_policy_id,
capacity,
child_instance_refs,
creation_time,
creator,
custom_tags,
effective_capacity,
effective_custom_tags,
effective_enable_pg_native_login,
effective_enable_readable_secondaries,
effective_node_count,
effective_retention_window_in_days,
effective_stopped,
enable_pg_native_login,
enable_readable_secondaries,
node_count,
parent_instance_ref,
pg_version,
read_only_dns,
read_write_dns,
retention_window_in_days,
state,
stopped,
uid
FROM databricks_workspace.database.database_instances
WHERE deployment_name = '{{ deployment_name }}' -- required
AND page_size = '{{ page_size }}'
AND page_token = '{{ page_token }}'
;

find_by_uid

Find a Database Instance by uid.

SELECT
name,
effective_usage_policy_id,
usage_policy_id,
capacity,
child_instance_refs,
creation_time,
creator,
custom_tags,
effective_capacity,
effective_custom_tags,
effective_enable_pg_native_login,
effective_enable_readable_secondaries,
effective_node_count,
effective_retention_window_in_days,
effective_stopped,
enable_pg_native_login,
enable_readable_secondaries,
node_count,
parent_instance_ref,
pg_version,
read_only_dns,
read_write_dns,
retention_window_in_days,
state,
stopped,
uid
FROM databricks_workspace.database.database_instances
WHERE uid = '{{ uid }}' -- required
AND deployment_name = '{{ deployment_name }}' -- required
;

INSERT examples

create

Create a Database Instance.

INSERT INTO databricks_workspace.database.database_instances (
database_instance,
deployment_name
)
SELECT 
'{{ database_instance }}' /* required */,
'{{ deployment_name }}'
RETURNING
name,
effective_usage_policy_id,
usage_policy_id,
capacity,
child_instance_refs,
creation_time,
creator,
custom_tags,
effective_capacity,
effective_custom_tags,
effective_enable_pg_native_login,
effective_enable_readable_secondaries,
effective_node_count,
effective_retention_window_in_days,
effective_stopped,
enable_pg_native_login,
enable_readable_secondaries,
node_count,
parent_instance_ref,
pg_version,
read_only_dns,
read_write_dns,
retention_window_in_days,
state,
stopped,
uid
;

Manifest

# Description fields are for documentation purposes
- name: database_instances
props:
  - name: deployment_name
    value: "{{ deployment_name }}"
    description: Required parameter for the database_instances resource.
  - name: database_instance
    description: |
      Instance to create.
    value:
      name: "{{ name }}"
      capacity: "{{ capacity }}"
      child_instance_refs:
        - branch_time: "{{ branch_time }}"
          effective_lsn: "{{ effective_lsn }}"
          lsn: "{{ lsn }}"
          name: "{{ name }}"
          uid: "{{ uid }}"
      creation_time: "{{ creation_time }}"
      creator: "{{ creator }}"
      custom_tags:
        - key: "{{ key }}"
          value: "{{ value }}"
      effective_capacity: "{{ effective_capacity }}"
      effective_custom_tags:
        - key: "{{ key }}"
          value: "{{ value }}"
      effective_enable_pg_native_login: {{ effective_enable_pg_native_login }}
      effective_enable_readable_secondaries: {{ effective_enable_readable_secondaries }}
      effective_node_count: {{ effective_node_count }}
      effective_retention_window_in_days: {{ effective_retention_window_in_days }}
      effective_stopped: {{ effective_stopped }}
      effective_usage_policy_id: "{{ effective_usage_policy_id }}"
      enable_pg_native_login: {{ enable_pg_native_login }}
      enable_readable_secondaries: {{ enable_readable_secondaries }}
      node_count: {{ node_count }}
      parent_instance_ref:
        branch_time: "{{ branch_time }}"
        effective_lsn: "{{ effective_lsn }}"
        lsn: "{{ lsn }}"
        name: "{{ name }}"
        uid: "{{ uid }}"
      pg_version: "{{ pg_version }}"
      read_only_dns: "{{ read_only_dns }}"
      read_write_dns: "{{ read_write_dns }}"
      retention_window_in_days: {{ retention_window_in_days }}
      state: "{{ state }}"
      stopped: {{ stopped }}
      uid: "{{ uid }}"
      usage_policy_id: "{{ usage_policy_id }}"

UPDATE examples

update

Update a Database Instance.

UPDATE databricks_workspace.database.database_instances
SET 
database_instance = '{{ database_instance }}'
WHERE 
name = '{{ name }}' --required
AND update_mask = '{{ update_mask }}' --required
AND deployment_name = '{{ deployment_name }}' --required
AND database_instance = '{{ database_instance }}' --required
RETURNING
name,
effective_usage_policy_id,
usage_policy_id,
capacity,
child_instance_refs,
creation_time,
creator,
custom_tags,
effective_capacity,
effective_custom_tags,
effective_enable_pg_native_login,
effective_enable_readable_secondaries,
effective_node_count,
effective_retention_window_in_days,
effective_stopped,
enable_pg_native_login,
enable_readable_secondaries,
node_count,
parent_instance_ref,
pg_version,
read_only_dns,
read_write_dns,
retention_window_in_days,
state,
stopped,
uid;

DELETE examples

delete

Delete a Database Instance.

DELETE FROM databricks_workspace.database.database_instances
WHERE name = '{{ name }}' --required
AND deployment_name = '{{ deployment_name }}' --required
AND force = '{{ force }}'
AND purge = '{{ purge }}'
;