Overview of app versions and upgrades¶

About app versions and patches¶

The Snowflake Native App Framework allows providers to create versions and patches of an app. Versions and patches allow providers to release new functionality and updates to consumers.

Version

Generally contains major updates to a Snowflake Native App. Versions generally introduce new features and changed functionality for an app.

Patch

Generally contains smaller updates to a Snowflake Native App. Unlike versions, patches should only contain small updates such as security fixes.

The versions and patches of an app are specified in the application package.

To add a new version to an application package that currently has two versions defined, providers must remove one of the existing versions. To remove a version, a provider must:

1. Ensure that all consumers have upgraded off the version to be removed.

2. Remove the version from the application package.

3. Create a new version.

4. Upgrade the app.

Although an application package can only contain two active versions at one time, a single version can have multiple patches. The Snowflake Native App Framework does not support dropping patches. When a provider adds a new version to an application package, the new version is automatically assigned patch 0 by default. This cannot be changed.

When a provider adds a new patch to a version, they can manually specify the identifier for the patch. If no patch number is provided, Snowflake automatically increments the patch version by 1.

Stateful and stateless objects¶

When developing a new version of an app, providers must consider if the components they are modifying need to preserve their state from one version or patch to another. A typical app contains two types of components:

Stateless objects

Stateless objects are recreated for each new version or patch of the app. Stateless objects only need to be available for the lifetime of the version and can be recreated as necessary. Stateless objects are typically the code of the app, including stored procedures, user-defined functions, Streamlit apps, and similar content.

Stateless objects should be created in a versioned schema.

Stateful objects

Stateful objects are shared from one version or patch of the app to another. Stateful components are intended to have a lifetime across multiple versions of the app. For example, if an app uses a table to store configuration information within the consumer account, the contents of this table would need to be preserved during upgrade.

Stateful objects should be created using a regular schema.

About versioned schemas¶

When writing the setup script for the new version of the app, providers must account for stateless and stateful components. To handle stateless objects the Snowflake Native App Framework provides a special type of database schema referred to as versioned schemas. A versioned schema is similar to a regular database schema with added functionality to handle multiple versions of objects created by different app versions.

See Use versioned schema to manage app objects across versions for more information.

About app upgrades¶

The Snowflake Native App Framework allows providers to upgrade an app to a new version or patch. To see how upgrades fit in the overall workflow for developing a new version or patch of an app, see Workflow for updating an app.

Providers can initiate an upgrade of an app to a new version or patch by setting a release directive on the application package. When the release directive is modified, Snowflake automatically upgrades all installed instances of the current version of the app to the version specified by the release directive.

When the provider initiates an upgrade, Snowflake adds each app to be upgraded to a queue. Each app is upgraded as resources are available. The upgrade process can take a while to complete across all installed versions of the app. To expedite the upgrade process, consumers can also manually initiate an upgrade of an app when a new version or patch is available.

For more information, see Upgrade an app.

Lifecycle of app version and patches¶

To understand how app versions and patches work together, consider a scenario where a provider has published an initial version, v1, of an app and consumer A and consumer B have installed that version of the app in their accounts.

This scenario is shown in the following sections.

Version v1.0 is installed in the consumer account¶

Figure 1 shows version v1.0 of an app that a provider published and two consumers have installed the app in their accounts:

This figure shows the following:

• The application files for v1.0 are stored in a stage.

• The release directive of the application package is set to v1.0.

• Consumers have installed v1.0 in their account.

• The provider has begun development of version v2.0 in their account.

Add version v2.0 to the application package¶

Figure 2 shows that the provider has uploaded version v2.0 and created a new version in the application package:

This figures shows the following:

• After testing version v2.0 of the app locally, the provider uploads the v2.0 file to the stage

• The provider creates a new version for the app in the application package.

• The release directive continues to point to version v1.0 of the app.

• Consumers continue to have version v1.0 installed in their account.

Upgrade the app from version v1.0 to version v2.0¶

To perform an upgrade from version v1.0 to version v2.0 of the app, the provider sets the release directive of the application package to version v2.0. This starts the process of upgrading the app in the consumer accounts.

After the upgrade completes, both consumers A and B have version v2.0 installed in their accounts as shown in the Figure 3 diagram.

Also, in this scenario the provider has begun developing and testing version v3.0 in their local development environment.

Drop version v1.0 to be able to create v3.0¶

When testing is complete, the provider uploads version v3.0 to the stage. When the provider wants to begin the upgrade to version v3.0, they must first ensure that all consumers have migrated off of version v1.0.

In the scenario shown in the previous section, all consumers are currently on v2.0.

The provider must drop version v1.0 from the application package as shown in Figure 4:

Add version v3.0 to the application package¶

After dropping version v1.0, the provider can then add version v3.0 to the application package. In this context, the release directive is still pointing to v2.0 and consumers have v2.0 installed in their account.

Upgrade to version v3.0¶

To upgrade to v3.0, the provider updates the release directive to point to v3.0. This begins the upgrade. When the upgrade is complete, consumers are upgraded to version v3.0 as shown in the following figure: