Native App Upgrades, Rollback and Maintenance Policies

1.How a release directive change triggers an upgrade

Consumers never pull a new version on their own initiative. The provider pushes it. When you point a release directive at a different version or patch, Snowflake puts every affected installed app in a queue and upgrades each one as resources allow. Across many consumers this can take a while. You can ask consumers to upgrade manually to speed things up, but a consumer can only do so before Snowflake has started upgrading their app.

ALTER APPLICATION PACKAGE my_application_package
  MODIFY RELEASE CHANNEL DEFAULT
  SET DEFAULT RELEASE DIRECTIVE
  VERSION = v2
  PATCH = 0;

ALTER APPLICATION <name>  ? 

The full provider workflow puts testing before the directive change, because the directive change is what reaches consumers. For apps published through Cross-Cloud Auto-Fulfillment, consumers in remote regions may not see the change until the listing refreshes. The APPLICATION_STATE view in the Data Sharing Usage schema shows the state of each installed instance.

Sources1

2.Scheduling upgrades with UPGRADE_AFTER

To delay an upgrade, add UPGRADE_AFTER when you set a default or custom release directive. The timestamp is the earliest the upgrade can start. The real start may be later, depending on how many apps and consumer accounts are involved. A timestamp that has already passed schedules the upgrade right away, the same as leaving the clause out. UPGRADE_AFTER only works in the same statement that sets VERSION and PATCH. You cannot use it to change 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'

Sources1

3.Version dependencies and rollback

Versions depend on each other in a simple chain. Snowflake allows only the previous version to be active. Before upgrading anyone to v3, it moves every v1 install to v2. That means a setup script only has to handle the difference from the version just before it. Code from the previous version can still be running during an upgrade, so it must cope with state changes the new version makes. State changes belong in versions, never in patches.

Setup scripts must also be self-contained. A consumer can install v3 without ever having had v2, so v3 must contain every CREATE and ALTER needed to build the app from nothing. They must also be idempotent: Snowflake reruns a failed setup script from the start, and upgrades can be retried. Use CREATE IF NOT EXISTS or CREATE OR ALTER for tables, ALTER TABLE ADD COLUMN IF NOT EXISTS for new columns, and CREATE OR REPLACE only for stateless objects such as procedures. Application roles are not versioned. Recreating one with CREATE OR REPLACE APPLICATION ROLE drops the grants consumers gave it.

When an upgrade fails, objects in a versioned schema go back to the previous version. Services in apps with containers do not. They live outside versioned schemas, so a successful ALTER SERVICE has already upgraded the service before a later step fails. To handle this, the manifest can name a version initializer, a callback stored procedure. It starts or upgrades services and can roll them back if the upgrade fails. Calling SYSTEM$WAIT_FOR_SERVICES in the setup script pauses it until the named services are READY, one of them FAILED, or the timeout passes.

Sources12

4.Consumer-controlled maintenance policies

The exam guide marks this feature as untested until it has been in Public Preview for three months, but it is part of the objective.

With a maintenance policy, the consumer decides when upgrades happen. On the provider side, you set UPGRADE_IN_MAINTENANCE_WINDOW = TRUE on the release directive. This requires an UPGRADE_DEADLINE, so consumers cannot postpone forever. Once the deadline passes, the upgrade goes ahead regardless of the policy. You cannot combine this with UPGRADE_AFTER in the same command; trying to set both returns an error.

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';

For apps that use Snowpark Container Services, setting AUTOMATIC_APPLICATION_MAINTENANCE = TRUE on the package puts compute pool node maintenance in the same window. The app upgrades first, then the node maintenance runs. Consumers without a policy are upgraded during the default system maintenance window.

On the consumer side, CREATE MAINTENANCE POLICY sets a cron schedule. A policy only defines a start time, not an end time or duration. Each account or app can have only one policy.

CREATE MAINTENANCE POLICY my_maintenance_policy
  SCHEDULE = 'USING CRON 0 2 * * SAT UTC'
  COMMENT = 'Weekly Saturday maintenance policy';

Sources34

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.A consumer maintenance policy lets the consumer postpone a provider's upgrade indefinitely.Why is that wrong?

   UPGRADE_DEADLINE is required when UPGRADE_IN_MAINTENANCE_WINDOW is TRUE. Once the deadline passes, the upgrade goes ahead regardless of the policy.

   Covered in Consumer-controlled maintenance policies

2. 2.Using CREATE OR REPLACE APPLICATION ROLE in the setup script is a safe way to keep roles current across versions.Why is that wrong?

   Application roles are not versioned. OR REPLACE drops and recreates the role, so account-level roles that consumers granted to it would have to be granted again. Use CREATE APPLICATION ROLE IF NOT EXISTS.

   Covered in Version dependencies and rollback

3. 3.A consumer can run ALTER APPLICATION ... UPGRADE at any time, even after the automated upgrade of their app has started.Why is that wrong?

   Manual upgrade is a way to get ahead of the queue. Once Snowflake has started upgrading an app, the consumer can no longer upgrade it manually.

   Covered in How a release directive change triggers an upgrade

Practise it for real

Release a new version through QA in your own provider account, then upgrade a test install to it.

1. 1.Stage the new version's files, including its own manifest and setup script, then run ALTER APPLICATION PACKAGE my_app_package REGISTER VERSION V1 USING '@stage/path';

   Why: With release channels enabled, a version has to be registered before it can go into a channel.

   You should see: Version V1 with patch 0 exists in the package and is not in any channel yet.

2. 2.Run ALTER APPLICATION PACKAGE my_app_package MODIFY RELEASE CHANNEL QA ADD VERSION V1;

   Why: Putting the version in QA lets you test it without starting the security scan.

   You should see: SHOW RELEASE CHANNELS IN APPLICATION PACKAGE my_app_package lists V1 under QA.

3. 3.Set the QA default release directive to VERSION=V1 PATCH=0, then run CREATE APPLICATION my_app FROM APPLICATION PACKAGE my_app_package USING RELEASE CHANNEL QA; with a role that has CREATE PREVIEW APPLICATION.

   Why: A directive must point at the version before you can install it from the channel.

   You should see: my_app installs and its setup script finishes without errors.

4. 4.Add a patch with ALTER APPLICATION PACKAGE my_app_package ADD PATCH FOR VERSION V1 USING the patch's stage path, point the QA directive at the new patch, then run ALTER APPLICATION my_app UPGRADE.

   Why: This walks through a patch release and a consumer-triggered upgrade, and checks that the setup script can safely run again on an existing install.

   You should see: Patch 1 is created automatically, and my_app upgrades to it without errors.