Versioning, Patching, and Upgrading an Application

This topic describes how to add versions and patches to an application created using the Native Apps Framework. This topic also describes how to use versioned schema to ensure seamless upgrade of the the application files and and setup script of your application.

About Versions, Patches and Upgrades

The Native Framework provides functionality that allows you to update your application or fix problems. It also provides a way to seamlessly upgrade an application after it is installed in a consumer account.

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.

Creating Versions and Patches

Version information for an application is specified in the application package.

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

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

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.

Note

You cannot specify the patch number yourself. Snowflake manages the patch numbers internally.

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

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

Note

Dropping a version that is currently being used by an installed application might cause that version to become unusable until the installed application is upgraded.

This command does not complete until all applications are upgraded to a new version. Take care when dropping a version that is current in use in a consumer account.

Setting the Release Directive for an Application Package

After adding a versions to an application package, you can specify release directive for the application package. Release directives determine the version of the application that is available to a consumer when they install the application.

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.

Note

If you specify both a default and custom release directive, the custom release directive always takes precedence. In the example above, consumer accounts specified in the custom release directive would only be able to install v3 of the application.

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

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

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

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

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

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
Copy

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