What you will be able to do
- Create a new application version with ADD VERSION or REGISTER VERSION and predict which version identifier Snowflake assigns
- Add patches to a version and predict the patch number Snowflake assigns when none is given
- Move a version through the QA, ALPHA and DEFAULT release channels and know which step triggers the security scan
- Set a release directive to publish a version or patch to consumers
- Release a version or patch with UPGRADE_IN_MAINTENANCE_WINDOW and UPGRADE_DEADLINE so the upgrade respects consumer-controlled maintenance policies without being postponed forever
Key concept
The release directive is the release step — You can register a version, add patches and place it in a release channel, and no installed instance moves to it. Consumers only receive a version or patch once you set a release directive that points at it, and setting that directive starts the upgrade.
1.Versions, patches and the two-version limit
A Snowflake Native App changes in two sizes. A version carries major change: new features, changed behaviour, and any change to the app's state, such as new tables or columns. A patch belongs to one version and carries small fixes, typically security fixes. Neither one is a diff. Each version and each patch is a complete set of app files, with its own manifest.yml and its own setup script, uploaded to a stage.
The two sizes have different limits, and those limits decide how you release. A release channel holds at most two versions at a time, so a third version only fits after one of the existing two is removed. Patches are much cheaper. A single version can have up to 130 patches, but once a patch exists it cannot be dropped. Expect a version to stay around for a while, and treat each patch as permanent history.
Checkpoint 1 of 8· Check yourself
A provider's DEFAULT release channel already holds versions v1 and v2 of their app. They have built v3, which adds new tables, and want to release it in DEFAULT. What is true?
Each release channel can hold at most two versions, so a third version only fits after one of the existing two is removed. The limit applies to each channel, not to the whole package. Patches can't be dropped and don't count toward the version limit.
“each release channel only allows two versions of an app at a time.”Source: docs.snowflake.com
2.Creating a new version
The classic command is ALTER APPLICATION PACKAGE ... ADD VERSION. Its USING clause names the stage directory that holds the version's files. A version identifier in the command is optional. If you leave it out, Snowflake reads the identifier from the manifest.yml in that directory. If the manifest doesn't name one either, the command has to supply it. When both name an identifier, the one in the command wins. The same fallback applies to LABEL, the display name consumers see: leave it out and the label in manifest.yml is used. Identifiers are names you choose, up to 30 characters, such as v1_1. Snowflake never generates them as a numeric sequence.
ALTER APPLICATION PACKAGE <name> ADD VERSION [ <version_identifier> ]
USING <path_to_version_directory> [ LABEL = '<display_label>' ]
ALTER APPLICATION PACKAGE <name> DROP VERSION <version_identifier>
ALTER APPLICATION PACKAGE <name> ADD PATCH [<patch_number>] FOR VERSION [<version_identifier>]
USING <path_to_version_directory> [ LABEL = '<display_label>' ]Running this command needs OWNERSHIP on the package or the global MANAGE VERSIONS privilege. The command also respects the version limit. If two versions are already active, for example because the current version hasn't finished rolling out, adding another version fails with an error.
Packages with release channels enabled use a different command. Release channels are on by default for new packages, and ADD VERSION ... USING is not supported there. Instead you register the version with REGISTER VERSION ... USING, which creates the version and its patch 0 without assigning it to any channel. A package can hold at most two unassigned versions. To make room you run DEREGISTER VERSION, which removes the version and all its patches. The role doing this work needs the MANAGE RELEASES privilege.
ALTER APPLICATION PACKAGE my_app_package REGISTER VERSION V1 USING '@stage/path';| Command | What it does | When you use it |
|---|---|---|
| ADD VERSION [id] USING '<path>' | Creates a version from staged files | Packages without release channels |
| REGISTER VERSION V1 USING '@stage/path' | Creates the version and patch 0, assigned to no channel | Packages with release channels enabled |
| MODIFY RELEASE CHANNEL QA ADD VERSION V1 | Puts an already-registered version into a channel; takes no USING path | After REGISTER, before setting a directive |
Checkpoint 2 of 8· Fill the gap
A provider just created a new application package and left its settings at their defaults. They have uploaded v1 of their app's files to a stage. Which keyword completes the statement that creates the version from those files?
ALTER APPLICATION PACKAGE my_app_package ? VERSION V1 USING '@stage/path';New application packages have release channels turned on by default, and those packages don't support ADD VERSION ... USING. You create the version with REGISTER VERSION ... USING instead. That creates V1 and its patch 0 without putting it in any channel, so you add it to a channel afterwards.
Source: docs.snowflake.comCheckpoint 3 of 8· Exam question
When a provider runs ALTER APPLICATION PACKAGE ... ADD VERSION without specifying a version identifier, what determines the version identifier that Snowflake assigns to the new version?
Correct answer: A — Snowflake reads the version identifier from the manifest.yml file bundled in the version directory.
- A. Correct: the version identifier can be omitted from the ADD VERSION command as long as it is defined in the manifest.yml for that version directory; Snowflake falls back to reading it from there.
- B. Incorrect: Snowflake does not auto-number versions sequentially. Automatic numbering applies to patches when a patch number is omitted, not to version identifiers.
- C. Incorrect: dropped version identifiers are not recycled automatically. A new identifier must come from the command or the manifest, never from a prior dropped version.
- D. Incorrect: the command does not fail outright when the identifier is left off the command, because the manifest.yml can supply the fallback value.
Checkpoint 4 of 8· Exam question
A provider runs ALTER APPLICATION PACKAGE ... ADD VERSION to publish a new version of a Snowflake Native App. Which clause is required to point Snowflake at the stage location containing the version's files?
Correct answer: A — USING
- A. Correct: the USING clause supplies the stage path where the version's manifest, setup script, and other files live.
- B. Incorrect: LABEL only sets an optional display name for consumers and does not point to a stage location.
- C. Incorrect: FOR VERSION is used with ADD PATCH to identify the parent version, not with ADD VERSION to locate files.
- D. Incorrect: WITH STAGE is not valid syntax for this command; the stage location is supplied through USING.
3.Adding patches to a version
Patch numbering starts automatically. A new version gets patch 0 as soon as it is created. After that, ADD PATCH [<patch_number>] FOR VERSION <version_identifier> USING <path> adds the next patch from its own staged files. You can choose the number yourself, or leave it out and let Snowflake add 1 to the highest existing patch. With release channels, a patch follows its version: once a version is in a channel, every later patch of that version belongs to the same channel.
Patches have one strict design rule: no state changes. Snowflake doesn't limit how many patches of one version are active at the same time, so instances on patch 3 and patch 5 can run side by side. If patch 5 adds a column that patch 3's code can't handle, the two break each other. Keep table and column changes for a new version, and use patches for bug fixes and minor additions that leave state alone.
Checkpoint 5 of 8· Check yourself
Version v2 of your app is live in DEFAULT. Some consumers' instances run patch 3 and others run patch 4. A fix you need to ship also adds a new column to an existing table. How should you ship it?
Snowflake doesn't limit how many patches of one version are active at the same time. A column added in a patch could break instances still running older patch code. State changes such as new tables or columns belong in a new version. Patches also can't be dropped, so you can't undo one by removing it.
“Providers must avoid making changes to the state of an app in a patch to avoid incompatibility across multiple patches.”Source: docs.snowflake.com
Checkpoint 6 of 8· Exam question
A provider has version V2 with patches 0 and 1 already published. The provider runs: ALTER APPLICATION PACKAGE my_pkg ADD PATCH FOR VERSION V2 USING '@stage.schema.stage/v2' without specifying a patch number. What patch number will Snowflake assign?
Correct answer: A — Patch 2, because Snowflake auto-increments the patch number when it is omitted.
- A. Correct: when the patch number is left out of ADD PATCH, Snowflake auto-increments from the highest existing patch number for that version, so patch 2 follows patches 0 and 1.
- B. Incorrect: omitting the patch number does not restart numbering at zero; it continues the sequence forward from the existing highest patch.
- C. Incorrect: the patch number is optional in this command precisely so that Snowflake can auto-increment it.
- D. Incorrect: reusing an existing patch number would overwrite it rather than add a new patch, which is not the auto-increment behavior.
4.Promoting through channels and setting the directive
A registered version does nothing until you add it to a channel. Each release channel (QA, ALPHA, DEFAULT) serves a different audience. In the release workflow, a version moves from QA to ALPHA to DEFAULT as it passes validation. You add it with MODIFY RELEASE CHANNEL <channel> ADD VERSION. Only a version that is in a channel can be the target of that channel's release directive.
ALTER APPLICATION PACKAGE my_app_package MODIFY RELEASE CHANNEL QA ADD VERSION V1;The automated security scan is the main difference between the stages. Adding a version only to QA doesn't start the scan. Adding it to ALPHA or DEFAULT does, and so does adding a patch to a version that is already in one of those channels. A version that fails the scan in ALPHA can no longer be used. Snowflake therefore recommends testing a version or patch fully before it reaches a scanning channel, so you avoid repeated scan runs.
| Action | Scan initiated? |
|---|---|
| Add a version only to QA | No |
| Add patches to a version that is not in ALPHA or DEFAULT | No |
| Add a version to ALPHA or DEFAULT | Yes |
| Add a patch to a version already in ALPHA or DEFAULT | Yes |
Setting a directive is what releases the code. Each channel has its own default and custom release directives, and each directive names a version and a patch. When you point a directive at a new version or patch, Snowflake starts upgrading the installed instances that directive targets.
ALTER APPLICATION PACKAGE my_app_package
MODIFY RELEASE CHANNEL ALPHA
SET DEFAULT RELEASE DIRECTIVE VERSION=v1 PATCH=10;Checkpoint 7 of 8· Check yourself
In a package with release channels enabled, V1 is in the QA channel only, and V2 was added to ALPHA last week. Which of these actions starts the automated security scan?
Adding a patch to a version that is already in ALPHA or DEFAULT starts the scan again. Patches to a version that is only in QA don't start it, and neither does registering a version that isn't in any channel.
“Adding a patch to a version that is already added to the ALPHA or DEFAULT release channel”Source: docs.snowflake.com
5.Releasing into consumer-controlled maintenance windows
A release directive can hand the timing of an upgrade to each consumer's own maintenance schedule instead of starting it the moment the directive changes. Consumers establish these consumer-controlled maintenance policies in their own accounts. The provider's part happens at release time: setting UPGRADE_IN_MAINTENANCE_WINDOW = TRUE on the default or custom directive that names the new version and patch. Without that flag, a consumer's policy has nothing to act on for that release.
Opting in always comes with a deadline. UPGRADE_DEADLINE is required whenever UPGRADE_IN_MAINTENANCE_WINDOW is TRUE, and once that moment passes the upgrade goes ahead whatever the consumer's policy says. Each instance therefore upgrades at its next maintenance window or at the deadline, whichever comes first. Instances whose consumers never set a policy upgrade during the default system maintenance window.
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';Set the deadline from the consumer's calendar, not from your release date. A consumer whose policy runs every Saturday at 02:00 UTC gets only one window a week. A deadline four days after release may arrive before their first window, so it overrides their policy before the policy ever applies. Leave at least a couple of their windows before the deadline, so they have time to test the upgrade and fix anything it breaks.
UPGRADE_AFTER and UPGRADE_IN_MAINTENANCE_WINDOW can't be set together. A directive that sets both fails with an error. Use UPGRADE_AFTER when the provider picks one earliest start time for every instance. Use the maintenance-window flag when each consumer's own schedule should decide.
Apps that run Snowpark Container Services can put compute pool node maintenance into the same window. Setting AUTOMATIC_APPLICATION_MAINTENANCE = TRUE on the application package schedules node software upgrades in the consumer's maintenance window. The application upgrades first, and node maintenance follows, so the consumer sees one disruption rather than two.
Checkpoint 8 of 8· Check yourself
A provider wants a release to wait for consumers' maintenance windows, but also wants nothing to start before 1 November. They run SET DEFAULT RELEASE DIRECTIVE with VERSION, PATCH, UPGRADE_IN_MAINTENANCE_WINDOW = TRUE, a valid UPGRADE_DEADLINE, and UPGRADE_AFTER = '2026-11-01T00:00:00Z'. What happens?
The two scheduling parameters are mutually exclusive, so a directive that sets both is rejected with an error. The provider has to choose either a single earliest start time or consumer maintenance windows bounded by a deadline.
“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
Sources
(7)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Each version and patch must have its own manifest file and setup script.”
↩︎ Versions, patches and the two-version limit“However, each release channel only allows two versions of an app at a time.”
↩︎ Versions, patches and the two-version limit“Unlike versions, patches should only contain small updates such as security fixes.”
↩︎ Versions, patches and the two-version limit“Patches cannot be dropped.”
↩︎ Versions, patches and the two-version limit“The two-version limit applies to each release channel instead of per application package.”
↩︎ Versions, patches and the two-version limit“When a provider adds a new version to a release channel, the new version is automatically assigned patch 0 by default.”
↩︎ Adding patches to a version“If no patch number is provided, Snowflake automatically increments the patch version by 1.”
↩︎ Adding patches to a version“if a version assigned to this release channel fails the security scan, it can no longer be used.”
↩︎ Promoting through channels and setting the directive“each release channel only allows two versions of an app at a time.”
↩︎ Checkpoint - 2.
“A single version can have up to 130 patches.”
↩︎ Versions, patches and the two-version limit“Adds a version or patch using the application files located in the path to a stage location specified by path_to_version_directory.”
↩︎ Creating a new version“If you do not specify a version_identifier in the manifest file, you must specify a version_identifier as part of this command.”
↩︎ Creating a new version“If you omit the LABEL clause, the label specified in the manifest.yml file is used.”
↩︎ Creating a new version“Version identifiers have a maximum limit of 30 characters.”
↩︎ Creating a new version“Modifying the version requires a role with the OWNERSHIP privilege on the application or the global MANAGE VERSIONS privilege.”
↩︎ Creating a new version“If two versions are active, for example, if the current version has not finished rolling out, adding a new version results in an error.”
↩︎ Creating a new version“If you specify version_identifier as part of this command, it takes precedence over version_identifier specified in the manifest file.”
↩︎ Exam trap 1 - 3.
“This command creates version V1 of the app and also creates patch 0.”
↩︎ Creating a new version“There is a maximum of two unassigned versions (not added to any release channels) allowed in the application package.”
↩︎ Creating a new version“To use release channels, you must use a role that has been granted the MANAGE RELEASES privilege.”
↩︎ Creating a new version“After a version has been added to a release channel, subsequent patches for that version are also bound to that release channel.”
↩︎ Adding patches to a version“you must explicitly add the version to a release channel to set the release directive for the app.”
↩︎ Promoting through channels and setting the directive“When release channels are enabled for an application package, each channel has its own release directive.”
↩︎ Promoting through channels and setting the directive“The ADD VERSION USING '@stage/path' clause of the ALTER APPLICATION PACKAGE command is not supported for application packages that have release channels enabled.”
↩︎ Exam trap 2“Adding a version to the QA release channel does not initiate the automated security scan.”
↩︎ Exam trap 3 - 4.
“Providers must avoid making changes to the state of an app in a patch to avoid incompatibility across multiple patches.”
↩︎ Adding patches to a version“This initiates an automated upgrade for the app instances targeted by the default or custom release directive.”
↩︎ Key concept - 5.
“Adding a patch to a version that is already added to the ALPHA or DEFAULT release channel”
↩︎ Promoting through channels and setting the directive“Snowflake recommends that you fully test a new version or patch of your app locally before initiating the security scan”
↩︎ Promoting through channels and setting the directive - 6.https://docs.snowflake.com/en/developer-guide/native-apps/consumer-maintenance-policies-providerOfficial docs
“you can specify that upgrades should respect consumer maintenance policies by setting the UPGRADE_IN_MAINTENANCE_WINDOW parameter to TRUE.”
↩︎ Releasing into consumer-controlled maintenance windows“After this deadline, the upgrade proceeds regardless of the consumer’s maintenance policy.”
↩︎ Releasing into consumer-controlled maintenance windows“the upgrade is delayed until the next maintenance window defined by the consumer’s policy, or until the upgrade deadline is reached, whichever comes first.”
↩︎ Releasing into consumer-controlled maintenance windows“If the consumer has not set a maintenance policy, the upgrade happens during the default system maintenance window.”
↩︎ Releasing into consumer-controlled maintenance windows“Set the deadline to a date and time that allows sufficient time for consumers to complete the upgrade within their maintenance windows.”
↩︎ Releasing into consumer-controlled maintenance windows“You can’t set the UPGRADE_AFTER and UPGRADE_IN_MAINTENANCE_WINDOW parameters at the same time.”
↩︎ Releasing into consumer-controlled maintenance windows“With this enabled, Snowpark Container Services compute pool node software upgrades are scheduled to occur during the consumer’s maintenance window.”
↩︎ Releasing into consumer-controlled maintenance windows“The application upgrades first, then any compute pool node maintenance follows.”
↩︎ Releasing into consumer-controlled maintenance windows“The UPGRADE_DEADLINE parameter is required when UPGRADE_IN_MAINTENANCE_WINDOW is set to TRUE.”
↩︎ Exam trap 4“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 - 7.https://docs.snowflake.com/en/developer-guide/native-apps/consumer-maintenance-policiesOfficial docs
“As a consumer, you should schedule your upgrades as soon as possible during a time when you can be available to test the upgrade”
↩︎ Releasing into consumer-controlled maintenance windows