ALTER DATABASE¶

Modifica as propriedades de um banco de dados existente.

As modificações do banco de dados incluem o seguinte:

Alterar o nome do banco de dados ou alterar o período de retenção de dados do Time Travel (se você estiver usando Snowflake Enterprise Edition ou superior).
Habilitar e gerenciar a replicação e failover de banco de dados.

Consulte também:: CREATE DATABASE , DESCRIBE DATABASE , DROP DATABASE , SHOW DATABASES , UNDROP DATABASE

Sintaxe¶

ALTER DATABASE [ IF EXISTS ] <name> RENAME TO <new_db_name>

ALTER DATABASE [ IF EXISTS ] <name> SWAP WITH <target_db_name>

ALTER DATABASE [ IF EXISTS ] <name> SET [ 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>' ]
                                        [ LOG_LEVEL = '<log_level>' ]
                                        [ TRACE_LEVEL = '<trace_level>' ]
                                        [ COMMENT = '<string_literal>' ]

ALTER DATABASE <name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]

ALTER DATABASE <name> UNSET TAG <tag_name> [ , <tag_name> ... ]

ALTER DATABASE [ IF EXISTS ] <name> UNSET { DATA_RETENTION_TIME_IN_DAYS         |
                                            MAX_DATA_EXTENSION_TIME_IN_DAYS     |
                                            EXTERNAL_VOLUME                     |
                                            CATALOG                             |
                                            DEFAULT_DDL_COLLATION               |
                                            COMMENT
                                          }
                                          [ , ... ]

Copy

Sintaxe de replicação e failover de banco de dados¶

Replicação de banco de dados

ALTER DATABASE <name> ENABLE REPLICATION TO ACCOUNTS <account_identifier> [ , <account_identifier> ... ] [ IGNORE EDITION CHECK ]

ALTER DATABASE <name> DISABLE REPLICATION [ TO ACCOUNTS <account_identifier> [ , <account_identifier> ... ] ]

ALTER DATABASE <name> REFRESH

Copy

Failover do banco de dados

ALTER DATABASE <name> ENABLE FAILOVER TO ACCOUNTS <account_identifier> [ , <account_identifier> ... ]

ALTER DATABASE <name> DISABLE FAILOVER [ TO ACCOUNTS <account_identifier> [ , <account_identifier> ... ] ]

ALTER DATABASE <name> PRIMARY

Copy

Parâmetros¶

name

Especifica o identificador para o banco de dados a ser alterado. 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. Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

RENAME TO new_db_name

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

Para obter mais detalhes, consulte Requisitos para identificadores.

Quando um objeto é renomeado, outros objetos que fazem referência a ele devem ser atualizados com o novo nome.

SWAP WITH target_db_name

Troca todos os objetos (esquemas, tabelas, visualizações etc.) e metadados, incluindo identificadores, entre os dois bancos de dados especificados. Também troca todos os privilégios de controle de acesso concedidos nos bancos de dados e objetos que eles contêm. SWAP WITH realiza essencialmente uma renomeação de ambos os bancos de dados como uma única operação.

SET ...

Especifica uma (ou mais) propriedades a serem definidas para o banco de dados (separadas por espaços em branco, vírgulas ou novas linhas):

DATA_RETENTION_TIME_IN_DAYS = num

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.

O valor que você pode especificar depende da edição do Snowflake que você está usando:

Standard Edition: 0 ou 1
Enterprise Edition (ou superior): 0 a 90

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'

Especifica uma especificação de agrupamento padrão para:

Qualquer nova coluna adicionada às tabelas existentes no banco de dados.
Todas as colunas em novas tabelas adicionadas ao banco de dados.

A definição do parâmetro não altera a especificação de agrupamento para qualquer coluna existente.

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

LOG_LEVEL = 'log_level'

Especifica o nível de gravidade das mensagens que devem ser ingeridas e disponibilizadas na tabela de eventos ativos. As mensagens no nível especificado (e em níveis mais graves) são ingeridas.

Para obter mais informações sobre os níveis, consulte LOG_LEVEL. Para obter informações sobre como configurar o nível de registro, consulte Configuração do nível de registro.

TRACE_LEVEL = 'trace_level'

Controla como os eventos de rastreamento são ingeridos na tabela de eventos.

Para obter informações sobre níveis, consulte TRACE_LEVEL. Para obter informações sobre como configurar o nível de rastreamento, consulte Configuração do nível de rastreamento.

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.

COMMENT = 'string_literal': Adiciona um comentário ou substitui um comentário existente para o banco de dados.

UNSET ...

Especifica uma (ou mais) propriedades e/ou parâmetros a serem removidos da definição para o banco de dados, que os redefine aos padrões:

DATA_RETENTION_TIME_IN_DAYS
MAX_DATA_EXTENSION_TIME_IN_DAYS
EXTERNAL_VOLUME
CATALOG
DEFAULT_DDL_COLLATION
TAG tag_name [ , tag_name ... ]
COMMENT

Você pode redefinir várias propriedades/parâmetros com uma única instrução ALTER; no entanto, cada propriedade/parâmetro deve ser separado por uma vírgula. Ao redefinir uma propriedade/parâmetro, especificar somente o nome; especificar um valor para a propriedade retornará um erro.

Parâmetros de failover e replicação de banco de dados¶

ENABLE REPLICATION TO ACCOUNTS account_identifier [ , account_identifier ... ]

Promove um banco de dados local para servir como banco de dados primário para replicação. Um banco de dados primário pode ser replicado em uma ou mais contas, permitindo aos usuários dessas contas consultar objetos em cada banco de dados secundário (ou seja, réplica).

Opcionalmente, é possível modificar um banco de dados primário existente para adicionar ou remover da lista de contas que podem armazenar uma réplica de banco de dados.

Forneça uma lista de contas separadas por vírgula em sua organização que possa armazenar uma réplica deste banco de dados.

account_identifier

Identificador exclusivo da conta. 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 e failover de banco de dados.

IGNORE EDITION CHECK

Permite replicar os dados para as contas em edições inferiores em um dos seguintes cenários:

O banco de dados primário está em uma conta Business Critical (ou superior), mas uma ou mais contas aprovadas para replicação estão em edições anteriores. O Business Critical Edition é destinado a contas Snowflake com dados extremamente confidenciais.
O banco de dados primário está em uma conta Business Critical (ou superior) e um contrato de parceiro comercial assinado está em vigor para armazenar dados PHI na conta segundo as regulamentações HIPAA e HITRUST, mas nenhum contrato desse tipo está em vigor para uma ou mais contas aprovadas para replicação, independentemente de serem contas Business Critical (ou superiores).

Ambos os cenários são proibidos por padrão em um esforço para ajudar a evitar que os administradores de contas Business Critical (ou superiores) repliquem inadvertidamente dados confidenciais para contas em edições anteriores.

DISABLE REPLICATION [ TO ACCOUNTS account_identifier [ , account_identifier ... ] ]

Desativa a replicação para este banco de dados primário, o que significa que nenhuma réplica deste banco de dados (ou seja, banco de dados secundário) pode ser atualizada em outra conta. Qualquer banco de dados secundário permanece vinculado ao banco de dados primário, mas os pedidos de atualização de um banco de dados secundário são negados.

Note que a desativação da replicação para um banco de dados primário não impede que ele seja replicado para a mesma conta; portanto, o banco de dados continua a ser listado na saída SHOW REPLICATION DATABASES.

Como opção, forneça uma lista de contas separadas por vírgula em sua organização para desativar a replicação para este banco de dados somente nas contas especificadas.

account_identifier

REFRESH

Atualiza um banco de dados secundário a partir de um instantâneo de seu banco de dados primário. Um instantâneo inclui alterações nos objetos e dados.

ENABLE FAILOVER TO ACCOUNTS account_identifier [ , account_identifier ... ]

Especifica uma lista de contas separadas por vírgula em sua organização onde uma réplica deste banco de dados primário pode ser promovida para servir como banco de dados primário.

account_identifier

DISABLE FAILOVER [ TO ACCOUNTS account_identifier [ , account_identifier ... ] ]

Desativa o failover para este banco de dados primário, o que significa que nenhuma réplica deste banco de dados (ou seja, banco de dados secundário) pode ser promovida para servir como banco de dados primário.

Opcionalmente, forneça uma lista separada por vírgula das contas em sua organização para desativar o failover para este banco de dados somente nas contas especificadas.

account_identifier

PRIMARY

Promove o banco de dados secundário (réplica) especificado para servir como banco de dados primário. Quando promovido, o banco de dados se torna gravável. Ao mesmo tempo, o banco de dados primário anterior se torna um banco de dados secundário somente leitura.

Notas de uso¶

Para renomear um banco de dados, a função utilizada para realizar a operação deve ter o privilégio CREATE DATABASE global e o privilégio OWNERSHIP no banco de dados.
Para trocar dois bancos de dados, a função utilizada para realizar a operação deve ter privilégios OWNERSHIP em ambos os bancos de dados.
Para atualizar um comentário, a função usada para executar a operação deve ser concedida ou herdar o privilégio MODIFY no banco de dados.
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 de replicação de banco de dados e failover¶

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.

Somente administradores de conta (usuários com a função ACCOUNTADMIN) podem habilitar e gerenciar a replicação e o failover do banco de dados.
Um limite de tamanho padrão de 10 TB é aplicado quando um banco de dados primário é inicialmente replicado para um banco de dados secundário. Para alterar ou remover o limite de tamanho, defina o parâmetro INITIAL_REPLICATION_SIZE_LIMIT_IN_TB no nível da conta.

Observe que atualmente não há um limite de tamanho padrão aplicado a atualizações posteriores de um banco de dados secundário.

O método preferido para identificar uma conta 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.

Exemplos gerais¶

Renomear banco de dados db1 para db2:

ALTER DATABASE IF EXISTS db1 RENAME TO db2;

Copy

Exemplos de replicação de banco de dados¶

Promova o banco de dados local mydb1 (na conta account1) para servir como banco de dados primário e especifique que as contas account2 e account3 na organização myorg podem armazenar uma réplica desse banco de dados:

ALTER DATABASE mydb1 ENABLE REPLICATION TO ACCOUNTS myorg.account2, myorg.account3;

Copy

Desabilitar a replicação para o banco de dados primário mydb1:

ALTER DATABASE mydb1 DISABLE REPLICATION;

Copy