Update and upgrade a Snowflake Native App¶

Differences between versions and patches¶

When a provider publishes a new version of an app, the Snowflake Native App Framework ensures that only the previous version of the app is active. For example, if a provider has published V1 and V2 of an app, the Snowflake Native App Framework ensures that only V2 is currently installed in a consumer account before upgrading to V3. This ensures that the setup script only has to account for differences between V2 and V3. In other words, the setup script is only backwards compatible with the most recent version of the app. If a provider makes a state change to the app, for example creating a new table or adding columns to a table, there are no compatibility issues between versions.

In contrast, when a provider publishes a new patch for a version of an app, the Snowflake Native App Framework does not enforce any restrictions on the number of active patches running. Providers must avoid making changes to the state of an app in a patch.

About upgrades across regions¶

See Upgrade an installed app across multiple regions for information on upgrading an installed app across regions.

Privileges required to add or remove versions and patches¶

To specify a version or patch for an application package, you must have one of the following privileges granted on the application package to your role:

• OWNERSHIP

• MANAGE VERSIONS

For example, to grant the MANAGE VERSION privilege on the application package to the release_mgr role, use the GRANT <privileges> command as shown in the following example:

GRANT MANAGE VERSIONS ON APPLICATION PACKAGE hello_snowflake_package
  TO ROLE release_mgr;

Add a version to an application package by using SQL¶

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.

Add a patch to an application package by using SQL¶

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 … VERSION command, as shown in the following example:

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

In the example, no patch number is provided to the ADD PATCH FOR VERSION V1_0 clause. In this case Snowflake automatically increments the patch number by 1.

To create a new patch for an application with a custom patch number, provide a patch number to the ADD PATCH FOR VERSION clause of the ALTER APPLICATION PACKAGE … VERSION command, as shown in the following example:

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

View 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 hello_snowflake_package:

SHOW VERSIONS IN APPLICATION PACKAGE hello_snowflake_package;

Remove a version from an application package¶

To remove a version from an application package, you must verify that there are no release directives currently pointing that the version you want to remove.

To view the release directives specified in an application package, run the SHOW RELEASE DIRECTIVES command as shown in the following example:

SHOW RELEASE DIRECTIVES IN APPLICATION PACKAGE hello_snowflake_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 hello_snowflake_package
  DROP VERSION v1_0;

After running this command the version is not dropped until all installed instances of the app are dropped. To verify the the status of the drop command, use the SHOW VERSIONS as shown in the following example:

SHOW VERSIONS IN APPLICATION PACKAGE hello_snowflake_package;

The dropped_on column lists the timestamp when the drop was initiated.

When a version is dropped, consumers can no longer install new instances of that version of the app.

Depending on how the application is published to consumers, it can take different amounts of time for the version to be dropped:

• If the application package has not been published to consumers, the version is dropped immediately.

• If the application package has been published as a public or private listing within a single region, the version is dropped immediately.

• If the application package is published as the data product of a listing shared within the same region as the application package, the version is dropped within a few hours.

• If the application package is published as the data product of a listing using Cross-Cloud Auto-Fulfillment, it may take longer for the version to be dropped across all regions.

Privileges required to set the release directive¶

To set a release directive, a provider must have the MANAGE RELEASES privilege or ownership of the application package.

GRANT MANAGE RELEASES ON APPLICATION PACKAGE hello_snowflake_package
  TO ROLE release_mgr;

Set 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 hello_snowflake_package
  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 or PATCH, as appropriate.

Set a custom release directive for 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 hello_snowflake_package
  SET RELEASE DIRECTIVE hello_snowflake_package_custom
  ACCOUNTS = (CONSUMER_ORG.CONSUMER_ACCOUNT)
  VERSION = v1_0
  PATCH = 0;

Update a custom release directive¶

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 hello_snowflake_package
  MODIFY RELEASE DIRECTIVE hello_snowflake_package_custom
  VERSION = v1_0
  PATCH = 0;

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.

Remove a custom release directive¶

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 hello_snowflake_package
  UNSET RELEASE DIRECTIVE hello_snowflake_package_custom;

Test a version and patch using a release directive¶

When installing an application from an application package in development mode, the version and patch are explicitly specified. However, when the application is installed using the following command:

CREATE APPLICATION hello_snowflake
  FROM APPLICATION PACKAGE hello_snowflake_package

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

Workflow for upgrading an Snowflake Native App¶

A provider upgrades an installed app by using the following workflow:

1. Update the application logic and setup script of the application package.

2. If there are two versions currently defined, remove a version from the application package.

3. Create a new version or patch for the changes in the application package.

   If the DISTRIBUTION property of the application is set to EXTERNAL, the automated security scan is initiated. The security scan must pass before the upgrade can occur.

4. Test the new version by creating an APPLICATION object in the provider’s test account.

5. Update the release directive for the version or patch.

   This initiates an automated upgrade that will update all installed instances of the previous version. A provider can notify the consumer that an upgrade is available and ask them to perform manually perform a manual upgrade.

Upgrade an installed app across multiple regions¶

If a provider publishes a Snowflake Native App using Cross-Cloud Auto-Fulfillment, automated upgrades may take a while to upgrade depending on the following factors:

• The value of the refresh schedule.

• The number of installed instances of the app.

• The number of regions where the app is deployed.

If the upgrade contains an urgent fix that needs to be upgraded in a remote region, providers can consider the following ways to perform an upgrade faster:

• Reduce the refresh frequency of the listing to a smaller value.

  Note

  Reducing the refresh frequency can increase the costs associated with replication. See Configuring Cross-Cloud Auto-Fulfillment for more information.

• Ask the consumer to perform a manual upgrade.

Perform a manual upgrade for an installed app¶

Manual upgrades allow a consumer to initiate the upgrade of an installed version or patch of an app using the release directive specified in the application package.

To upgrade an installed Snowflake Native App to the latest available version, a consumer can use the UPGRADE clause of the ALTER APPLICATION command to modify the application object:

ALTER APPLICATION <name> UPGRADE

View the status of an upgrade¶

To view the upgrade state of a app, use the APPLICATION_STATE View system view as shown in the following example:

SELECT * FROM snowflake.data_sharing_usage.APPLICATION_STATE

This view includes columns that are specific to upgrades, including the upgrade state and the region where the app is deployed.