CREATE DATABASE¶

Sintaxe¶

Banco de dados padrão

CREATE [ OR REPLACE ] [ TRANSIENT ] DATABASE [ IF NOT EXISTS ] <name>
    [ CLONE <source_db>
          [ { AT | BEFORE } ( { TIMESTAMP => <timestamp> | OFFSET => <time_difference> | STATEMENT => <id> } ) ] ]
    [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
    [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
    [ EXTERNAL_VOLUME = <external_volume_name> ]
    [ CATALOG = <catalog_integration_name> ]
    [ DEFAULT_DDL_COLLATION = '<collation_specification>' ]
    [ COMMENT = '<string_literal>' ]
    [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

Banco de dados compartilhado (de um compartilhamento)

CREATE DATABASE <name> FROM SHARE <provider_account>.<share_name>

Banco de dados secundário (Replicação de banco de dados)

CREATE DATABASE <name>
    AS REPLICA OF <account_identifier>.<primary_db_name>
    [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]

Parâmetros obrigatórios¶

name

Especifica o identificador do banco de dados; deve ser único para sua conta.

Além disso, o identificador deve começar com um caractere alfabético e não pode conter espaços ou caracteres especiais, a menos que toda a cadeia de caracteres do identificador esteja entre aspas duplas (por exemplo, "My object"). Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

Para obter mais detalhes, consulte Requisitos para identificadores.

Importante

Como prática recomendada para Replicação e failover do banco de dados, recomendamos dar a cada banco de dados secundário o mesmo nome de seu banco de dados primário. Esta prática oferece suporte a fazer referência a objetos totalmente qualificados (ou seja, '<bd>.<esquema>.<objeto>') por outros objetos no mesmo banco de dados, como a consulta de um nome de tabela totalmente qualificado em uma exibição.

Se um banco de dados secundário tiver um nome diferente do banco de dados primário, então estas referências de objetos seriam desfeitas no banco de dados secundário.

Parâmetros opcionais¶

TRANSIENT

Especifica um banco de dados como transitório. Os bancos de dados transitórios não têm um período de Fail-safe, de modo que não incorrem em custos adicionais de armazenamento uma vez que saem do Time Travel; no entanto, isto significa que também não estão protegidos pelo Fail-safe no caso de perda de dados. Para obter mais informações, consulte Explicação e visualização do Fail-safe.

Além disso, por definição, todos os esquemas (e consequentemente todas as tabelas) criados em um banco de dados transitório são transitórios. Para obter mais informações sobre tabelas transitórias, consulte CREATE TABLE.

Padrão: sem valor (ou seja, banco de dados é permanente)

CLONE source_db

Especifica a criação de um clone do banco de dados da fonte especificada. Para obter mais detalhes sobre a clonagem de um banco de dados, consulte CREATE <objeto> … CLONE.

AT | BEFORE ( TIMESTAMP => timestamp | OFFSET => time_difference | STATEMENT => id )

Ao clonar um banco de dados, a cláusula AT | BEFORE especifica o uso de Time Travel para clonar o banco de dados em ou antes de um ponto específico no passado. Se a hora do Time Travel especificada for no momento ou antes do momento em que o banco de dados foi criado, a operação de clonagem falhará com um erro.

DATA_RETENTION_TIME_IN_DAYS = integer

Especifica o número de dias para os quais as ações de Time Travel (CLONE e UNDROP) podem ser executadas no banco de dados, bem como especifica o tempo padrão de retenção do Time Travel para todos os esquemas criados no banco de dados. Para obter mais detalhes, consulte Compreensão e uso do Time Travel.

Para uma descrição detalhada deste parâmetro de nível de objeto, bem como mais informações sobre parâmetros de objeto, consulte Parâmetros.

Valores:

• Standard Edition: 0 ou 1

• Enterprise Edition:

  • 0 a 90 para bancos de dados permanentes

  • 0 ou 1 para bancos de dados transitórios

Padrão:

• Standard Edition: 1

• Enterprise Edition (ou superior): 1 (a menos que um valor padrão diferente tenha sido especificado no nível da conta)

Nota

Um valor de 0 efetivamente desabilita o Time Travel para o banco de dados.

MAX_DATA_EXTENSION_TIME_IN_DAYS = integer

Parâmetro de objeto que especifica o número máximo de dias para os quais o Snowflake pode estender o período de retenção de dados das tabelas no banco de dados para evitar que os fluxos nas tabelas se tornem obsoletos.

Para uma descrição detalhada deste parâmetro, consulte MAX_DATA_EXTENSION_TIME_IN_DAYS.

EXTERNAL_VOLUME = external_volume_name

Parâmetro de objeto que especifica o volume externo padrão a ser usado para tabelas Iceberg.

Para obter mais informações sobre este parâmetro, consulte EXTERNAL_VOLUME.

CATALOG = catalog_integration_name

Parâmetro de objeto que especifica a integração de catálogo padrão a ser usada para tabelas Iceberg.

Para obter mais informações sobre este parâmetro, consulte CATALOG.

DEFAULT_DDL_COLLATION = 'collation_specification'

Determina uma especificação de agrupamento padrão para todos os esquemas e tabelas adicionados ao banco de dados. O padrão pode ser anulado no nível do esquema e da tabela individual.

Para obter mais detalhes sobre o parâmetro, consulte DEFAULT_DDL_COLLATION.

COMMENT = 'string_literal'

Especifica um comentário para o banco de dados.

Padrão: sem valor

TAG ( tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ] )

Especifica o nome da tag e o valor da cadeia de caracteres dela.

O valor de tag é sempre uma cadeia de caracteres, e o número máximo de caracteres do valor da tag é 256.

Para obter informações sobre como especificar tags em uma instrução, consulte Cotas de tags para objetos e colunas.

Requisitos de controle de acesso¶

Uma função usada para executar este comando SQL deve ter os seguintes privilégios no mínimo:

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Notas de uso geral¶

• A criação de um banco de dados o define automaticamente como o banco de dados ativo/atual para a sessão atual (equivalente a usar o comando USE DATABASE para o banco de dados).

• Se já existir um banco de dados com o mesmo nome, um erro será retornado e o banco de dados não é criado, a menos que a palavra-chave opcional OR REPLACE seja especificada no comando.

  Importante

  Usar OR REPLACE é o equivalente a usar DROP DATABASE no banco de dados existente e depois criar um novo banco de dados com o mesmo nome; entretanto, o banco de dados descartado não é permanentemente removido do sistema. Em vez disso, ela fica retida no Time Travel. Isto é importante porque os bancos de dados descartados no Time Travel contribuem para o armazenamento de dados de sua conta. Para obter mais informações, consulte Custos de armazenamento para Time Travel e Fail-safe.

• Instruções CREATE OR REPLACE <object> são atômicas. Ou seja, quando um objeto é substituído, o objeto antigo é excluído e o novo objeto é criado em uma única transação.

• A criação de um novo banco de dados cria automaticamente dois esquemas no banco de dados:

  • PUBLIC: esquema padrão para o banco de dados.

  • INFORMATION_SCHEMA: esquema que contém exibições e funções de tabela que podem ser usadas para consultar metadados sobre os objetos do banco de dados, bem como sobre todos os objetos da conta.

• Os bancos de dados criados a partir de compartilhamentos diferem dos bancos de dados padrão nas seguintes formas:

  • Eles não têm os esquemas PUBLIC ou INFORMATION_SCHEMA, a menos que estes esquemas tenham sido explicitamente concedidos ao compartilhamento.

  • Eles não podem ser clonados.

  • Propriedades, como TRANSIENT e DATA_RETENTION_TIME_IN_DAYS, não se aplicam.

• Quando um banco de dados está ativo/atual, o esquema PUBLIC também estará ativo/atual por padrão, a menos que um esquema diferente seja usado ou que o esquema PUBLIC tenha sido descartado.

• Em relação aos metadados:

  Atenção

  Os clientes devem garantir que nenhum dado pessoal (exceto para um objeto do usuário), dados sensíveis, dados controlados por exportação ou outros dados regulamentados sejam inseridos como metadados ao usar o serviço Snowflake. Para obter mais informações, consulte Campos de metadados no Snowflake.

Notas de uso da replicação de banco de dados¶

• A replicação do banco de dados utiliza recursos computacionais fornecidos pelo Snowflake em vez de seu próprio warehouse virtual para copiar objetos e dados. Entretanto, o parâmetro STATEMENT_TIMEOUT_IN_SECONDS de sessão/objeto ainda controla por quanto tempo uma instrução é executada antes de ser cancelada. O valor padrão é 172800 (2 dias). Como a replicação inicial de um banco de dados primário pode levar mais do que 2 dias para ser concluída (dependendo da quantidade de metadados no banco de dados, assim como a quantidade de dados nos objetos de banco de dados), recomendamos aumentar o valor de STATEMENT_TIMEOUT_IN_SECONDS para 604800 (7 dias, o valor máximo) para a sessão em que se executa a operação de replicação.

  Execute a seguinte instrução ALTER SESSION antes de executar a instrução ALTER DATABASE secondary_db_name REFRESH na mesma sessão:

  ALTER SESSION SET STATEMENT_TIMEOUT_IN_SECONDS = 604800;
  

  Copy

  Observe que o parâmetro STATEMENT_TIMEOUT_IN_SECONDS também se aplica ao warehouse ativo em uma sessão. O parâmetro honra o valor mais baixo definido no nível da sessão ou do warehouse. Se você tiver um warehouse ativo na sessão atual, defina também STATEMENT_TIMEOUT_IN_SECONDS como 604800 para este warehouse (usando ALTER WAREHOUSE).

  Por exemplo:

  -- determine the active warehouse in the current session (if any)
  SELECT CURRENT_WAREHOUSE();
  
  +---------------------+
  | CURRENT_WAREHOUSE() |
  |---------------------|
  | MY_WH               |
  +---------------------+
  
  -- change the STATEMENT_TIMEOUT_IN_SECONDS value for the active warehouse
  
  ALTER WAREHOUSE my_wh SET STATEMENT_TIMEOUT_IN_SECONDS = 604800;
  

  Copy

  Você pode redefinir o valor do parâmetro para o padrão depois que a operação de replicação for concluída:

  ALTER WAREHOUSE my_wh UNSET STATEMENT_TIMEOUT_IN_SECONDS;
  

  Copy

• O método preferido para identificar a conta que armazena o banco de dados primário usa o nome da organização e o nome da conta como o identificador da conta. Se você decidir usar o localizador de conta de legado em seu lugar, pode ser necessário que ele contenha segmentos adicionais para identificar a conta de forma única. Consulte a tabela abaixo para referência:

  Identificador da conta	Localização da conta remota
  organization_name.account_name	Identificador de conta preferido que pode ser usado independentemente da região ou grupo de regiões da conta que armazena o banco de dados primário.
  account_locator	A mesma região, mas uma conta diferente da conta que armazena o banco de dados primário.
  snowflake_region.account_locator	O mesmo grupo regional, mas uma região diferente da conta que armazena o banco de dados primário.
  region_group.snowflake_region.account_locator	Grupo de regiões diferente da conta que armazena o banco de dados primário.

• O comando CREATE DATABASE … AS REPLICA não oferece suporte para a cláusula WITH TAG.

  Esta cláusula não é suportada porque o banco de dados secundário é somente leitura. Se seu banco de dados primário especificar a cláusula WITH TAG, remova a cláusula antes de criar o banco de dados secundário. Para verificar se seu banco de dados tem a cláusula WITH TAG, chame a função GET_DDL em sua conta Snowflake e especifique o banco de dados primário no argumento da função. Se uma tag for definida no banco de dados, a saída da função incluirá uma instrução ALTER DATABASE … SET TAG.

  Para detalhes adicionais, consulte Replicação e tags.

Exemplos¶

Criar dois bancos de dados permanentes, um com um período de retenção de dados de 10 dias:

CREATE DATABASE mytestdb;

CREATE DATABASE mytestdb2 DATA_RETENTION_TIME_IN_DAYS = 10;

SHOW DATABASES LIKE 'my%';

+---------------------------------+------------+------------+------------+--------+----------+---------+---------+----------------+
| created_on                      | name       | is_default | is_current | origin | owner    | comment | options | retention_time |
|---------------------------------+------------+------------+------------+--------+----------+---------+---------+----------------|
| Tue, 17 Mar 2016 16:57:04 -0700 | MYTESTDB   | N          | N          |        | PUBLIC   |         |         | 1              |
| Tue, 17 Mar 2016 17:06:32 -0700 | MYTESTDB2  | N          | N          |        | PUBLIC   |         |         | 10             |
+---------------------------------+------------+------------+------------+--------+----------+---------+---------+----------------+

Copy

Criar um banco de dados transitório:

CREATE TRANSIENT DATABASE mytransientdb;

SHOW DATABASES LIKE 'my%';

+---------------------------------+---------------+------------+------------+--------+----------+---------+-----------+----------------+
| created_on                      | name          | is_default | is_current | origin | owner    | comment | options   | retention_time |
|---------------------------------+---------------+------------+------------+--------+----------+---------+-----------+----------------|
| Tue, 17 Mar 2016 16:57:04 -0700 | MYTESTDB      | N          | N          |        | PUBLIC   |         |           | 1              |
| Tue, 17 Mar 2016 17:06:32 -0700 | MYTESTDB2     | N          | N          |        | PUBLIC   |         |           | 10             |
| Tue, 17 Mar 2015 17:07:51 -0700 | MYTRANSIENTDB | N          | N          |        | PUBLIC   |         | TRANSIENT | 1              |
+---------------------------------+---------------+------------+------------+--------+----------+---------+-----------+----------------+

Copy

Criar um banco de dados a partir de um compartilhamento fornecido pela conta ab67890:

CREATE DATABASE snow_sales FROM SHARE ab67890.sales_s;

Copy

Para exemplos mais detalhados da criação de um banco de dados a partir de um compartilhamento, consulte Consumo de dados compartilhados.

Exemplos de replicação de banco de dados¶

O exemplo a seguir cria uma réplica do banco de dados primário myorg.account1.mydb1 na conta account1 da organização myorg, com a atualização automática das exibições materializadas na réplica habilitada. A instrução SQL é executada no mesmo grupo de região AWS (public), mas em uma região diferente da conta que armazena o banco de dados primário:

CREATE DATABASE mydb1
  AS REPLICA OF myorg.account1.mydb1
  DATA_RETENTION_TIME_IN_DAYS = 10;