To share your application with consumers, create a listing for your application package.

Creating a Private Listing for an Application Package

To present your application package exclusively to specific consumers, follow these steps to create a listing:

Log in to Snowsight.

Navigate to Data » Provider Studio in the left navigation bar.

Click on + Listing, opening the Create Listing window.

Provide a name for your listing.

In the "Who can discover the listing" section, choose "Only specified consumers" to privately share the listing with specific accounts.

Click on + Select to choose the application package to include in the listing.

Add a description for your listing.

(Optional) If you have multiple provider profiles, select the one to use for publishing this listing.

In the "Add consumer accounts" section, input the account identifiers for the consumers you wish to share the listing with.

If the consumer accounts are in a different region, set up auto-fulfillment:

Review the refresh frequency configured at the account level. Adjust if needed; refer to Set Account-Level Refresh Frequency.
Optionally, choose a warehouse for auto-fulfillment.
Click on "Publish" to publish the listing to the selected consumers, or choose "Save Draft" to save it as a draft.

To monetize your application, incorporate a pricing plan to receive payment for your application.

Accessible to accounts in all AWS regions outside of government instances. For information on support for other cloud platforms, please reach out to your Snowflake representative.

Following the development and testing of the application package containing your application, you can make the application available to consumers through listings.

As a provider, you incorporate an application package as the data content of a listing. Subsequently, consumers install the application in their account directly from the listing.

Set Up Roles and Privileges:

When initiating the creation of a listing, it must be done from the account containing the data or application package. The role responsible for attaching a data product to a listing and publishing the listing should align with the role that initially created and owns the application package or share. The transfer of the OWNERSHIP privilege for a share is not supported.

In cases where a different role is used to create and manage the listing, it is advisable to grant the MODIFY privilege on the listing to the role that possesses ownership of the application package or share. For instance:

Role of the share or application package owner:

OWNERSHIP privilege on the share or application package.
MODIFY privilege on the listing.

Prerequisites for Publishing a Listing for an Application Package

Prior to generating a listing for an application package, make sure to accomplish the following:

Develop and thoroughly test your application package.
Before publishing, verify the correct functionality of your application package and ensure that roles and privileges are appropriately configured.
To streamline the process of sharing applications from your account to other Snowflake accounts, it is recommended to become a provider of listings in Snowflake. Refer to the guide on Becoming a Provider of Listings for details.

Note: Creating a provider profile is not mandatory for private listings.

This section details the process of incorporating application logic into the setup script of an application package. Additionally, it provides guidance on integrating external code files into an application package.

For information specifically related to including a Streamlit app in an application package, refer to the documentation on Adding a Streamlit App to an Application Package.

Considerations for Using Stored Procedures and Functions:

Within the Snowflake Native App Framework, you have the capability to incorporate stored procedures, user-defined functions (UDFs), and external functions into an application package. These components can be authored in any of the languages supported by Snowflake.

Adding Application Code Securely:

All stored procedures and user-defined functions (UDFs) within a Snowflake Native App operate under the context of the application, possessing access to all objects within the installed Snowflake Native App. This scenario poses a risk of SQL injection attacks.

When creating procedures and functions intended for use within a Snowflake Native App, it is advised to follow best practices by utilizing bound parameters for all SQL commands that involve user input. This precaution applies to input received through procedure arguments.

For further details, refer to the documentation on Creating a Stored Procedure.

Users possessing the OWNERSHIP privilege for an application package can detach it from an account. However, it's important to note that removing an application package associated with a listing is not permitted.

Once an application package is removed, it becomes inaccessible within the provider account.

Note:
Following the removal of both a listing and the associated application package, consumers can view but cannot access the Snowflake Native App generated from that application package. Attempting to access the Snowflake Native App results in an error indicating the removal of the application package.

Removing an application package can be done either through Snowsight or by utilizing SQL commands.

Removing an Application Package Using Snowsight:
To remove an application package using Snowsight, adhere to the following steps:

Sign in to Snowsight.
In the left navigation bar, navigate to Apps, and then select Packages.
Choose the ellipsis (...) next to the desired application package, then select Drop.

Removing an Application Package Using SQL Commands:
To remove an application package using SQL, execute the DROP APPLICATION PACKAGE command, as illustrated in the following example:

DROP APPLICATION PACKAGE HelloSnowflakePackage;

After creating an application package, you have the option to transfer ownership of the application package to another account-level role.

Transferring Ownership Using Snowsight:
To transfer ownership of an application package via Snowsight, follow these steps:

1. Sign in to Snowsight.
2. In the left navigation bar, navigate to Apps and then select Packages.
3. Choose the ellipsis (...) next to the application package you wish to transfer, then select Transfer Ownership.
4. Under Transfer to, choose the new account-level role.
5. Click on Transfer.

Transferring Ownership Using SQL Commands:
To transfer ownership of an application package to a different account-level role using SQL, utilize the GRANT OWNERSHIP command, as illustrated in the following example:
GRANT OWNERSHIP ON APPLICATION HelloSnowflakePackage TO ROLE native_app_dev;

To generate an application package using SQL, employ the CREATE APPLICATION PACKAGE command, exemplified in the following instance:

CREATE APPLICATION PACKAGE HelloSnowflakePackage;

After creating an application package, use the SHOW APPLICATION PACKAGES command to view the list of available application packages.

Granting Privileges on an Application Package:

Certain tasks associated with the development of an application package necessitate specific privileges assigned to the application package. The following table outlines the privileges required for performing these tasks:

Privilege Task
ATTACH LISTING Add an application package to a listing.
DEVELOP Create an APPLICATION object in development mode from the application package.
INSTALL Create an APPLICATION object based on the application package.
MANAGE RELEASES Specify a release directive, view the version and patch level.
MANAGE VERSIONS Add a version and patch level to an application package.
OWNERSHIP Perform all tasks mentioned above.

Granting Privileges on an Application Package Using Snowsight:

To configure privileges for an application package using Snowsight, follow these steps:

1. Log in to Snowsight.

2. In the left navigation bar, go to Apps and then select Packages.

3. Choose the desired application package, and click on the Settings tab.

4. Within the Privileges section, click the edit icon next to the privilege you wish to grant.

5. Click on Add Role, and then select the role to which you want to grant the privilege.

6. Save your changes.

The assigned role will now be displayed next to the granted privilege.

Granting privileges on an application package to a role using SQL commands:
It involves using the GRANT command, illustrated in the following example:

GRANT MANAGE RELEASES ON APPLICATION PACKAGE HelloSnowflakePackage TO ROLE app_release_mgr;

This command bestows the MANAGE RELEASES privilege upon the app_release_mgr role. You can employ the identical command to confer other available privileges on an application package.

To generate an application package using Snowsight, follow these steps:

1. Log in to Snowsight.

2. Navigate to the left-hand menu, choose 'Apps,' and then click on 'Packages.'

3. Click on 'Create' followed by 'App Package.'

4. Provide a name for your application package.

5. Choose the target audience for the application package:

- Select 'Consumers outside of your organization' to make it accessible externally. This choice triggers an automated security scan for each version and patch.

- Choose 'Consumers within your organization' to limit availability within your organization. No automated security scan is initiated for this option.

6. Optionally, add comments for the application package. Note that these comments won't be visible to consumers.

7. Click 'Create.'

The Snowflake Native App Framework provides the flexibility to create an application package either through Snowsight or by executing SQL commands.

Privileges Required for Application Package Creation:
To create an application package, your role must be granted the global privilege of CREATE APPLICATION PACKAGE.

Uploading the Manifest File and Setup Script to a Named Stage:
Before crafting an application package, it is essential to generate the manifest file and setup script, and subsequently, upload them to a named stage accessible to your account.

There are two methods for file upload to a named stage:

Using Snowsight: For detailed instructions, refer to the guide on Staging Files Using Snowsight.

Using the PUT Command.

This topic describes how to create and manage an application package with the Snowflake Native App Framework.

About Application Packages:
An application package serves as a comprehensive container, encompassing the data content, application logic, metadata, and setup script essential for an application's functionality. Additionally, it includes details about the defined versions and patch levels associated with the application.

The following example shows a typical manifest file with values specified for all supported properties:

manifest_version: 1 # required
version:
name: hello_snowflake
label: "v1.0"
comment: "The first version of a Snowflake Native App"

artifacts:
readme: readme.md
setup_script: scripts/setup.sql
default_streamlit: streamlit/ux_schema.homepage_streamlit
extension_code: true

configuration:
log_level: debug
trace_level: always

privileges:
- EXECUTE TASK:
description: "Run ingestion tasks for replicating Redshift data"
- EXECUTE MANAGED TASK:
description: "To run serverless ingestion tasks for replicating Redshift data"
- CREATE WAREHOUSE:
description: "To create warehouses for executing tasks"
- MANAGE WAREHOUSES:
description: "To manage warehouses for optimizing the efficiency of your accounts"
- CREATE DATABASE:
description: "To create sink databases for replicating Redshift data"
- IMPORTED PRIVILEGES ON SNOWFLAKE DB:
description: "To access account_usage views"

references:
- enrichment_table:
label: "Enrichment Table"
description: "Select table with audience data to enrich with Ramp IDs"
privileges:
- SELECT
- INSERT
- UPDATE
object_type: Table
multi_valued: true
register_callback: config.register_reference

The manifest.yml file can contain the following valid properties:

manifest_version:

Specifies the version of the manifest file.
Required
version:

Defines a block containing parameters related to a version.

Optional

name:
Specifies the logical name of the version.
label:
Displays a name for the version to consumers.
comment:
Provides a comment visible to providers using the SHOW VERSIONS command.
artifacts:

Defines a block related to resources distributed from this version of the package.
Required
readme:

Specifies the path to a markdown readme file, offering an overview of the Snowflake Native App.
Required
setup_script:

Specifies the path and filename of the SQL script run during installation.
Optional
default_streamlit:

Specifies the schema and name of the default Streamlit app for Snowflake Native Apps that include Streamlit.
Required if Streamlit is included; Optional otherwise.
extension_code:

Specifies if the Snowflake Native App can run UDFs and stored procedures.
Optional
configuration:

Defines a block containing configuration properties for the Snowflake Native App.

Optional

log_level:
Specifies the logging level (Default: Off).
trace_level:
Specifies the trace event level (Default: Off).
privileges:

Defines the privileges that the consumer must grant during installation.

Optional; Default: Empty list

:

Specifies the name of the privilege.
description:
Describes the privilege for consumer understanding.
references:

Defines a block containing references defined by the provider.

Optional

- :

Specifies the name of the reference.
label:
Describes the reference for consumer viewing.
privileges:
Specifies the required privileges for the reference.
object_type:
Specifies the type of associated object.
multi_valued:
Specifies if more than one object is associated (Optional; Default: false).
register_callback:
Specifies the callback function used for the reference.
Required if references is specified.

About the Manifest File:

The Snowflake Native App Framework mandates the inclusion of a manifest file in each application package. This file delineates essential properties for the application package, such as the setup script's location and version definitions.

Key requirements for the manifest file are as follows:

The manifest file must be named manifest.yml.
It should be uploaded to a specifically named stage, ensuring accessibility during the creation of an application package or Snowflake Native App.
The manifest file must be positioned at the root of the directory structure within the designated stage.

Application roles lack versioning. Consequently, removing an application role or withdrawing a permission from an object situated outside a versioned schema can potentially affect the existing version of an application or the version undergoing an upgrade. It is advisable to drop application roles only when all versions of the application utilizing those roles have been successfully removed.

Application roles established within the setup script are automatically conferred upon the role that possesses the application instance. Upon installation, the role employed to install the application assumes the ownership of that application. Nevertheless, the application owner retains the authority to extend privileges to other account roles within the consumer account.

These application roles serve as a means to impart privileges on objects within the application, thereby enabling the conferment of privileges to the consumer.

For example:
CREATE APPLICATION ROLE admin;
CREATE APPLICATION ROLE user;
GRANT APPLICATION ROLE user TO APPLICATION ROLE admin;

CREATE OR ALTER VERSIONED SCHEMA app_code;
GRANT USAGE ON SCHEMA app_code TO APPLICATION ROLE admin;
GRANT USAGE ON SCHEMA app_code TO APPLICATION ROLE user;
CREATE OR REPLACE PROCEDURE app_code.config_app(...)
GRANT USAGE ON PROCEDURE app_code.config_app(..)
TO APPLICATION ROLE admin;

CREATE OR REPLACE FUNCTION app_code.add(x INT, y INT)
GRANT USAGE ON FUNCTION app_code.add(INT, INT)
TO APPLICATION ROLE admin;
GRANT USAGE ON FUNCTION app_code.add(INT, INT)
TO APPLICATION ROLE user;

In this illustration, the setup script initiates the creation of application roles, specifically 'admin' and 'user.' Subsequently, both application roles are endowed with access to the schema housing the application code. Additionally, access to the 'add' function within the schema is granted to both roles. Furthermore, exclusive access to the 'config_app' procedure is extended to the 'admin' role.

Snowflake recommends adhering to the following best practices when crafting the setup script for an application:

When employing the CREATE command to generate objects within the setup script, it is advisable to use the CREATE OR REPLACE or CREATE IF NOT EXISTS variations of the commands. The setup script might be executed multiple times during installation, upgrades, or error recovery scenarios, such as in cases where a versioned schema may not be empty.
sql
Copy code
-- Example of creating a schema within the setup script
CREATE SCHEMA IF NOT EXISTS app_config;
CREATE TABLE IF NOT EXISTS app_config.params(...);
As the CREATE SCHEMA command doesn't alter the session context, objects must be qualified with the target schema when created. Considerations should be given to potential failures during the setup script execution. Since the script is designed to be idempotent, it automatically reruns if the initial execution encounters an error.

Take into account the implications when granting permissions to application roles within a schema. Utilize the CREATE OR REPLACE statement carefully, especially with procedures, as it replaces the procedure, implicitly removing prior grants. Although grants are restored later in the script, a script failure during execution might temporarily revoke consumer access to the procedure.

sql
Copy code
-- Example of creating or replacing a procedure and granting usage to an application role
CREATE OR REPLACE PROCEDURE app_state.proc()...;
-- Additional CREATE statements
GRANT USAGE ON PROCEDURE app_state.proc()
TO APPLICATION ROLE app_user;
Views on shared content should always be defined in a versioned schema. This ensures that any code accessing the view during an upgrade maintains a consistent view, even if new columns or other attributes are added or removed.

If the setup script necessitates prolonged operations, such as upgrading large state tables, ensure that these updates are compatible with existing running code from the previous version.

These best practices help optimize the robustness and reliability of the setup script throughout the application's lifecycle.

Snowflake recommends adhering to the following best practices when crafting the setup script for an application:

When employing the CREATE command to generate objects within the setup script, it is advisable to use the CREATE OR REPLACE or CREATE IF NOT EXISTS variations of the commands. The setup script might be executed multiple times during installation, upgrades, or error recovery scenarios, such as in cases where a versioned schema may not be empty.
sql
Copy code
-- Example of creating a schema within the setup script
CREATE SCHEMA IF NOT EXISTS app_config;
CREATE TABLE IF NOT EXISTS app_config.params(...);
As the CREATE SCHEMA command doesn't alter the session context, objects must be qualified with the target schema when created. Considerations should be given to potential failures during the setup script execution. Since the script is designed to be idempotent, it automatically reruns if the initial execution encounters an error.

Take into account the implications when granting permissions to application roles within a schema. Utilize the CREATE OR REPLACE statement carefully, especially with procedures, as it replaces the procedure, implicitly removing prior grants. Although grants are restored later in the script, a script failure during execution might temporarily revoke consumer access to the procedure.

sql
Copy code
-- Example of creating or replacing a procedure and granting usage to an application role
CREATE OR REPLACE PROCEDURE app_state.proc()...;
-- Additional CREATE statements
GRANT USAGE ON PROCEDURE app_state.proc()
TO APPLICATION ROLE app_user;
Views on shared content should always be defined in a versioned schema. This ensures that any code accessing the view during an upgrade maintains a consistent view, even if new columns or other attributes are added or removed.

If the setup script necessitates prolonged operations, such as upgrading large state tables, ensure that these updates are compatible with existing running code from the previous version.

These best practices help optimize the robustness and reliability of the setup script throughout the application's lifecycle.

The setup script has the capability to define a wide range of database-level objects. Notably, the database objects created by the setup script are internal to the application, remaining invisible and inaccessible to the consumer account directly.

To grant visibility and access to these objects for consumers, application roles come into play. Any application role established within the setup script is automatically bestowed upon the role that owns the instance of the installed application. It's crucial to note that these roles cannot be revoked.

Users possessing the role that owns the application instance can then extend these application roles to other roles within their organization. For instance, the setup script may define an application role, such as APP_ADMIN, which is granted permission to access objects within the application. Subsequently, users with this role can leverage these objects for administering the application.

Additionally, the setup script can introduce an application role (e.g., USER) to provide consumers with access to the application's functionality. Furthermore, it can define roles like READ_ONLY, offering restricted access to specific data areas within the application.

The setup script serves a dual purpose, catering to both the initial installation and subsequent upgrades. It is imperative for the script to be composed in an idempotent manner. For instance, object creation can utilize statements such as CREATE .. IF NOT EXISTS or CREATE OR REPLACE.

This section guides utilizing the setup script to define the objects created during the installation of your application. Additionally, it delves into the utilization of application roles and their integration within the setup script.

About the Setup Script:

Within the application, the setup script comprises SQL statements executed during the installation, upgrade, or testing phases. It is imperative for every application to include a setup script, with its location explicitly detailed in the manifest file.

The setup script serves to articulate the creation and modification of objects during the installation or upgrade of an application.

Note:
The setup script is an essential component for generating an application package. Both the name and path of the setup script are specified in the manifest.yml file.

Restrictions on the Setup Script:

The operations listed below are restricted and cannot be executed within a setup script:

- USE DATABASE
- USE SCHEMA
- USE ROLE
- USE SECONDARY ROLES
- Configuring the LOG_LEVEL or TRACE_LEVEL properties using the ALTER command.
- Creating or invoking procedures set to EXECUTE AS CALLER.
- Developing Snowpark user-defined functions (UDFs) or procedures utilizing IMPORT from a designated stage.
- Invoking procedures, functions, or anonymous code blocks incorporating extension code.
- Importing code files from a named stage when utilizing the CREATE FUNCTION command.
- Employing CALL to invoke a procedure configured with EXECUTE AS CALLER.

It's important to note that there are additional constraints on objects created within a versioned schema.

Upon a provider's successful publication of a listing, featuring an application package, consumers gain the ability to explore the listing and seamlessly install the application.

Snowflake Native App:
A Snowflake Native App represents a database object established within the consumer account. When a consumer initiates the installation of the Snowflake Native App, Snowflake dynamically generates the application and executes the setup script, thereby creating the necessary objects within the application. Refer to the documentation on Creating and Testing an APPLICATION Object for in-depth details.

Following the installation of the application, consumers can undertake additional tasks, including:

Activating logging and event sharing features to aid providers in troubleshooting the application.

Granting the necessary privileges as required by the application.

In order to share both data content and application logic with a consumer, providers initiate the creation of an application package.

Application Package:
This comprehensive package encompasses the data content, application logic, metadata, and setup script essential for the application's functionality. Additionally, it incorporates information about versions and patch levels specific to the application. For a detailed guide on creating an application package, please refer to the documentation on Creating an Application Package.

Within an application package, providers can include references to data content and external code files they wish to integrate into the application. Notably, an application package necessitates both a manifest file and a setup script.

Manifest File:
This file outlines the configuration and setup properties essential for the application, such as the location of the setup script and version details. For a thorough understanding of creating the manifest file, consult the documentation on Creating the Manifest File.

Setup Script:
Containing SQL statements, the setup script executes when a consumer installs or upgrades an application, or when a provider installs or upgrades an application for testing. The manifest.yml file specifies the location of the setup script. For comprehensive guidance on creating the setup script, refer to the documentation on Creating the Setup Script.