What you will be able to do
- Explain when an automatic upgrade starts after a provider sets a release directive, including UPGRADE_AFTER schedules
- Create a maintenance policy and apply it to one app or to every app in an account
- Predict whether an upgrade waits for a maintenance window or runs at the provider's upgrade deadline
- Upgrade an installed app manually with ALTER APPLICATION ... UPGRADE and track its upgrade state
- Distinguish a disabled app from an uninstalled one and say what upgrade behavior each has
Key concept
Upgrade start time — An installed app is not upgraded the moment a provider sets a new release directive. The upgrade starts at the earliest at the provider's UPGRADE_AFTER time, or it waits for the consumer's maintenance window until the provider's upgrade deadline. A consumer can only bring it forward by upgrading manually, and only before the automatic upgrade has started.
1.When an automatic upgrade starts after a release directive
An installed Native App upgrades itself. When the provider points a release directive at a new version or patch, every app instance that directive targets is upgraded in the consumer's account, and the consumer doesn't have to do anything. The provider-side mechanics are covered in How an app upgrade happens. This page is about the consumer's side: when that upgrade reaches your app, how you can delay it, and how you can start it early.
Setting a directive does not upgrade every instance at once. Snowflake adds each targeted app to a queue and upgrades it when resources are available. Across many accounts, this rollout can take a while. A queued instance therefore keeps running the old version for some time, and that delay is normal.
A provider can push the start back on purpose. The UPGRADE_AFTER clause on the default or a custom release directive sets a date and time before which the upgrade will not begin. It is a lower bound, not an appointment: the actual upgrade can start later, depending on how many apps and consumer accounts are in the queue. A timestamp that has already passed behaves as if UPGRADE_AFTER had not been set, and the upgrade is scheduled immediately. The clause can only be used together with a version and patch, so a provider cannot reschedule an existing directive by changing only the time.
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'Checkpoint 1 of 8· Fill the gap
A provider wants the automatic upgrade to patch 2 of v1_0 to begin no earlier than 6 April 2025, 11:00 UTC. They accept that it may start later, depending on the upgrade queue. Which clause completes the command?
ALTER APPLICATION PACKAGE hello_snowflake_package MODIFY RELEASE CHANNEL DEFAULT SET DEFAULT RELEASE DIRECTIVE VERSION = 'v1_0' PATCH = '2' ? = '2025-04-06T11:00:00Z'UPGRADE_AFTER sets a lower bound. The upgrade will not begin before this timestamp, but it can start later depending on how many apps and accounts are queued. It is neither an exact start time nor a deadline, and it can only be set together with VERSION and PATCH, as shown here.
Source: docs.snowflake.comSources1
2.Blocking upgrades outside a consumer maintenance window
UPGRADE_AFTER is set by the provider. A maintenance policy is the consumer's own control over upgrade timing. It is a schema-level object holding a cron schedule. When a new release directive arrives, an app covered by a policy does not upgrade immediately. It waits until the start time the policy defines. Use a policy to make upgrades land when someone is available to test the app, such as early Saturday, rather than in the middle of a business-critical run.
CREATE MAINTENANCE POLICY my_maintenance_policy
SCHEDULE = 'USING CRON 0 2 * * SAT UTC'
COMMENT = 'Weekly Saturday maintenance policy';The SCHEDULE uses the same syntax as the SCHEDULE parameter of CREATE TASK, and it describes only a start. A policy cannot say "from 02:00 to 06:00" because there is no end time or duration. Once created, the policy does nothing until you apply it, and there are two scopes for that:
ALTER ACCOUNT SET MAINTENANCE POLICY my_maintenance_policy FOR ALL APPLICATIONS;
ALTER APPLICATION my_app SET MAINTENANCE POLICY my_maintenance_policy;Each app or account can have only one maintenance policy. To move the window, change the existing policy's schedule instead of adding a second policy. ALTER MAINTENANCE POLICY can set a new SCHEDULE or COMMENT, unset the comment, or rename the policy. SHOW MAINTENANCE POLICIES and DESCRIBE MAINTENANCE POLICY let you inspect policies, and DROP MAINTENANCE POLICY removes one.
ALTER MAINTENANCE POLICY my_maintenance_policy SET
SCHEDULE = 'USING CRON 0 3 * * SUN UTC';| Privilege | Object | What it allows |
|---|---|---|
| CREATE MAINTENANCE POLICY | Schema | Create a new maintenance policy |
| APPLY MAINTENANCE POLICY | Account | Apply a maintenance policy to an account or app |
| APPLY or OWNERSHIP | Maintenance policy | Apply or view that policy; also required to alter it |
With no policy applied, the app does not wait for any consumer-defined window. The upgrade begins when the default upgrade time is reached: a system default, called the default system maintenance window where the provider has opted in to maintenance-window upgrades, that applies when the consumer has defined no schedule of their own. The consumer does not configure it. Creating and applying a policy is how a consumer replaces that default with a time of their choosing.
Checkpoint 2 of 8· Check yourself
Your team wants a Native App's upgrades to happen only between 02:00 and 06:00 UTC on Saturdays. You are writing the consumer maintenance policy. Which statement about what the policy can express is correct?
A maintenance policy's cron SCHEDULE describes only a start time. It has no end time or duration. Each app or account can have only one policy, so a second policy can't be used to close the window either.
“Only the start time for a maintenance policy can be specified; not the end time or the duration of the maintenance policy.”Source: docs.snowflake.com
3.Provider opt-in and the upgrade deadline
A consumer's maintenance policy has no effect unless the provider opts in. The provider does this per release directive by setting UPGRADE_IN_MAINTENANCE_WINDOW = TRUE. That setting requires UPGRADE_DEADLINE, the latest date and time by which the upgrade must be completed. A provider can also attach these settings to an existing release instead of releasing a new version for them.
ALTER APPLICATION PACKAGE my_app_package
MODIFY RELEASE CHANNEL DEFAULT
SET DEFAULT RELEASE DIRECTIVE
VERSION = v1_0
PATCH = 2
UPGRADE_IN_MAINTENANCE_WINDOW = TRUE
UPGRADE_DEADLINE = '2026-2-10T10:00:00Z';Once the provider has opted in, the outcome depends on what the consumer has configured. A consumer with a policy is upgraded at the next window or at the deadline, whichever comes first. A consumer without a policy is upgraded during the default system maintenance window. The deadline means a consumer can postpone an upgrade but cannot avoid it. If the policy runs rarely, for example a monthly cron, and the provider set a short deadline, the upgrade can run outside the window entirely. Schedule the policy often enough that the window, not the deadline, decides when the upgrade happens.
| Setting | Set on | Effect on timing |
|---|---|---|
| UPGRADE_AFTER | Release directive | Earliest time the upgrade can begin; the actual start may be later |
| UPGRADE_IN_MAINTENANCE_WINDOW = TRUE | Release directive | Upgrade waits for the consumer's next maintenance window |
| UPGRADE_DEADLINE | Release directive | Required with the above; after it, the upgrade proceeds regardless of the policy |
| AUTOMATIC_APPLICATION_MAINTENANCE = TRUE | Application package | Snowpark Container Services compute pool node maintenance follows the app upgrade in the same window |
The two timing mechanisms cannot be combined. Setting UPGRADE_AFTER and UPGRADE_IN_MAINTENANCE_WINDOW on the same directive fails with an error, so a directive uses either a fixed earliest start or the consumer's window, never both.
Checkpoint 3 of 8· Check yourself
A provider runs ALTER APPLICATION PACKAGE ... SET DEFAULT RELEASE DIRECTIVE VERSION = v1_0 PATCH = 2 with UPGRADE_AFTER = '2026-03-01T00:00:00Z', UPGRADE_IN_MAINTENANCE_WINDOW = TRUE and UPGRADE_DEADLINE = '2026-03-15T00:00:00Z'. The goal is for no upgrade to start before 1 March, and after that for each upgrade to wait for the consumer's window. What happens?
The two timing mechanisms are mutually exclusive. A directive uses either a fixed earliest start (UPGRADE_AFTER) or the consumer's maintenance window with a required deadline. If you set both, the command fails instead of one setting quietly winning.
“You can’t set the UPGRADE_AFTER and UPGRADE_IN_MAINTENANCE_WINDOW parameters at the same time. If you try to set both, the command fails with an error.”Source: docs.snowflake.com
4.Upgrading manually and tracking upgrade state
A consumer who wants a new version sooner can start the upgrade themselves. They run ALTER APPLICATION <name> UPGRADE on the installed app, and it upgrades to whatever the release directive in the release channel currently specifies. The command acts on the application object in the consumer's account. ALTER APPLICATION PACKAGE and setting release directives are provider commands on the package, and CREATE APPLICATION installs an app rather than upgrading one.
There is a time limit on this. A manual upgrade is only possible while the automatic upgrade of that instance has not yet started. Once the automatic upgrade has started, the consumer can no longer upgrade the app manually. The two upgrade paths never run side by side, and starting a manual upgrade does not cancel or roll back an automatic one.
To upgrade at a chosen time without a maintenance policy, schedule the command as a task. The example below retries the upgrade every hour from 09:00 to 17:00 on Sundays, Los Angeles time. Each run picks up whatever upgrade is available at that moment.
CREATE OR REPLACE TASK APP_UPGRADE_TASK
SCHEDULE = 'USING CRON 0 9-17 * * SUN America/Los_Angeles'
WAREHOUSE = 'WH'
AS
ALTER APPLICATION hello_snowflake_app UPGRADE;
ALTER TASK APP_UPGRADE_TASK RESUME;You can check an upgrade's progress in two places. DESCRIBE APPLICATION shows upgrade_after, upgrade_state, upgrade_target_version and upgrade_target_patch for one app. The APPLICATION_STATE view in the Data Sharing Usage schema exposes the same UPGRADE_STATE values. That view is the place to monitor in-flight upgrades, including a slow refresh to remote regions after an upgrade.
| UPGRADE_STATE | Meaning |
|---|---|
| QUEUED | Queued for upgrade |
| QUEUED_DELAYED | Queued for an upgrade scheduled for a future time |
| UPGRADING | Upgrade in progress |
| QUEUED_RETRY | One or more attempts failed; another attempt is queued |
| FAILED | All attempts failed; stays FAILED until the release directive points to a different version |
| COMPLETE | Setup script finished; app created or upgraded |
| DISABLED | App and its upgrades are disabled; inaccessible to consumers |
Checkpoint 4 of 8· Match them up
DESCRIBE APPLICATION returns an upgrade_state for your installed app. Match each value to what it tells you as the consumer.
Tap a term, then the definition that fits it.
You can only upgrade manually before the automatic upgrade of your instance has started. A QUEUED_DELAYED app hasn't started yet, so you can still upgrade it manually. An UPGRADING app has already started, so the manual path is closed. QUEUED_RETRY means Snowflake will try again on its own. FAILED is cleared only when the provider points the directive at a different version.
“After the upgrade process begins on an app, consumers can no longer manually upgrade the app.”Source: docs.snowflake.com
Checkpoint 5 of 8· Exam question
Which SQL command does a consumer use to manually trigger an app upgrade before the provider's automatic upgrade process begins for that instance?
Correct answer: A — ALTER APPLICATION app_name UPGRADE
- A. This is the consumer-side command that immediately upgrades an installed application object to the version and patch currently specified in the release directive, as long as an automatic upgrade has not already started for that instance.
- B. This targets the application package, which is a provider-side object; consumers do not own or alter application packages, so this is not a valid consumer upgrade action.
- C. CREATE APPLICATION installs a new application object from a listing; it does not upgrade an existing installed instance.
- D. Setting a release directive is a provider action performed on the application package to control which version consumers receive; it is not how a consumer manually upgrades their own instance.
Checkpoint 6 of 8· Exam question
A consumer is deciding whether to manually upgrade their app instance. The provider's automatic upgrade process has already begun for that instance. What happens if the consumer now tries to run a manual upgrade?
Correct answer: A — The consumer can no longer manually trigger upgrades once the automatic process has started for that instance.
- A. Once Snowflake's automated upgrade process has started for an app instance, the provider's process takes precedence and manual upgrade attempts are no longer available for that instance.
- B. There is no rollback-and-replace mechanic; the framework simply blocks new manual upgrade attempts once the automatic process has taken over.
- C. A prior manual upgrade does not cancel a later automatic upgrade; the two are sequential, not mutually cancelling.
- D. Snowflake does not run two upgrade paths concurrently for the same instance; only one upgrade process is active on an instance at a time.
Checkpoint 7 of 8· Exam question
Which view lets a consumer monitor the progress of an in-flight application upgrade, including states such as QUEUED and UPGRADING?
Correct answer: A — APPLICATION_STATE
- A. APPLICATION_STATE is the view consumers query to track the lifecycle state of an installed application instance during and after an upgrade attempt.
- B. This is not a recognized native app monitoring object for upgrade progress; it does not exist as the upgrade-tracking view.
- C. There is no UPGRADE_HISTORY view in the Native App Framework for tracking instance-level upgrade state.
- D. State tracking applies to the application object, not a separate package-level state view; this name does not match the actual monitoring object.
5.What upgrades mean for disabled and uninstalled apps
Uninstalling an app takes it out of the upgrade process for good, and its upgrade record goes with it. The APPLICATION_STATE view keeps no history: once an app is uninstalled, the row describing its upgrade state is no longer available. A provider counting instances that reached the target version after a release will not find an uninstalled instance reported as failed or stuck. It is simply absent.
An app becomes disabled when something outside the upgrade process makes it unusable, and the consumer does not choose it. The causes sit with the application package, the installed app or the consumer account: Snowflake or the provider disables the app, the account is locked or suspended, the provider drops the version the app runs on, a trial exceeds its usage or duration limit, or a paid listing's payment is missing or out of date. The DISABLEMENT_REASONS column of APPLICATION_STATE names the cause, and until it is cleared the app cannot be used.
Three situations get confused, and only one of them is an uninstall. An app whose compute is merely suspended stays installed and keeps its upgrade schedule. A disabled app is still installed but sits outside normal upgrades: it cannot be upgraded while disabled, and when it is re-enabled it is upgraded automatically to the version and patch of the release directive. An uninstalled app no longer exists, so there is nothing to upgrade or to re-enable.
Re-enabling has a limit, and that limit is where uninstalling becomes the remedy. If the version the app was on has been dropped from the application package, the app is no longer usable and must be uninstalled and reinstalled from a current listing. An app stuck in INSTALL_FAILED follows the same pattern: it stays in that state until it is dropped, and no later release directive will move it. Reinstalling creates a fresh instance on the current version; it is not an upgrade of the old one.
Checkpoint 8 of 8· Check yourself
An app was disabled for weeks. The provider has since dropped the version it runs from the application package, and the app now shows as unusable. What is the way forward?
Automatic upgrade after re-enabling only works while the target version path still exists. When the app's version was dropped from the package, the instance cannot be upgraded, so it has to be removed and installed again.
“the app is no longer usable and must be uninstalled and reinstalled from a current listing.”Source: docs.snowflake.com
Sources
(8)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“When the provider initiates an upgrade, Snowflake adds each app to be upgraded to a queue.”
↩︎ When an automatic upgrade starts after a release directive“This is the earliest date and time when the upgrade can begin.”
↩︎ When an automatic upgrade starts after a release directive“If the timestamp has already passed the upgrade is immediately scheduled.”
↩︎ When an automatic upgrade starts after a release directive“You can only use the UPGRADE_AFTER clause if you are setting the version and patch.”
↩︎ When an automatic upgrade starts after a release directive“After the upgrade process begins on an app, consumers can no longer manually upgrade the app.”
↩︎ Upgrading manually and tracking upgrade state“You can use the APPLICATION_STATE view in the Data Sharing Usage schema to monitor the state.”
↩︎ Upgrading manually and tracking upgrade state“Disabled apps are not part of the normal upgrade process and cannot be upgraded.”
↩︎ What upgrades mean for disabled and uninstalled apps“An app installed in a consumer account can become disabled for multiple reasons, including:”
↩︎ What upgrades mean for disabled and uninstalled apps“After the upgrade process begins on an app, consumers can no longer manually upgrade the app.”
↩︎ Exam trap 4 - 2.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.”
↩︎ Blocking upgrades outside a consumer maintenance window“Each app or account can only have one maintenance policy set.”
↩︎ Blocking upgrades outside a consumer maintenance window“If a consumer does not set a maintenance policy, the upgrade begins when the default upgrade time is reached.”
↩︎ Blocking upgrades outside a consumer maintenance window“the upgrade is delayed until the start date and time specified in the maintenance policy.”
↩︎ Key concept“Only the start time for a maintenance policy can be specified; not the end time or the duration of the maintenance policy.”
↩︎ Exam trap 1 - 3.https://docs.snowflake.com/en/developer-guide/native-apps/consumer-maintenance-policies-providerOfficial docs
“If the consumer has not set a maintenance policy, the upgrade happens during the default system maintenance window.”
↩︎ Blocking upgrades outside a consumer maintenance window“The UPGRADE_DEADLINE parameter is required when UPGRADE_IN_MAINTENANCE_WINDOW is set to TRUE.”
↩︎ Provider opt-in and the upgrade deadline“If the consumer has not set a maintenance policy, the upgrade happens during the default system maintenance window.”
↩︎ Provider opt-in and the upgrade deadline“The application upgrades first, then any compute pool node maintenance follows.”
↩︎ Provider opt-in and the upgrade deadline“After this deadline, the upgrade proceeds regardless of the”
↩︎ Exam trap 2“If you try to set both, the command fails with an error.”
↩︎ Exam trap 3“or until the upgrade deadline is reached, whichever comes first.”
↩︎ Prediction“You can’t set the UPGRADE_AFTER and UPGRADE_IN_MAINTENANCE_WINDOW parameters at the same time. If you try to set both, the command fails with an error.”
↩︎ Checkpoint - 4.
“This parameter uses the same syntax as the SCHEDULE parameter of the CREATE TASK command.”
↩︎ Blocking upgrades outside a consumer maintenance window - 5.
“Note that the application provider must explicitly opt in to this feature to honor consumer maintenance schedules when releasing new upgrades.”
↩︎ Provider opt-in and the upgrade deadline - 6.
“as long as the upgrade of the instance installed in their account has not started”
↩︎ Upgrading manually and tracking upgrade state“Consumers can use the DESCRIBE APPLICATION command to view the status of an upgrade.”
↩︎ Upgrading manually and tracking upgrade state - 7.
“QUEUED_DELAYED: The application object is queued for an upgrade that is scheduled for a future time.”
↩︎ Upgrading manually and tracking upgrade state“If an app is uninstalled the information contained in this view is no longer available.”
↩︎ What upgrades mean for disabled and uninstalled apps“The application object remains in the INSTALL_FAILED state until it is dropped.”
↩︎ What upgrades mean for disabled and uninstalled apps“If an app is uninstalled the information contained in this view is no longer available.”
↩︎ Exam trap 5 - 8.https://docs.snowflake.com/en/developer-guide/native-apps/ui-consumer-managing-applicationsOfficial docs
“The consumer account is inactive after being locked or suspended.”
↩︎ What upgrades mean for disabled and uninstalled apps“the app is no longer usable and must be uninstalled and reinstalled from a current listing.”
↩︎ What upgrades mean for disabled and uninstalled apps