ALTER DATABASE¶

修改现有数据库的属性。

数据库修改包括以下内容：

更改数据库的名称或更改 Time Travel 数据保留期（如果您使用的是 Snowflake Enterprise Edition 或更高版本）。
启用并管理数据库复制和故障转移。

小技巧

您还可以使用 Snowflake REST APIs 来执行此操作。有关信息，请参阅以下端点：

另请参阅：: CREATE DATABASE、DESCRIBE DATABASE、DROP DATABASE、SHOW DATABASES、UNDROP DATABASE

语法¶

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> ]
                                        [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
                                        [ DEFAULT_DDL_COLLATION = '<collation_specification>' ]
                                        [ LOG_LEVEL = '<log_level>' ]
                                        [ TRACE_LEVEL = '<trace_level>' ]
                                        [ STORAGE_SERIALIZATION_POLICY = { COMPATIBLE | OPTIMIZED } ]
                                        [ 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               |
                                            STORAGE_SERIALIZATION_POLICY        |
                                            COMMENT
                                          }
                                          [ , ... ]

Copy

数据库复制和故障转移语法¶

注意

Snowflake 建议使用账户复制功能对数据库进行复制和故障转移。

数据库复制

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

数据库故障转移

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

参数¶

name

指定要更改的数据库的标识符。如果标识符包含空格、特殊字符或大小写混合字符，则整个字符串必须放在双引号内。放在双引号内的标识符也区分大小写。

RENAME TO new_db_name

指定数据库的新标识符，它对于您的账户必须是唯一的。

有关更多信息，请参阅标识符要求。

重命名对象时，引用该对象的其他对象必须使用新名称进行更新。

SWAP WITH target_db_name

在两个指定的数据库之间交换所有对象（架构、表、视图等）和元数据（包括标识符）。还可交换对数据库及其所含对象授予的所有访问控制权限。SWAP WITH 实质上是将两个数据库的重命名作为单个操作执行。

SET ...

指定要为数据库设置的一个（或多个）属性（用空格、逗号或新行分隔）：

DATA_RETENTION_TIME_IN_DAYS = num

指定可以对数据库执行 Time Travel 操作（CLONE 和 UNDROP）的天数，并指定在数据库中创建的所有架构的默认 Time Travel 保留时间。

您可以指定的值取决于您使用的 Snowflake Edition：

Standard Edition：0 或 1
Enterprise Edition（或更高版本）：0 至 90

MAX_DATA_EXTENSION_TIME_IN_DAYS = integer

对象参数，用于指定 Snowflake 可以延长数据库中表的数据保留期以防止表上的流过时的最大天数。

有关此参数的详细说明，请参阅 MAX_DATA_EXTENSION_TIME_IN_DAYS。

EXTERNAL_VOLUME = external_volume_name

对象参数，指定要用于 Apache Iceberg™ 表的默认外部卷。

有关此参数的详细信息，请参阅 EXTERNAL_VOLUME。

CATALOG = catalog_integration_name

对象参数，指定要用于 Apache Iceberg™ 表的默认目录集成。

有关此参数的详细信息，请参阅 CATALOG。

REPLACE_INVALID_CHARACTERS = { TRUE | FALSE }

指定在 Iceberg 表的查询结果中是否使用 Unicode 替换字符 (�) 替换无效的 UTF-8 字符。您只能为使用外部 Tables 目录的表设置此参数。

TRUE 会将无效的 UTF-8 字符替换为 Unicode 替换字符。
FALSE 保留无效的 UTF-8 字符不变。如果在 Parquet 数据文件中遇到无效的 UTF-8 字符，Snowflake 会返回用户错误消息。

默认：FALSE

DEFAULT_DDL_COLLATION = 'collation_specification'

指定以下项的默认排序规则规范：

添加到数据库中现有表的任何新列。
添加到数据库的新表中的所有列。

设置该参数不会更改任何现有列的排序规则规范。

有关该参数的更多信息，请参阅 DEFAULT_DDL_COLLATION。

LOG_LEVEL = 'log_level'

指定应引入并在活动事件表中可用的消息的严重级别。引入指定级别（以及更严重级别）的消息。

有关级别的更多信息，请参阅 LOG_LEVEL。有关设置日志级别的信息，请参阅为日志、指标和跟踪设置级别。

TRACE_LEVEL = 'trace_level'

控制如何将跟踪事件引入到事件表中。

有关级别的更多信息，请参阅 TRACE_LEVEL。有关设置跟踪级别的信息，请参阅为日志、指标和跟踪设置级别。

STORAGE_SERIALIZATION_POLICY = { COMPATIBLE | OPTIMIZED }

为使用 Snowflake 作为目录的 Apache Iceberg™ 表指定存储序列化策略。

COMPATIBLE：Snowflake 对数据文件执行编码和压缩，可确保与第三方计算引擎的互操作性。
OPTIMIZED：Snowflake 对数据文件执行编码和压缩，可确保 Snowflake 中的最佳表性能。

默认：OPTIMIZED

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

指定标签名称和标签字符串值。

标签值始终为字符串，标签值的最大字符数为 256。

有关在语句中指定标签的信息，请参阅对象和列的标签配额。

COMMENT = 'string_literal': 为数据库添加注释或覆盖现有注释。

UNSET ...

指定要为数据库取消设置的一个（或多个）属性和/或参数，这会将它们重置为默认值：

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

您可以使用单个 ALTER 语句重置多个属性/参数；但是，每个属性/参数必须用逗号分隔。重置属性/参数时，请仅指定名称；指定属性的值将返回错误。

数据库复制和故障转移参数¶

注意

Snowflake 建议使用账户复制功能对数据库进行复制和故障转移。

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

将本地数据库提升为用于复制的主数据库。主数据库可以在一个或多个账户中复制，使这些账户中的用户可以查询各个 *辅助*（即副本）数据库中的对象。

或者，修改现有主数据库，以添加到可存储数据库副本的账户列表或从该列表中移除。

提供组织中可存储此数据库副本的账户列表（用逗号分隔）。

account_identifier

账户的唯一标识符。首选标识符为 organization_name.account_name。若要查看组织中已启用复制的账户列表，请查询 SHOW REPLICATION ACCOUNTS。

虽然旧版账户定位器也可以用作账户标识符，但不建议使用，因为旧版账户定位器未来可能无法运行。有关使用账户定位器作为账户标识符的更多信息，请参阅数据库复制和故障转移使用说明。

IGNORE EDITION CHECK

允许在以下任一场景中将数据复制到较低版本的账户：

主数据库位于 Business Critical（或更高版本）账户中，但批准复制的一个或多个账户位于较低版本中。Business Critical Edition 适用于具有极其敏感数据的 Snowflake 账户。
主数据库位于 Business Critical（或更高版本）账户中，并且已签署业务伙伴协议，可根据 HIPAA 和 HITRUST 法规在账户中存储 PHI 数据，但一个或多个获准复制的账户未签署此类协议，无论它们是否为 Business Critical（或更高版本）账户。

默认情况下，这两种场景都是禁止的，以防止 Business Critical（或更高版本）账户的账户管理员无意中将敏感数据复制到较低版本的账户。

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

禁用对此主数据库的复制，这意味着无法刷新其他账户中此数据库的副本（即辅助数据库）。任何辅助数据库仍链接到主数据库，但刷新辅助数据库的请求将被拒绝。

请注意，禁用对主数据库的复制并不会阻止将其复制到同一账户；因此，SHOW REPLICATION DATABASES 输出中仍将列出该数据库。

（可选）提供组织中以逗号分隔的账户列表，从而仅在指定账户中禁用对此数据库的复制。

account_identifier

账户的唯一标识符。首选标识符为 organization_name.account_name。若要查看组织中已启用复制的账户列表，请查询 SHOW REPLICATION ACCOUNTS。

REFRESH

根据主数据库的快照刷新辅助数据库。快照包括对对象和数据的更改。

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

指定组织中以逗号分隔的账户列表，在此列表中，可以将此主数据库的副本提升为主数据库。

account_identifier

账户的唯一标识符。首选标识符为 organization_name.account_name。若要查看组织中已启用复制的账户列表，请查询 SHOW REPLICATION ACCOUNTS。

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

禁用对此主数据库的故障转移，这意味着不能将此数据库的副本（即辅助数据库）提升为主数据库。

（可选）提供组织中以逗号分隔的账户列表，从而仅在指定账户中禁用对此数据库的故障转移。

account_identifier

账户的唯一标识符。首选标识符为 organization_name.account_name。若要查看组织中已启用复制的账户列表，请查询 SHOW REPLICATION ACCOUNTS。

PRIMARY

将指定的辅助（副本）数据库提升为主数据库。升级后，数据库变为可写入。同时，先前的主数据库变成了只读辅助数据库。

使用说明¶

若要重命名数据库，用于执行操作的角色必须对数据库具有 CREATE DATABASE 全局权限和 OWNERSHIP 权限。
若要交换两个数据库，用于执行操作的角色必须对这两个数据库都具有 OWNERSHIP 权限。
若要更新注释，用于执行操作的角色必须被授予或继承对数据库的 MODIFY 权限。
关于元数据：

注意

客户应确保在使用 Snowflake 服务时，不会将个人数据（用户对象除外）、敏感数据、出口管制数据或其他受监管数据作为元数据输入。有关更多信息，请参阅 Snowflake 中的元数据字段。

数据库复制和故障转移使用说明¶

注意

Snowflake 建议使用账户复制功能对数据库进行复制和故障转移。

只有账户管理员（具有 ACCOUNTADMIN 角色的用户）才能启用并管理数据库复制和故障转移。
当主数据库初始复制到辅助数据库时，将应用默认的 10 TB 大小限制。要更改或移除这一大小限制，请在账户级别设置 INITIAL_REPLICATION_SIZE_LIMIT_IN_TB 参数。

请注意，当前没有默认大小限制应用于辅助数据库的后续刷新。
识别账户的首选方法是使用组织名称和账户名称作为账户标识符。如果您决定改用旧版账户定位器，请参阅用于复制和故障转移的账户标识符。

一般示例¶

将数据库 db1 重命名为 db2：

ALTER DATABASE IF EXISTS db1 RENAME TO db2;

Copy

Database Replication 示例¶

注意

Snowflake 建议使用账户复制功能对数据库进行复制和故障转移。

使用复制组或故障转移组对单个数据库进行复制和故障转移。有关示例，请参阅以下内容之一：