What you will be able to do
- Explain what Snowflake does to each installed instance when a release directive changes
- Write setup scripts that survive upgrades and retries
- Schedule upgrades with UPGRADE_AFTER and trigger manual upgrades
- Plan rollback within the limits of version compatibility
- Configure upgrades to respect consumer-controlled maintenance policies
1.What happens when a release directive changes
An upgrade starts when a provider points a release directive at a new version or patch. (Registering versions and adding them to channels are earlier steps that reach no consumer.) The directive decides which instances are targeted. Changing a channel's default directive upgrades instances that follow the default. Accounts assigned to a custom directive stay where they are until their own directive changes. Snowflake then puts every targeted app in a queue and upgrades each one as resources become available, so a large install base can take a while to finish.
ALTER APPLICATION PACKAGE my_application_package
MODIFY RELEASE CHANNEL DEFAULT
SET DEFAULT RELEASE DIRECTIVE
VERSION = v2
PATCH = 0;The upgrade itself is a rerun of the setup script. For each targeted instance, Snowflake runs the setup script of the target version or patch. If the manifest names a version initializer, Snowflake calls it after the setup script succeeds. How each object comes through depends on how it holds state. Stateless objects such as procedures and views are created with CREATE OR REPLACE inside a versioned schema, and each version gets its own copy. Stateful objects such as tables are created with CREATE IF NOT EXISTS followed by idempotent ALTERs, which keeps their existing data.
A failed upgrade leaves the previous version in place, and failed upgrades can be retried. Because of retries, every statement has to be idempotent: ADD COLUMN IF NOT EXISTS, and guards against inserting duplicate rows. Application roles need extra care because they are not versioned. Use CREATE APPLICATION ROLE IF NOT EXISTS, never CREATE OR REPLACE, which drops the role along with the grants consumers attached to it. Services are not versioned either. A service can already be running the new specification while the app as a whole stays on the old version, which is why Snowflake recommends starting or upgrading services from the version initializer.
Consumers don't have to wait for the queue. When a new version or patch is available, a consumer can run ALTER APPLICATION <name> UPGRADE, which upgrades to whatever the release directive specifies. Once Snowflake has started upgrading that app, the manual command is no longer available.
ALTER APPLICATION <name> UPGRADECheckpoint 1 of 5· Fill the gap
You want to upgrade every installed instance in the DEFAULT channel that follows the channel's default directive to v2 patch 0. Accounts assigned to a custom directive should stay where they are. Which keyword completes the statement?
ALTER APPLICATION PACKAGE my_application_package
MODIFY RELEASE CHANNEL DEFAULT
SET ? RELEASE DIRECTIVE
VERSION = v2
PATCH = 0;Changing the default release directive upgrades only the instances that follow the default directive. Accounts on a custom directive move only when that named directive changes, so this statement already leaves them alone. No CUSTOM or ALL keyword exists. You change a custom directive by its name, and no single statement upgrades every instance in the channel.
Source: docs.snowflake.comCheckpoint 2 of 5· Check yourself
Consumers have granted account roles to your app's application role app_user. The v3 setup script runs on every upgrade, and Snowflake can retry it after a failure. How should the script create app_user?
Application roles are not versioned, and the setup script must be idempotent because upgrades can be retried. CREATE OR REPLACE, or a DROP followed by CREATE, removes the role along with the grants consumers attached to it. IF NOT EXISTS keeps the role and its grants.
“Avoid using CREATE OR REPLACE APPLICATION ROLE. Instead, use CREATE APPLICATION ROLE IF NOT EXISTS.”Source: docs.snowflake.com
2.Scheduling when automatic upgrades begin
UPGRADE_AFTER sets the earliest moment automatic upgrades can begin, not the moment they happen. Queue depth, the number of consumer accounts and similar factors can push the actual upgrade later. A timestamp that has already passed schedules the upgrade immediately, which is the same as leaving the clause out. The clause can't be set on its own: it is only accepted in a statement that also sets VERSION and PATCH. To move a scheduled time, restate the whole directive.
ALTER APPLICATION PACKAGE hello_snowflake_package MODIFY RELEASE CHANNEL DEFAULT SET DEFAULT RELEASE DIRECTIVE VERSION = 'v1_0' PATCH = '2' UPGRADE_AFTER = '2025-04-06T11:00:00Z'Apps served in other regions through Cross-Cloud Auto-Fulfillment add one more delay. A directive change takes effect in a remote region only after the application package has been replicated there. With LISTING_AUTO_REFRESH set to TRUE, the default, Snowflake starts that replication as soon as a directive changes.
Checkpoint 3 of 5· Check yourself
The DEFAULT channel's default release directive points at v1_0 patch 2 with UPGRADE_AFTER = '2025-04-06T11:00:00Z'. A consumer asks you to push the automatic upgrade back by one week. Which statement does that?
UPGRADE_AFTER is only accepted in a statement that also sets VERSION and PATCH, so to move the time you restate the whole directive with the new timestamp. Adding a version to a channel doesn't schedule anything. Only the release directive controls when upgrades start.
“This clause can’t be used to modify only the upgrade time and date.”Source: docs.snowflake.com
3.Version dependencies and rollback
Compatibility only has to hold between neighbouring versions. Before an upgrade to v3, Snowflake makes sure every instance is already on v2, so only the previous version is ever active. A setup script therefore only has to handle one step: v3 must work with v2 but never with v1. The dependency also runs the other way. Code from the previous version can still be running after an instance upgrades, so v2 code must cope with any state change v3 makes. That is the reason state changes belong in versions and never in patches.
Rollback means setting the release directive again, at an earlier version or patch that is still available as a target. The directive names any version and patch that is still in the channel, and that pair is what targeted instances receive. What you can roll back to depends on what still exists:
| Target | Still available? |
|---|---|
| An earlier patch of the same version | Yes: patches cannot be dropped |
| The previous version, still in the channel | Yes, until you drop or deregister it |
| A version dropped from the channel | No: once all consumers have upgraded off it, it is gone |
| A version two steps back | No: only two versions exist per channel, and v3 never had to be compatible with v1 |
The safest rollback strategy is to keep the previous version in the channel until the new one is proven. Dropping a version is asynchronous anyway. It completes only once every consumer has upgraded off it and all running code from it has finished, and any single failed upgrade has to be fixed first. Moving back between patches of one version is low-risk if your patches followed the no-state-change rule. For apps with containers, the version initializer can roll a service upgrade back to the previous version when the upgrade fails.
Code from the previous version has to handle state changes the new version introduces. A purely additive change, such as a new column added with IF NOT EXISTS, is the kind v1 code can tolerate. Dropping or renaming a column that v1 still reads would break it.
Checkpoint 4 of 5· Check yourself
While writing the v3 setup script, a teammate points out that some consumers installed v1 a year ago and never upgraded manually. Your channel currently holds v1 and v2. Which upgrade paths does the v3 setup script have to handle?
Snowflake keeps only the previous version active and moves all v1 instances to v2 before upgrading to v3. So v3 only has to be compatible with v2, never with v1.
“because only two versions of an app can exist at one time, version v3 does not have to be compatible with version v1.”Source: docs.snowflake.com
4.Consumer-controlled maintenance policies
A maintenance policy is an object a consumer creates in their own schema to say when upgrades may begin. It does nothing until it is applied, and it only matters for releases the provider has opened to window-based timing. The schedule is a cron expression in SCHEDULE. A policy sets a start time only, with no end time or duration, so a consumer cannot reserve a window of fixed length. Each app or account can have only one policy.
CREATE MAINTENANCE POLICY my_maintenance_policy
SCHEDULE = 'USING CRON 0 2 * * SAT UTC'
COMMENT = 'Weekly Saturday maintenance policy';ALTER APPLICATION my_app SET MAINTENANCE POLICY my_maintenance_policy;Two privileges split the work. CREATE MAINTENANCE POLICY on the schema lets a role create the object, and APPLY MAINTENANCE POLICY on the account lets it attach the policy to an account or an app. A team that separates those duties can let one role author schedules while another decides where they apply. Day-to-day management uses ALTER MAINTENANCE POLICY, SHOW MAINTENANCE POLICIES, DESCRIBE MAINTENANCE POLICY and DROP MAINTENANCE POLICY.
Checkpoint 5 of 5· Fill the gap
A consumer wants one existing policy to govern upgrades for every app installed in their account, not just one. Which object completes the statement?
ALTER ? SET MAINTENANCE POLICY my_maintenance_policy FOR ALL APPLICATIONS;Account-wide application uses ALTER ACCOUNT with FOR ALL APPLICATIONS, while ALTER APPLICATION sets the policy on one named app. Policies live in a schema but are not applied through it.
Source: docs.snowflake.comSources4
Practise it for real
Release a version through the QA channel and upgrade a test instance to it
1.Run ALTER APPLICATION PACKAGE my_app_package REGISTER VERSION V1 USING '@stage/path';
Why: Packages with release channels enabled need the version registered first
You should see: Version V1 and its patch 0 exist, not yet assigned to any channel
2.Run ALTER APPLICATION PACKAGE my_app_package MODIFY RELEASE CHANNEL QA ADD VERSION V1;
Why: Only a version that is in a channel can be named by that channel's directive
You should see: V1 is in QA, and no security scan starts
3.Set the QA channel's default release directive to VERSION=v1 PATCH=0 with MODIFY RELEASE CHANNEL QA SET DEFAULT RELEASE DIRECTIVE
Why: Setting the directive is the step that releases the version
You should see: Targeted QA instances are queued for upgrade
4.In the test account, run ALTER APPLICATION my_app UPGRADE, replacing my_app with the name of the installed app
Why: A manual upgrade skips the wait for the queue
You should see: The instance runs the V1 setup script, or reports that an upgrade is already in progress
Stuck? Get a nudge
If the manual upgrade is rejected, check whether Snowflake has already started the automatic upgrade for that instance.
Sources
(5)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Changing the default release directive targets installed app instances that use the default directive.”
↩︎ What happens when a release directive changes“When the provider initiates an upgrade, Snowflake adds each app to be upgraded to a queue.”
↩︎ What happens when a release directive changes“For each targeted app instance, Snowflake runs the setup script for the target version or patch.”
↩︎ What happens when a release directive changes“After the upgrade process begins on an app, consumers can no longer manually upgrade the app.”
↩︎ What happens when a release directive changes“This is the earliest date and time when the upgrade can begin.”
↩︎ Scheduling when automatic upgrades begin“If the timestamp has already passed the upgrade is immediately scheduled.”
↩︎ Scheduling when automatic upgrades begin“You can only use the UPGRADE_AFTER clause if you are setting the version and patch.”
↩︎ Scheduling when automatic upgrades begin“The setup script is only backwards compatible with the most recent version of the app.”
↩︎ Version dependencies and rollback“If a single upgrade fails, providers must fix the reason for the upgrade failure before they can remove the version.”
↩︎ Version dependencies and rollback“It doesn’t target accounts assigned to a custom release directive.”
↩︎ Exam trap 1“You can only use the UPGRADE_AFTER clause if you are setting the version and patch.”
↩︎ Exam trap 2“This clause can’t be used to modify only the upgrade time and date.”
↩︎ Checkpoint - 2.
“For stateless objects, use CREATE OR REPLACE. Each app version has its own copy of these objects in a versioned schema.”
↩︎ What happens when a release directive changes“For stateful objects that don’t support CREATE OR ALTER, use CREATE IF NOT EXISTS followed by idempotent ALTER statements.”
↩︎ What happens when a release directive changes“The previous version remains active.”
↩︎ What happens when a release directive changes“When inserting rows, implement safeguards to prevent duplicate rows if unintended, as upgrades may be retried multiple times.”
↩︎ What happens when a release directive changes“Application roles are not versioned.”
↩︎ What happens when a release directive changes“Services aren’t supported in versioned schemas because they have their own version management.”
↩︎ What happens when a release directive changes“However, because only two versions of an app can exist at one time, version v3 does not have to be compatible with version v1.”
↩︎ Version dependencies and rollback“Code running in the previous version must handle state changes introduced in the new version.”
↩︎ Version dependencies and rollback“Use the version initializer function to rollback service upgrades to the previous version if the upgrade fails.”
↩︎ Version dependencies and rollback“If the setup script or target version initializer fails, Snowflake doesn’t make the target version’s objects in versioned schemas active.”
↩︎ Prediction“Avoid using CREATE OR REPLACE APPLICATION ROLE. Instead, use CREATE APPLICATION ROLE IF NOT EXISTS.”
↩︎ Checkpoint“because only two versions of an app can exist at one time, version v3 does not have to be compatible with version v1.”
↩︎ Checkpoint - 3.
“a change to a release directive takes effect in a remote region only after the application package is replicated to that region.”
↩︎ Scheduling when automatic upgrades begin“Dropping a version from a release channel is asynchronous and will only be truly dropped once all consumers have been upgraded off that version.”
↩︎ Version dependencies and rollback - 4.https://docs.snowflake.com/en/developer-guide/native-apps/consumer-maintenance-policiesOfficial docs
“Only the start time for a maintenance policy can be specified; not the end time or the duration of the maintenance policy.”
↩︎ Consumer-controlled maintenance policies“Each app or account can only have one maintenance policy set.”
↩︎ Consumer-controlled maintenance policies“Required to apply a maintenance policy to an account or app.”
↩︎ Consumer-controlled maintenance policies“ALTER ACCOUNT: Applies or removes a maintenance policy for all apps in the account.”
↩︎ Consumer-controlled maintenance policies
Also cited
- https://docs.snowflake.com/en/developer-guide/native-apps/consumer-maintenance-policies-providerOfficial docs
“The UPGRADE_DEADLINE parameter is required when UPGRADE_IN_MAINTENANCE_WINDOW is set to TRUE.”
↩︎ Exam trap 3