Versioning, Patching, and Upgrading an Application¶

About Versions and Patches¶

In general, use new versions to introduce new features or behavior changes for an application. The upgrade (and rollback) process from one major version to another major version ensures that no code can be running from a previous version. This means that the setup script needs to only be compatible with the immediately previous major version.

Patches are considered full versions of the app, meaning that they are defined by a setup script exactly in the same manner as a major version. Unlike full version upgrades, however, there are no restrictions on the order in which the provider can install them nor on how many patches can have code running at the same time.

Multiple patches can be added to a given version. Unlike versions, there is nothing restricting the installation of a patch on the currently installed version. This means that it is possible for code to be running simultaneously from multiple different patches when installed in rapid succession. This also means a new version needs to be compatible with all possible running patches from the previous version.

Adding a Version to an Application Package¶

The following example shows how to use the ALTER APPLICATION PACKAGE command to add a version to an application package.

ALTER APPLICATION PACKAGE MyAppPackage
  ADD VERSION v1_0
  USING '@dev_stage/v1_0'
  LABEL = 'MyApp Version 1.0';

In this example, v1_0 is an identifier for the version that is not visible to consumers when they install the application. The consumer sees version information as defined in the LABEL clause.

Only two versions of an application can exist at the same time. For example, if you define v1_0 and v1_1 in an application, you must drop v1_0 in order to create v1_2. However, you can have multiple patches for a single version.

You can define the version name and label in the manifest.yml file, or specify them directly with the ALTER APPLICATION PACKAGE command. If you define them in the manifest.yml file as well as with the SQL command, the values specified in the SQL command take precedence over the values specified in the manifest.yml file.

Adding a Patch to an Application Package¶

In addition to creating versions for an app you can also create patches for a specific version. Like versions, app patches also have their own application files.

To create a new patch for an application package, use the ADD PATCH FOR VERSION clause of the ALTER APPLICATION PACKAGE command, as shown in the following example:

ALTER APPLICATION PACKAGE MyAppPackage ADD PATCH
 FOR VERSION V1_0
 USING '@dev_stage/v1_0_p1;

When you add the first version to an application package, this version is assigned patch 0. As you add additional patches, Snowflake increments the patch number by 1.

Viewing the Versions and Patches for an Application Package¶

As a provider, you can view the versions and patches defined for an application by running the SHOW VERSIONS command on the application package.

The following command displays the versions and patches that have been defined for an application package named HelloSnowflakePackage:

SHOW VERSIONS IN APPLICATION PACKAGE HelloSnowflakePackage;

Removing a Version from an Application Package¶

To remove a version from an application package, use the DROP VERSION clause of the ALTER APPLICATION PACKAGE command as shown in the following example:

ALTER APPLICATION PACKAGE HelloSnowflakePackage
  DROP VERSION v1_0;

About Release Directives¶

You can set a default release directive for an application package. The default release directive specifies the version that is applicable to all consumers when installing an application. For example if you have created a V1 and V2 of an application, setting the default release directive to V2 ensures that when a consumer installs the application, they install the v2 version.

You can also add a custom release directive to an application package. Custom release directives allow you to specify the version of an application that specific Snowflake accounts can install.

For example, if you create V2 and V3 of an application, you can assign V2 to be the default release and create a custom release directive to share V3 with specific accounts. One common use case for custom release directives is to share an application with the consumer account you use for testing.

You must define a release directive for an application package to be able to do the following:

• Install an application in the consumer account.

• Create a private listing for an application package.

Privileges Required to Set the Release Directive¶

Specifying release directives requires the MANAGE RELEASES privilege or ownership of the application package.

GRANT MANAGE RELEASES ON APPLICATION PACKAGE HelloSnowflakePackage
  TO ROLE release_mgr;

Setting the Default Release Directive for an Application Package¶

Use the ALTER APPLICATION PACKAGE command with SET DEFAULT RELEASE DIRECTIVE to set the default release directive as shown in the following example:

ALTER APPLICATION PACKAGE HelloSnowflakePackage
  SET DEFAULT RELEASE DIRECTIVE
  VERSION = v1_0
  PATCH = 2;

To update the default release directive for an application package, run the ALTER APPLICATION PACKAGE command with SET DEFAULT RELEASE DIRECTIVE again, specifying new values for VERSION and PATCH.

Adding a Custom Release Directive to an Application Package¶

To add a custom release directive, use the ALTER APPLICATION PACKAGE command with SET RELEASE DIRECTIVE. Use the ACCOUNTS clause to specify the accounts to which this release directive applies. For example:

ALTER APPLICATION PACKAGE HelloSnowflakePackage
  SET RELEASE DIRECTIVE HelloSnowflakePackage_Custom
  ACCOUNTS = (CONSUMER_ORG.CONSUMER_ACCOUNT)
  VERSION = v1_0
  PATCH = 0;

After adding a custom release directive to an application package, you can update the version and patch for the release directive by running the ALTER APPLICATION PACKAGE with MODIFY RELEASE DIRECTIVE and specifying updated values for VERSION and PATCH.

However, you cannot modify the accounts associated with the release directive. To change the organization and account associated with a release directive do the following:

1. Remove the release directive from the application package by running the ALTER APPLICATION PACKAGE command with UNSET RELEASE DIRECTIVE.

2. Add the release directive back to the application package by running the ALTER APPLICATION PACKAGE command with SET RELEASE DIRECTIVE and using the ACCOUNTS clause to specify the list of accounts.

Updating a Custom Release Directive in an Application Package¶

To update the version or patch for a custom release directive, use the ALTER APPLICATION PACKAGE command with MODIFY RELEASE DIRECTIVE as shown in the following example:

ALTER APPLICATION PACKAGE HelloSnowflakePackage
  MODIFY RELEASE DIRECTIVE HelloSnowflakePackage_Custom
  VERSION = v1_0
  PATCH = 0;

Removing a Custom Release Directive from an Application Package¶

To remove a custom release directive from an application package, use the ALTER APPLICATION PACKAGE command with UNSET RELEASE DIRECTIVE as shown in the following example:

ALTER APPLICATION PACKAGE HelloSnowflakePackage
  UNSET RELEASE DIRECTIVE HelloSnowflakePackage_Custom;

Releasing Versions and Patches¶

When installing an application from an application package in development mode, the version and patch are explicitly specified. However, when the application is installed normally, such as:

CREATE APPLICATION HelloSnowflake
  FROM APPLICATION PACKAGE HelloSnowflakePackage

The release directive determines the version that is installed when running this command.