databases

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

Overview

Name	databases
Type	Resource
Id	snowflake.database.databases

Fields

The following fields are returned by SELECT queries:

list_databases

Snowflake database object.

Name	Datatype	Description
name	string	A Snowflake object identifier. If the identifier contains spaces or special characters, the entire string must be enclosed in double quotes. Identifiers enclosed in double quotes are also case-sensitive. (pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$, example: TEST_NAME)
budget	string	Budget that defines a monthly spending limit on the compute costs for a Snowflake account or a custom group of Snowflake objects.
comment	string	Optional comment in which to store information related to the database.
created_on	string (date-time)	Date and time the database was created.
data_retention_time_in_days	integer	Specifies the number of days for which Time Travel actions (CLONE and UNDROP) can be performed on the database, as well as specifying the default Time Travel retention time for all schemas created in the database.
default_ddl_collation	string	Default collation specification for all schemas and tables added to the database. You an override the default at the schema and individual table levels.
dropped_on	string (date-time)	Date and time the database was dropped.
is_current	boolean	Current database for the session.
is_default	boolean	Whether the database is the default database for a user.
kind	string	Database type, permanent (default) or transient. (default: PERMANENT)
log_level	string	Severity level of messages that should be ingested and made available in the active event table. Currently, Snowflake supports only TRACE, DEBUG, INFO, WARN, ERROR, FATAL and OFF.
max_data_extension_time_in_days	integer	Maximum number of days for which Snowflake can extend the data retention period for tables in the database to prevent streams on the tables from becoming stale.
options	string
origin	string
owner	string	Name of the role that owns the database.
owner_role_type	string	Type of role that owns the object, either ROLE or DATABASE_ROLE
retention_time	integer	Number of days that historical data is retained for Time Travel.
serverless_task_max_statement_size	string	Specifies the maximum allowed warehouse size for the serverless task. Minimum XSMALL, Maximum XXLARGE.
serverless_task_min_statement_size	string	Specifies the minimum allowed warehouse size for the serverless task. Minimum XSMALL, Maximum XXLARGE.
suspend_task_after_num_failures	integer	Maximum number of consecutive failed task runs before the current task is suspended automatically.
trace_level	string	How trace events are ingested into the event table. Currently, Snowflake supports only ALWAYS, ON_EVENT, and OFF.
user_task_managed_initial_warehouse_size	string	Size of the compute resources to provision for the first run of the serverless task, before a task history is available for Snowflake to determine an ideal size.
user_task_timeout_ms	integer	Time limit, in milliseconds, for a single run of the task before it times out.

fetch_database

Snowflake database object.

Name	Datatype	Description
name	string	A Snowflake object identifier. If the identifier contains spaces or special characters, the entire string must be enclosed in double quotes. Identifiers enclosed in double quotes are also case-sensitive. (pattern: ^"([^"]|"")+"|[a-zA-Z_][a-zA-Z0-9_$]*$, example: TEST_NAME)
budget	string	Budget that defines a monthly spending limit on the compute costs for a Snowflake account or a custom group of Snowflake objects.
comment	string	Optional comment in which to store information related to the database.
created_on	string (date-time)	Date and time the database was created.
data_retention_time_in_days	integer	Specifies the number of days for which Time Travel actions (CLONE and UNDROP) can be performed on the database, as well as specifying the default Time Travel retention time for all schemas created in the database.
default_ddl_collation	string	Default collation specification for all schemas and tables added to the database. You an override the default at the schema and individual table levels.
dropped_on	string (date-time)	Date and time the database was dropped.
is_current	boolean	Current database for the session.
is_default	boolean	Whether the database is the default database for a user.
kind	string	Database type, permanent (default) or transient. (default: PERMANENT)
log_level	string	Severity level of messages that should be ingested and made available in the active event table. Currently, Snowflake supports only TRACE, DEBUG, INFO, WARN, ERROR, FATAL and OFF.
max_data_extension_time_in_days	integer	Maximum number of days for which Snowflake can extend the data retention period for tables in the database to prevent streams on the tables from becoming stale.
options	string
origin	string
owner	string	Name of the role that owns the database.
owner_role_type	string	Type of role that owns the object, either ROLE or DATABASE_ROLE
retention_time	integer	Number of days that historical data is retained for Time Travel.
serverless_task_max_statement_size	string	Specifies the maximum allowed warehouse size for the serverless task. Minimum XSMALL, Maximum XXLARGE.
serverless_task_min_statement_size	string	Specifies the minimum allowed warehouse size for the serverless task. Minimum XSMALL, Maximum XXLARGE.
suspend_task_after_num_failures	integer	Maximum number of consecutive failed task runs before the current task is suspended automatically.
trace_level	string	How trace events are ingested into the event table. Currently, Snowflake supports only ALWAYS, ON_EVENT, and OFF.
user_task_managed_initial_warehouse_size	string	Size of the compute resources to provision for the first run of the serverless task, before a task history is available for Snowflake to determine an ideal size.
user_task_timeout_ms	integer	Time limit, in milliseconds, for a single run of the task before it times out.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_databases	select	endpoint	like, startsWith, showLimit, fromName, history	Lists the accessible databases.
fetch_database	select	name, endpoint		Fetches a database.
create_database	insert	endpoint	createMode, kind	Creates a database, with modifiers as query parameters. You must provide the full database definition when creating a database.
create_or_alter_database	replace	name, endpoint		Creates a new, or alters an existing, database. You must provide the full database definition even when altering an existing database.
delete_database	delete	name, endpoint	ifExists, restrict	Deletes the specified database. If you enable the ifExists parameter, the operation succeeds even if the database does not exist. Otherwise, a 404 failure is returned if the database does not exist. if the drop is unsuccessful.
create_database_from_share	exec	endpoint	createMode, share	Creates a database from a given share.
create_database_from_share_deprecated	exec	name, endpoint	createMode, share	Creates a database from a given share.
clone_database	exec	name, endpoint	createMode, kind	Clones an existing database, with modifiers as query parameters. You must provide the full database definition when cloning an existing database.
undrop_database	exec	name, endpoint		Undrops database.
enable_database_replication	exec	name, endpoint	ignore_edition_check	Promotes a local database to serve as a primary database for replication. A primary database can be replicated in one or more accounts, allowing users in those accounts to query objects in each secondary (i.e. replica) database.
disable_database_replication	exec	name, endpoint		Disables replication for this primary database, meaning no replica of this database (i.e. secondary database) in another account can be refreshed. Any secondary databases remain linked to the primary database, but requests to refresh a secondary database are denied.
refresh_database_replication	exec	name, endpoint		Refreshes a secondary database from a snapshot of its primary database. A snapshot includes changes to the objects and data. If you call this endpoint while another refresh for the same replica database is running, it fails and returns an error. Snowflake ensures only one refresh is executed at any given time.
enable_database_failover	exec	name, endpoint		Specifies a comma-separated list of accounts in your organization where a replica of this primary database can be promoted to serve as the primary database.
disable_database_failover	exec	name, endpoint		Disables failover for this primary database, meaning no replica of this database (i.e. secondary database) can be promoted to serve as the primary database.
primary_database_failover	exec	name, endpoint		Promotes the specified secondary (replica) database to serve as the primary database. When promoted, the database becomes writeable. At the same time, the previous primary database becomes a read-only secondary database.

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
endpoint	string	Organization and Account Name (default: orgid-acctid)
name	string	Identifier (i.e. name) for the resource.
createMode	string	Query parameter allowing support for different modes of resource creation. Possible values include: - errorIfExists: Throws an error if you try to create a resource that already exists. - orReplace: Automatically replaces the existing resource with the current one. - ifNotExists: Creates a new resource when an alter is requested for a non-existent resource.
fromName	string	Query parameter to enable fetching rows only following the first row whose object name matches the specified string. Case-sensitive and does not have to be the full name.
history	boolean	Optionally includes dropped databases that have not yet been purged.
ifExists	boolean	Query parameter that specifies how to handle the request for a resource that does not exist: - true: The endpoint does not throw an error if the resource does not exist. It returns a 200 success response, but does not take any action on the resource. - false: The endpoint throws an error if the resource doesn't exist.
ignore_edition_check	boolean	Whether to allow replicating data to accounts on lower editions. Default: true. For more information, see the ALTER DATABASE reference.
kind	string	Type of database to create. Currently, Snowflake supports only transient and permanent (also represented by the empty string).
like	string	Query parameter to filter the command output by resource name. Uses case-insensitive pattern matching, with support for SQL wildcard characters.
restrict	boolean	Whether to drop the database if foreign keys exist that reference any tables in the database. - true: Return a warning about existing foreign key references and don't drop the database. - false: Drop the database and all objects in the database, including tables with primary or unique keys that are referenced by foreign keys in other tables.
share	string	ID of the share from which to create the database, in the form "<provider_account>.<share_name>".
showLimit	integer	Query parameter to limit the maximum number of rows returned by a command.
startsWith	string	Query parameter to filter the command output based on the string of characters that appear at the beginning of the object name. Uses case-sensitive pattern matching.

SELECT examples

list_databases

Lists the accessible databases.

SELECT
name,
budget,
comment,
created_on,
data_retention_time_in_days,
default_ddl_collation,
dropped_on,
is_current,
is_default,
kind,
log_level,
max_data_extension_time_in_days,
options,
origin,
owner,
owner_role_type,
retention_time,
serverless_task_max_statement_size,
serverless_task_min_statement_size,
suspend_task_after_num_failures,
trace_level,
user_task_managed_initial_warehouse_size,
user_task_timeout_ms
FROM snowflake.database.databases
WHERE endpoint = '{{ endpoint }}' -- required
AND like = '{{ like }}'
AND startsWith = '{{ startsWith }}'
AND showLimit = '{{ showLimit }}'
AND fromName = '{{ fromName }}'
AND history = '{{ history }}';

fetch_database

Fetches a database.

SELECT
name,
budget,
comment,
created_on,
data_retention_time_in_days,
default_ddl_collation,
dropped_on,
is_current,
is_default,
kind,
log_level,
max_data_extension_time_in_days,
options,
origin,
owner,
owner_role_type,
retention_time,
serverless_task_max_statement_size,
serverless_task_min_statement_size,
suspend_task_after_num_failures,
trace_level,
user_task_managed_initial_warehouse_size,
user_task_timeout_ms
FROM snowflake.database.databases
WHERE name = '{{ name }}' -- required
AND endpoint = '{{ endpoint }}' -- required;

INSERT examples

create_database

Creates a database, with modifiers as query parameters. You must provide the full database definition when creating a database.

INSERT INTO snowflake.database.databases (
data__name,
data__kind,
data__comment,
data__data_retention_time_in_days,
data__default_ddl_collation,
data__log_level,
data__max_data_extension_time_in_days,
data__suspend_task_after_num_failures,
data__trace_level,
data__user_task_managed_initial_warehouse_size,
data__user_task_timeout_ms,
data__serverless_task_min_statement_size,
data__serverless_task_max_statement_size,
endpoint,
createMode,
kind
)
SELECT 
'{{ name }}' --required,
'{{ kind }}',
'{{ comment }}',
{{ data_retention_time_in_days }},
'{{ default_ddl_collation }}',
'{{ log_level }}',
{{ max_data_extension_time_in_days }},
{{ suspend_task_after_num_failures }},
'{{ trace_level }}',
'{{ user_task_managed_initial_warehouse_size }}',
{{ user_task_timeout_ms }},
'{{ serverless_task_min_statement_size }}',
'{{ serverless_task_max_statement_size }}',
'{{ endpoint }}',
'{{ createMode }}',
'{{ kind }}'
;

Manifest

# Description fields are for documentation purposes
- name: databases
  props:
    - name: endpoint
      value: string
      description: Required parameter for the databases resource.
    - name: name
      value: string
      description: >
        A Snowflake object identifier. If the identifier contains spaces or special characters, the entire string must be enclosed in double quotes. Identifiers enclosed in double quotes are also case-sensitive.
        
    - name: kind
      value: string
      description: >
        Database type, permanent (default) or transient.
        
      valid_values: ['PERMANENT', 'TRANSIENT']
      default: PERMANENT
    - name: comment
      value: string
      description: >
        Optional comment in which to store information related to the database.
        
    - name: data_retention_time_in_days
      value: integer
      description: >
        Specifies the number of days for which Time Travel actions (CLONE and UNDROP) can be performed on the database, as well as specifying the default Time Travel retention time for all schemas created in the database.
        
    - name: default_ddl_collation
      value: string
      description: >
        Default collation specification for all schemas and tables added to the database. You an override the default at the schema and individual table levels.
        
    - name: log_level
      value: string
      description: >
        Severity level of messages that should be ingested and made available in the active event table. Currently, Snowflake supports only `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` and `OFF`.
        
    - name: max_data_extension_time_in_days
      value: integer
      description: >
        Maximum number of days for which Snowflake can extend the data retention period for tables in the database to prevent streams on the tables from becoming stale.
        
    - name: suspend_task_after_num_failures
      value: integer
      description: >
        Maximum number of consecutive failed task runs before the current task is suspended automatically.
        
    - name: trace_level
      value: string
      description: >
        How trace events are ingested into the event table. Currently, Snowflake supports only `ALWAYS`, `ON_EVENT`, and `OFF`.
        
    - name: user_task_managed_initial_warehouse_size
      value: string
      description: >
        Size of the compute resources to provision for the first run of the serverless task, before a task history is available for Snowflake to determine an ideal size.
        
    - name: user_task_timeout_ms
      value: integer
      description: >
        Time limit, in milliseconds, for a single run of the task before it times out.
        
    - name: serverless_task_min_statement_size
      value: string
      description: >
        Specifies the minimum allowed warehouse size for the serverless task. Minimum XSMALL, Maximum XXLARGE.
        
    - name: serverless_task_max_statement_size
      value: string
      description: >
        Specifies the maximum allowed warehouse size for the serverless task. Minimum XSMALL, Maximum XXLARGE.
        
    - name: createMode
      value: string
      description: Query parameter allowing support for different modes of resource creation. Possible values include: - `errorIfExists`: Throws an error if you try to create a resource that already exists. - `orReplace`: Automatically replaces the existing resource with the current one. - `ifNotExists`: Creates a new resource when an alter is requested for a non-existent resource.
    - name: kind
      value: string
      description: Type of database to create. Currently, Snowflake supports only `transient` and `permanent` (also represented by the empty string).

REPLACE examples

create_or_alter_database

Creates a new, or alters an existing, database. You must provide the full database definition even when altering an existing database.

REPLACE snowflake.database.databases
SET 
data__name = '{{ name }}',
data__kind = '{{ kind }}',
data__comment = '{{ comment }}',
data__data_retention_time_in_days = {{ data_retention_time_in_days }},
data__default_ddl_collation = '{{ default_ddl_collation }}',
data__log_level = '{{ log_level }}',
data__max_data_extension_time_in_days = {{ max_data_extension_time_in_days }},
data__suspend_task_after_num_failures = {{ suspend_task_after_num_failures }},
data__trace_level = '{{ trace_level }}',
data__user_task_managed_initial_warehouse_size = '{{ user_task_managed_initial_warehouse_size }}',
data__user_task_timeout_ms = {{ user_task_timeout_ms }},
data__serverless_task_min_statement_size = '{{ serverless_task_min_statement_size }}',
data__serverless_task_max_statement_size = '{{ serverless_task_max_statement_size }}'
WHERE 
name = '{{ name }}' --required
AND endpoint = '{{ endpoint }}' --required
AND data__name = '{{ name }}' --required;

DELETE examples

delete_database

Deletes the specified database. If you enable the ifExists parameter, the operation succeeds even if the database does not exist. Otherwise, a 404 failure is returned if the database does not exist. if the drop is unsuccessful.

DELETE FROM snowflake.database.databases
WHERE name = '{{ name }}' --required
AND endpoint = '{{ endpoint }}' --required
AND ifExists = '{{ ifExists }}'
AND restrict = '{{ restrict }}';

Lifecycle Methods

create_database_from_share

Creates a database from a given share.

EXEC snowflake.database.databases.create_database_from_share 
@endpoint='{{ endpoint }}' --required, 
@createMode='{{ createMode }}', 
@share='{{ share }}' 
@@json=
'{
"name": "{{ name }}"
}';

create_database_from_share_deprecated

Creates a database from a given share.

EXEC snowflake.database.databases.create_database_from_share_deprecated 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@createMode='{{ createMode }}', 
@share='{{ share }}';

clone_database

Clones an existing database, with modifiers as query parameters. You must provide the full database definition when cloning an existing database.

EXEC snowflake.database.databases.clone_database 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@createMode='{{ createMode }}', 
@kind='{{ kind }}' 
@@json=
'{
"name": "{{ name }}", 
"kind": "{{ kind }}", 
"comment": "{{ comment }}", 
"data_retention_time_in_days": {{ data_retention_time_in_days }}, 
"default_ddl_collation": "{{ default_ddl_collation }}", 
"log_level": "{{ log_level }}", 
"max_data_extension_time_in_days": {{ max_data_extension_time_in_days }}, 
"suspend_task_after_num_failures": {{ suspend_task_after_num_failures }}, 
"trace_level": "{{ trace_level }}", 
"user_task_managed_initial_warehouse_size": "{{ user_task_managed_initial_warehouse_size }}", 
"user_task_timeout_ms": {{ user_task_timeout_ms }}, 
"serverless_task_min_statement_size": "{{ serverless_task_min_statement_size }}", 
"serverless_task_max_statement_size": "{{ serverless_task_max_statement_size }}"
}';

undrop_database

Undrops database.

EXEC snowflake.database.databases.undrop_database 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required;

enable_database_replication

Promotes a local database to serve as a primary database for replication. A primary database can be replicated in one or more accounts, allowing users in those accounts to query objects in each secondary (i.e. replica) database.

EXEC snowflake.database.databases.enable_database_replication 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@ignore_edition_check={{ ignore_edition_check }} 
@@json=
'{
"accounts": "{{ accounts }}"
}';

disable_database_replication

Disables replication for this primary database, meaning no replica of this database (i.e. secondary database) in another account can be refreshed. Any secondary databases remain linked to the primary database, but requests to refresh a secondary database are denied.

EXEC snowflake.database.databases.disable_database_replication 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required 
@@json=
'{
"accounts": "{{ accounts }}"
}';

refresh_database_replication

Refreshes a secondary database from a snapshot of its primary database. A snapshot includes changes to the objects and data. If you call this endpoint while another refresh for the same replica database is running, it fails and returns an error. Snowflake ensures only one refresh is executed at any given time.

EXEC snowflake.database.databases.refresh_database_replication 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required;

enable_database_failover

Specifies a comma-separated list of accounts in your organization where a replica of this primary database can be promoted to serve as the primary database.

EXEC snowflake.database.databases.enable_database_failover 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required 
@@json=
'{
"accounts": "{{ accounts }}"
}';

disable_database_failover

Disables failover for this primary database, meaning no replica of this database (i.e. secondary database) can be promoted to serve as the primary database.

EXEC snowflake.database.databases.disable_database_failover 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required 
@@json=
'{
"accounts": "{{ accounts }}"
}';

primary_database_failover

Promotes the specified secondary (replica) database to serve as the primary database. When promoted, the database becomes writeable. At the same time, the previous primary database becomes a read-only secondary database.

EXEC snowflake.database.databases.primary_database_failover 
@name='{{ name }}' --required, 
@endpoint='{{ endpoint }}' --required;