CREATE DATABASE

Cria um novo banco de dados no sistema.

Além disso, este comando pode ser usado para:

Consulte também:

ALTER DATABASE , DESCRIBE DATABASE , DROP DATABASE , SHOW DATABASES , UNDROP DATABASE

DESCRIBE SHARE , SHOW SHARES

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>' , ... ] ) ]
Copy

Banco de dados compartilhado (de um compartilhamento)

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

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> ]
Copy

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 de Secure Data Sharing

provider_account.share_name

Especifica o identificador do compartilhamento a partir do qual se pode criar o banco de dados. Conforme documentado, o nome do compartilhamento deve ser totalmente qualificado com o nome da conta que fornece o compartilhamento.

Parâmetros de replicação de banco de dados

AS REPLICA OF account_identifier.primary_db_name

Especifica o identificador de um banco de dados primário a partir do qual se pode criar uma réplica (ou seja, um banco de dados secundário). Se o identificador contiver espaços, caracteres especiais ou caracteres com letras maiúsculas e minúsculas, toda a cadeia de caracteres deve ser delimitada por aspas duplas.

Exige o identificador da conta e o nome do banco de dados primário.

account_identifier

Identificador exclusivo da conta que armazena o banco de dados primário. O identificador preferido é organization_name.account_name. Para visualizar a lista de contas habilitadas para replicação em sua organização, consulte SHOW REPLICATION ACCOUNTS.

Embora o localizador de conta de legado também possa ser usado como identificador de conta, seu uso é desencorajado, pois ele pode não funcionar no futuro. Para obter mais detalhes sobre o uso do localizador de conta como um identificador de conta, veja Notas de uso da replicação de banco de dados.

primary_db_name

Nome do banco de dados primário. Como prática recomendada, recomendamos dar a cada banco de dados secundário o mesmo nome de seu banco de dados primário.

Nota

Como prática recomendada para replicação e failover de banco de dados, recomendamos definir o parâmetro opcional DATA_RETENTION_TIME_IN_DAYS para o mesmo valor no banco de dados secundário e no banco de dados primá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:

Privilégio

Objeto

Notas

CREATE DATABASE

Conta

Only the SYSADMIN role, or a higher role, has this privilege by default. The privilege can be granted to additional roles as needed.

USAGE

Volume externo, integração de catálogo

Obrigatório ao definir os parâmetros do objeto EXTERNAL_VOLUME ou CATALOG, respectivamente.

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

Nota

A Snowflake recomenda o uso do recurso de replicação de conta para replicar bancos de dados. Os grupos de replicação e failover permitem a replicação de vários bancos de dados e outros objetos de conta com consistência pontual para os objetos no grupo. Para obter uma lista completa da disponibilidade do recurso e objetos suportados, consulte Introdução à replicação e failover em várias contas.

  • 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;
Copy