ALTER FAILOVER GROUP¶
Modifies the properties for an existing failover group.
在源账户中,可以执行以下操作:
-
为故障转移组重命名。
-
重置为复制和故障转移启用的指定对象类型列表。
-
设置或更新复制计划,以自动刷新辅助故障转移组。
-
在故障转移组中添加或移除以下类型的账户对象:
- 数据库
- 外部卷
- 共享
- 安全集成
- API 集成
- 存储集成
- 外部访问集成
- Certain types of notification integrations (see Integration replication)
-
添加或移除启用复制和故障转移的目标账户。
-
将共享或数据库移动至另一个故障转移组。
在目标账户中,您可以执行以下操作:
- 将对象从源账户刷新到目标账户中。
- 将辅助故障转移组提升为主要故障转移组(即对故障转移对象组进行故障转移)。
- 暂停计划的复制。
- 恢复计划的复制。
语法
源账户
目标账户
参数
源账户
name指定故障转移组的标识符。
RENAME TO new_namenew_name为故障转移组指定新标识符。如果其他复制或故障转移组的标识符已经存在,则不能使用新标识符。
For more details, see Identifier requirements.
SET ...指定要为故障转移组设置的属性(由空格、逗号或换行符分隔)。
OBJECT_TYPES = object_type [ , object_type , ... ]重置您要启用从源账户复制和故障转移到目标账户的对象类型的列表。
Note
For database, external volume, and share objects:
- If DATABASES, EXTERNAL VOLUMES, or SHARES are included in the OBJECT_TYPES list, and remain in the OBJECT_TYPES list after the list is reset, the respective allowed objects list (ALLOWED_DATABASES, ALLOWED_EXTERNAL_VOLUMES, or ALLOWED_SHARES) remains unchanged.
- If the OBJECT_TYPES list is reset to add or remove DATABASES, the ALLOWED_DATABASES list is set to NULL.
- If the OBJECT_TYPES list is reset to add or remove EXTERNAL VOLUMES, the ALLOWED_EXTERNAL_VOLUMES list is set to NULL.
- If the OBJECT_TYPES list is reset to add or remove SHARES, the ALLOWED_SHARES list is set to NULL.
- Use the ADD, MOVE, and REMOVE clauses to modify the list of allowed database, external volume, or share objects.
支持以下对象类型:
- ACCOUNT PARAMETERS:
All account-level parameters. This includes account parameters and parameters that can be set for your account.
- DATABASES:
Add database objects to the list of object types. If database objects were already included in the list of specified object types, the
ALLOWED_DATABASESlist remains unchanged. To modify the list of databases, use the ADD, MOVE, or REMOVE clauses.- EXTERNAL VOLUMES:
Add external volume objects to the list of object types. If external volume objects are included in the list of specified object types, the
ALLOWED_EXTERNAL_VOLUMESparameter must be set. To modify the list of external volumes, use the ADD, MOVE, or REMOVE clauses.- INTEGRATIONS:
Currently, only security, API, storage, external access, and certain types of notification integrations are supported. For details, see Integration replication.
If integration objects are included in the list of specified object types, the
ALLOWED_INTEGRATION_TYPESparameter must be set.- LISTINGS:
将列表添加到对象类型列表。将列表添加到故障转移组时,可以选择是否添加共享。Snowflake 会自动选择所有符合条件的列表及其共享,以进行复制和故障转移。
- NETWORK POLICIES:
源账户中的所有网络策略。
- PROFILES:
All profiles in the source account. Review profile replication constraints for information about current constraints.
- RESOURCE MONITORS:
源账户中的所有资源监视器。
- ROLES:
All roles in the source account. Replicating roles implicitly includes all grants for object types included in the failover group. For example, if
ROLESis the only object type that is replicated, then only hierarchies of roles (that is, roles granted to other roles) are replicated to target accounts. If theUSERSobject type is also included, then role grants to users are also replicated.- SHARES:
Add share objects to the list of object types. If share objects were already included in the list of specified object types, the
ALLOWED_SHARESlist remains unchanged. To modify the list of shares, use the ADD, MOVE, or REMOVE clauses.- USERS:
源账户中的所有用户。
- WAREHOUSES:
源账户中的所有仓库。
Note
If you replicate users and roles, programmatic access tokens for users are replicated automatically.
ALLOWED_DATABASES = db_name [ , db_name , ... ]Specifies the database or list of databases for which you are enabling replication and failover from the source account to the target account. In order for you to set this parameter, the
OBJECT_TYPESlist must includeDATABASES.db_name指定数据库的标识符。
ALLOWED_EXTERNAL_VOLUMES = external_volume_name [ , external_volume_name , ... ]Specifies the external volume or list of external volumes for which you are enabling replication and failover from the source account to the target account. For you to set this parameter, the
OBJECT_TYPESlist must includeEXTERNAL VOLUMES.external_volume_name指定外部卷的标识符。
ALLOWED_SHARES = share_name [ , share_name , ... ]Specifies the share or list of shares for which you are enabling replication and failover from the source account to the target account. For you to set this parameter, the
OBJECT_TYPESlist must includeSHARES.share_name指定共享的标识符。
Note
如果 ALLOWED_DATABASES、ALLOWED_EXTERNAL_VOLUMES 或 ALLOWED_SHARES 列表被修改,则在下一次刷新操作发生时,列表中先前存在但现在已移除的所有对象都会从任何具有链接的辅助故障转移组的目标账户中删除。
ALLOWED_INTEGRATION_TYPES = integration_type_name [ , integration_type_name , ... ]要启用从源账户复制和故障转移到目标账户的集成类型。
This property requires that the
OBJECT_TYPESlist includeINTEGRATIONSto set this parameter.The following integration types are supported:
- SECURITY INTEGRATIONS:
Specifies security integrations.
This property requires that the
OBJECT_TYPESlist includeROLES.- API INTEGRATIONS:
Specifies API integrations.
API integration replication requires additional set up after the API integration is replicated to the target account. For more information, see Updating the remote service for API integrations.
- STORAGE INTEGRATIONS:
Specifies storage integrations.
- EXTERNAL ACCESS INTEGRATIONS:
Specifies external access integrations.
For more information, see Replication of stored procedures and user-defined functions (UDFs).
- NOTIFICATION INTEGRATIONS:
Specifies notification integrations.
Only some types of notification integrations are replicated. For details, see Integration replication.
COMMENT = 'string_literal'为故障转移组添加注释或覆盖现有注释。
- Default:
NULL
REPLICATION_SCHEDULE ...指定辅助故障转移组的刷新计划。
-
USING CRON expr time_zoneSpecifies a cron expression and time zone for the secondary group refresh. Supports a subset of standard cron utility syntax.
For a list of time zones, see the list of tz database time zones (in Wikipedia).
The cron expression consists of the following fields:
The following special characters are supported:
*Wildcard. Specifies any occurrence of the field.
LStands for “last”. When used in the day-of-week field, it allows you to specify constructs such as “the last Friday” (“5L”) of a given month. In the day-of-month field, it specifies the last day of the month.
/nIndicates the nth instance of a given unit of time. Each quanta of time is computed independently. For example, if
4/3is specified in the month field, then the refresh is scheduled for April, July and October (i.e. every 3 months, starting with the 4th month of the year). The same schedule is maintained in subsequent years. That is, the refresh is not scheduled to run in January (3 months after the October run).Note
- The cron expression currently evaluates against the specified time zone only. Altering the TIMEZONE parameter value for the account (or setting the value at the user or session level) does not change the time zone for the refresh.
- The cron expression defines all valid run times for the refresh. Snowflake attempts to refresh secondary groups based on this schedule; however, any valid run time is skipped if a previous run has not completed before the next valid run time starts.
- When both a specific day of month and day of week are included in the cron expression, then the refresh is scheduled on days
satisfying either the day of month or day of week. For example,
SCHEDULE = 'USING CRON 0 0 10-20 * TUE,THU UTC'schedules a refresh at 0AM on any 10th to 20th day of the month and also on any Tuesday or Thursday outside of those dates.
-
num MINUTESpecifies an interval (in minutes) of wait time between refreshes. Accepts positive integers only.
Also supports
num Msyntax.To avoid ambiguity, a base interval time is set:
- When the object is created (using CREATE <object>) or
- When a different interval is set (using ALTER <object> … SET REPLICATION_SCHEDULE)
The base interval time starts the interval counter from the current clock time. For example, if an INTERVAL value of
10is set and the scheduled refresh is enabled at 9:03 AM, then the refresh runs at 9:13 AM, 9:23 AM, and so on. Note that we make a best effort to ensure absolute precision, but only guarantee that refreshes do not execute before their set interval occurs (e.g. in the current example, the refresh could first run at 9:14 AM, but will definitely not run at 9:12 AM).Note
The maximum supported value is
11520(8 days). If the replication schedule has a greaternum MINUTEvalue, the refresh operation never runs.
- Default:
NULL
-
ERROR_INTEGRATION = integration_nameSpecifies the name of the notification integration to use to email/push notifications when refresh errors occur for the failover group. For more details, see Error notifications for replication and failover groups.
TAG tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ]Specifies the tag name and the tag string value.
The tag value is always a string, and the maximum number of characters for the tag value is 256.
For information about specifying tags in a statement, see Tag quotas.
ADD db_name [ , db_name , ... ] TO ALLOWED_DATABASES使用逗号分隔列表形式指定要启用复制和故障转移的附加数据库。要添加数据库,必须在指定对象类型的列表中包含 DATABASES。如果对象类型列表中尚未包括 DATABASES,则必须添加。
db_name指定数据库的标识符。
MOVE DATABASES db_name [ , db_name , ... ] TO FAILOVER GROUP move_to_fg_name使用逗号分隔列表形式,指定要从一个故障转移组移动到另一个故障转移组的数据库。对于数据库要移动到的故障转移组,指定对象类型列表中必须包含 DATABASES。
db_name指定数据库的标识符。
move_to_fg_name指定要将数据库移动到的故障转移组的标识符。
REMOVE db_name [ , db_name , ... ] FROM ALLOWED_DATABASES使用逗号分隔列表形式,指定要从启用复制和故障转移的数据库列表中移除的数据库。
Note
当从主要故障转移组中移除数据库时,在下一次刷新操作发生时,在任何具有链接的辅助故障转移组的目标账户中,该数据库将被删除。
为了避免在目标账户中删除数据库,您可以在下次将修改后的主要故障转移组复制到目标账户 * 之前 * 删除辅助故障转移组。删除辅助故障转移组时,该组中包含的只读辅助数据库将成为目标账户中的独立读写数据库。
ADD external_volume_name [ , external_volume_name , ... ] TO ALLOWED_EXTERNAL_VOLUMES使用逗号分隔列表形式,指定要启用复制和故障转移的附加外部卷。要添加外部卷,EXTERNAL VOLUMES 必须包含在指定对象类型的列表中。如果对象类型列表中尚未包括 EXTERNAL VOLUMES,则必须添加。
external_volume_name指定外部卷的标识符。
MOVE EXTERNAL VOLUMES external_volume_name [ , external_volume_name , ... ] TO FAILOVER GROUP move_to_fg_name使用逗号分隔列表形式,指定要从一个故障转移组移动到另一个故障转移组的外部卷。外部卷要移动到的故障转移组必须包括指定对象类型列表中的 EXTERNAL VOLUMES。
db_name指定外部卷的标识符。
move_to_fg_name指定外部卷要移动到的故障转移组的标识符。
REMOVE external_volume_name [ , external_volume_name , ... ] FROM ALLOWED_EXTERNAL_VOLUMES指定一个逗号分隔的外部卷列表,这些卷将从已启用复制和故障转移的外部卷列表中移除。
Note
当从主故障转移组中移除外部卷时,下次刷新操作执行时,该外部卷将在所有与之关联的辅助故障转移组的目标账户中被删除。
为了避免在目标账户中删除外部卷,您可以在下次将修改后的主要故障转移组复制到目标账户 * 之前 * 删除辅助故障转移组。删除辅助故障转移组后,原本包含在该组中的只读辅助外部卷将在目标账户中变为独立的可读写外部卷。
ADD share_name [ , share_name , ... ] TO ALLOWED_SHARES使用逗号分隔列表形式,指定要启用复制和故障转移的附加共享。要添加共享,必须在指定对象类型的列表中包含 SHARES。如果对象类型列表中尚未包括 SHARES,则必须添加。
share_name指定共享的标识符。
MOVE SHARES share_name [ , share_name , ... ] TO FAILOVER GROUP move_to_fg_name使用逗号分隔列表形式,指定要从一个故障转移组移动到另一个故障转移组的共享。对于共享要移动到的故障转移组,指定对象类型列表中必须包含 SHARES。
share_name指定共享的标识符。
move_to_fg_name指定要将共享移动到的故障转移组的标识符。
REMOVE share_name [ , share_name , ... ] FROM ALLOWED_SHARES使用逗号分隔列表形式,指定要从启用复制和故障转移的共享列表中移除的共享。
Note
当从主要故障转移组中移除共享时,在下一次刷新操作发生时,在任何辅助故障转移组的目标账户中,该共享将被删除。
ADD org_name.target_account_name [ , org_name.target_account_name , ... ] TO ALLOWED_ACCOUNTS使用逗号分隔列表形式,指定要添加到主要故障转移组的目标账户,以启用将源账户中的指定对象复制和故障转移到目标账户的功能。此列表中的目标账户中的辅助故障转移组可以在发生故障转移时提升为主要故障转移组。
org_nameSnowflake 组织的名称。
target_account_name要对其启用指定对象复制的目标账户。
REMOVE org_name.target_account_name [ , org_name.target_account_name , ... ] FROM ALLOWED_ACCOUNTS使用逗号分隔列表形式,指定要从主要故障转移组中移除的目标账户列表,以禁用将源账户中的指定对象复制到目标账户。移除目标账户将禁用从当前账户到该目标账户的故障转移。
org_nameSnowflake 组织的名称。
target_account_name要对其禁用指定对象复制的目标账户。
IGNORE EDITION CHECK
Allows replicating objects to accounts in the following scenario:
The primary failover group is in a Business Critical (or higher) account and a signed business associate agreement is in place to store PHI data in the account per HIPAA and HITRUST regulations. However, no such agreement is in place for one or more of the accounts approved for replication, regardless if they are Business Critical (or higher) accounts.
This scenario is prohibited by default.
目标账户
name指定故障转移组的标识符。
REFRESH将对象从源账户刷新到目标(当前)账户中。
PRIMARY将目标(当前)账户中的辅助故障转移组及其指定对象提升到主故障转移组(在发生故障转移的情况下)。
SUSPEND [ IMMEDIATE ]Suspend the scheduled refresh of the secondary failover group (if the primary failover group has scheduled refreshes using the
REPLICATION_SCHEDULEproperty).The optional
IMMEDIATEkeyword cancels a scheduled refresh operation that is currently in progress for the secondary failover group (if there is one). Note that there might be a slight delay between the time that the statement returns and the time that the cancellation of the refresh operation is finished.RESUMEResume scheduled refresh of the secondary failover group (if the primary failover group has scheduled refreshes using the
REPLICATION_SCHEDULEproperty).UNSET ...为故障转移组指定一个(或多个)要取消设置的属性,从而将其重置为默认值:
COMMENTREPLICATION_SCHEDULEERROR_INTEGRATION-
TAG tag_name [ , tag_name ... ]
You can reset multiple properties with a single ALTER statement; however, each property must be separated by a comma. Also, when resetting a property, you only specify the name; no value is required.
使用说明
-
需要以下最低权限:
- To refresh a secondary failover group using ALTER FAILOVER GROUP … REFRESH, the active, primary role must have either the OWNERSHIP or REPLICATE privilege on the failover group.
- To fail over a secondary failover group using ALTER FAILOVER GROUP … PRIMARY, a role must have either the OWNERSHIP or FAILOVER privilege on the failover group.
- 要对故障转移组进行任何其他更改,只有具有该组的 OWNERSHIP 权限才能执行此 SQL 命令。
- 要将数据库添加到故障转移组,活动角色必须具有 MONITOR 数据库的权限。
- 要将外部卷添加到复制组,活动角色必须拥有对外部卷的 USAGE 权限。
- 要将共享添加到故障转移组,活动角色必须对共享具有 OWNERSHIP 权限。
-
账户中的故障转移组和复制组的标识符必须是唯一的。
-
数据库、外部卷和共享以外的对象必须位于同一个故障转移组中。
-
一个数据库只能添加到一个故障转移组。
-
一个外部卷只能添加到一个故障转移组。
-
Inbound shares (shares from providers) cannot be added to a replication or failover group.
-
如果正在执行刷新,将辅助故障转移组提升为主要故障转移组(在发生故障转移的情况下)会失败。
-
If a refresh is in progress when the replication schedule is updated, the refresh continues until completion and the next refresh will use the new schedule.
-
On failover, scheduled refreshes on all secondary failover groups are suspended.
ALTER FAILOVER GROUP ... RESUMEmust be executed on each secondary to resume automatic refreshes. -
要将数据库、外部卷或共享从一个故障转移组(移出组)移动到另一个故障转移组(移至组),需要满足以下条件:
- 两个组的类型必须相同:FAILOVER GROUP。
- If the last database in the move-from group is moved to another group, the
allowed_databasesproperty for the move-from group is set to NULL. The same behavior applies to shares and external volumes. - If the move-to group doesn’t have the object type that is being moved (
databases,external volumes, orshares) in theobject_typeslist, it must be explicitly added to the move-to group before you move the objects.
-
If database, external volume, or share objects are removed from a primary failover group (by using the REMOVE parameter or SET parameter to modify the ALLOWED_DATABASES, ALLOWED_EXTERNAL_VOLUMES, or ALLOWED_SHARES lists), those objects are dropped in any target account when the next refresh operation occurs.
为了避免在目标账户中删除这些对象,您可以在下次将修改后的主要故障转移组复制到目标账户 * 之前 * 删除辅助故障转移组。
- To retrieve the list of accounts in your organization that are enabled for replication, use the SHOW REPLICATION ACCOUNTS command.
- To retrieve the list of failover groups in your organization, use SHOW FAILOVER GROUPS.
-
Automatically scheduled refresh operations are executed using the role with the OWNERSHIP privilege on the group. If a scheduled refresh operation fails due to insufficient privileges, grant the required privileges to the role with the OWNERSHIP privilege on the group.
- The ALTER FAILOVER GROUP … SUSPEND IMMEDIATE command doesn’t cancel an in-progress refresh operation if it was manually triggered. For information, see Cancel an in-progress refresh operation that wasn’t automatically scheduled.
- Canceling an in-progress refresh operation that is in the SECONDARY_DOWNLOADING_METADATA or SECONDARY_DOWNLOADING_DATA phase might result in an inconsistent state on the target account. For more information see View the current phase of an in-progress refresh operation.
-
If you create a replication or failover group with a tag or modify a replication or failover group by setting a tag on it, tag inheritance does not apply to any objects that you specify in the replication or failover group.
Tag inheritance is only applicable to objects with a parent-child relationship, such database, schema, and table. There are no child objects of replication or failover groups.
-
You cannot set a tag or modify a tag on a secondary replication or failover group because these objects are read only.
-
When you refresh a secondary replication or failover group, any tags that are set on the primary group are then set on the secondary group.
-
关于元数据:
Attention
Customers should ensure that no personal data (other than for a User object), sensitive data, export-controlled data, or other regulated data is entered as metadata when using the Snowflake service. For more information, see Metadata fields in Snowflake.
示例
从源账户执行
Add myorg.myaccount3 to the list of target accounts to which replication of specified objects and failover from the source
account is enabled.
Reset the object types list for replication in the source account and add database db1:
Add databases db2 and db3 to the list of databases:
Move database db3 to another failover group, myfg2:
Move database db2 in myfg to another failover group, myfg3, that currently has no databases:
First add
databasestoobject_types:Move
db2tomyfg3:
从源账户的数据库列表中移除要进行复制和故障转移的所有数据库:
Note
执行上述语句会从要复制的数据库列表中移除所有数据库,但不会从用于复制和故障转移的指定对象类型列表中移除数据库对象。
要禁用所有数据库的复制和故障转移,并从指定对象类型的列表中移除数据库,请执行以下操作:
增加(或修改)自动计划刷新的间隔:
从目标账户执行
Refresh objects in the failover group myfg in the target account:
将当前目标账户中的辅助故障转移组提升为主故障转移组:
暂停自动刷新: