Native App Package Anatomy: Manifest, Setup Script and Versioned Schemas

1.The application package and its manifest

An application package is the provider-side container for a Snowflake Native App. It holds the app's data content and application logic, plus the versions and patches defined for the app. Each version needs two files of its own: a manifest file and a setup script. You can create the package before either file exists, but you cannot develop or test the app until both are uploaded to a stage the package can read.

The manifest has strict placement rules. The file must be named manifest.yml, it must be uploaded to a named stage, and it must sit at the root of the directory structure on that stage, next to the other application files. The manifest gives the location of the setup script, defines the version, and holds configuration for the app. Under artifacts it lists things such as the readme, the setup script and, for apps with containers, the container images. Under privileges it lists what the app asks the consumer for.

manifest_version: 2
version:
  name: v1
artifacts:
  readme: readme.md
  setup_script: setup.sql
privileges:
  - CREATE TABLE:
    description: "Allows the app to create tables in the consumer account"
  - CREATE WAREHOUSE:
    description: "Allows the app to create warehouses in the consumer account"

The manifest_version field decides which manifest format applies. Version 1 supports the current and legacy functionality of Native Apps. Version 2 adds more features, the main one being automated granting of privileges. In the example above, Snowflake automatically grants CREATE TABLE and CREATE WAREHOUSE when the app is installed. This changes what the consumer is agreeing to. During installation Snowsight shows the requested privileges, and by installing, the consumer accepts that the app can be granted these privileges during later upgrades without being asked again. Consumers who want limits can create feature policies that restrict which objects an app is allowed to create.

A container-based app (Snowpark Container Services) adds its own entries to the same manifest. Its architecture has three parts that the manifest must declare:

- Images. Add an images property under artifacts.container_services, with one entry for each image. Each path names the database, schema and image repository that hold the image. - Compute and network privileges. CREATE COMPUTE POOL lets the app create a compute pool in the consumer account. You do not need it if the consumer creates the pool manually. BIND SERVICE ENDPOINT lets an endpoint be reached from outside Snowflake. These are the compute pool and service endpoint binding requirements. - A user interface endpoint. The optional default_web_endpoint names a service and an endpoint, and that endpoint must also be defined in the service specification file. You can specify only one of default_web_endpoint and default_streamlit.

The manifest reference also requires a grant_callback in the configuration block for an app with containers. It is a stored procedure that can create compute pools, services and perform other setup tasks.

Objects for the containers must not live in a versioned schema. Snowpark Container Services is not supported there, so create the services and compute pools in a regular schema. Setup-script logic that builds them runs inside the consumer's account, which is why the manifest-first approach to sharing content does not apply to them.

privileges:
- CREATE COMPUTE POOL:
  description: 'Required to allow the app to create a compute pool in the consumer account.'
- BIND SERVICE ENDPOINT:
  description: 'Required to allow endpoints to be externally accessible.'

default_web_endpoint:
  service: ux_schema.ux_service
  endpoint: ui

Sources1234

2.The setup script: SQL only, internal by default

The setup script runs when a consumer installs or upgrades the app, and when a provider creates or upgrades an app to test the package. It is SQL only, so no other language is supported for the script itself. It creates everything the app needs: database objects, stored procedures, views and application roles.

Privacy is the default. Database objects created by the setup script are internal to the app, and a consumer cannot see or access them directly unless the provider exposes them, usually through application roles. A table that the provider never grants on stays hidden from the consumer.

Some statements are not allowed in a setup script: USE DATABASE, USE SCHEMA, USE ROLE and USE SECONDARY ROLES. You also cannot create or call procedures that are EXECUTE AS CALLER, or run code that is not included in the application package. Because the session context cannot be switched, every object must be qualified with its schema:

CREATE SCHEMA IF NOT EXISTS app_config;
CREATE TABLE IF NOT EXISTS app_config.params(...);

For large apps, the manifest points to one primary setup script, which pulls in secondary scripts with EXECUTE IMMEDIATE FROM. These run in the order they appear, and the paths are case-sensitive. A leading / means the app root, ./ means the current script's directory, and ../ means its parent. At app runtime, only the / form is allowed. Event logging is not supported in scripts called this way.

The main design rule is that the script must be safe to run again. It can run multiple times during installation and upgrade, for example when a failed run is retried. That is why Snowflake recommends CREATE OR REPLACE or CREATE IF NOT EXISTS. CREATE OR REPLACE has a catch: replacing a procedure silently removes the grants on it. If the script fails before it re-grants, consumers lose access until a new version or patch restores the grant.

Sources5

3.Versioned schemas versus regular schemas

Every app object falls into one of two groups. Stateless objects are the app's code: stored procedures, UDFs, Streamlit apps and similar. They only need to exist for the life of a version and can be recreated each time. Stateful objects, such as a configuration table in the consumer account, must keep their contents across versions.

Versioned schemas exist for the stateless group. A versioned schema works like a regular schema but internally holds a subschema for each app version. That gives version pinning: a query started by a v1 object stays tied to v1 even after an upgrade. Consumers see only the objects for the version they have installed, even in SHOW OBJECTS. Versioned schemas can only be created inside the setup script, within an application object.

This extra machinery means many object types are not compatible with versioned schemas. Snowpark Container Services, tasks, tags, masking policies, and grants or future grants are all unsupported. A versioned schema cannot be cloned or used as a clone target, and it cannot be dropped, because dropping it would remove every version's objects, including ones that older queries are still using.

Sources4

4.Managing schema changes across upgrades

Since every version has its own setup script, each script has to handle a fresh install and an upgrade from the previous version. For versioned schemas, always use CREATE OR ALTER VERSIONED SCHEMA so the schema stays compatible across versions and patches. Objects inside it must be recreated with CREATE OR REPLACE or CREATE IF NOT EXISTS, because each version has its own copies in the schema's subschemas. Objects in versioned and non-versioned schemas can reference each other.

For stateful objects in a regular schema, create them only if they are missing, then apply changes additively. The documented pattern below does both: on a fresh install the CREATE builds the full table, and on an upgrade the ALTER adds the column the older version lacked. Existing data is kept either way.

CREATE SCHEMA IF NOT EXISTS stateful_object;

CREATE TABLE IF NOT EXISTS stateful_object.config (
  config_param STRING,
  config_value STRING,
  default_value STRING,
  modified_on  TIMESTAMP);

ALTER TABLE stateful_object.config
  ADD COLUMN IF NOT EXISTS modified_on TIMESTAMP;

CREATE OR ALTER  ?  SCHEMA version_schema;

Sources4

5.Bundling data in the package and sharing it with the app

An application package can bundle data content next to the app's logic. This is a data inclusion decision, and there are three options:

- Put the data in the package. Create the schema and table in the application package, then grant USAGE on the schema and SELECT on the table TO SHARE IN APPLICATION PACKAGE. - Reference data that stays outside the package. You cannot share objects outside the package directly with the installed app. Grant REFERENCE_USAGE on the other database to the share in the package, then create a view in the package over the external object. - Create the object in the setup script. It is then internal to the app, and the consumer cannot reach it unless you expose it.

This is the boundary between shared data and private data. Anything you add to the package is private to the package and not visible when the app is installed until you grant on it to the share. When you share an object you must also share its schema.

Sharing with the app is still not the same as exposing data to the consumer. To let consumers read shared content, the setup script creates a view in a versioned schema and grants privileges on it to an application role. Each version then holds only its own view definition, which suits upgrades. Snowflake also recommends defining policies on these proxy views, so the policies cannot be changed after installation.

The manifest can also declare shared content in a shared_content section. Snowflake says this is the recommended way to share content, and a setup script should be used only for advanced scenarios that run code in the consumer account. Each patch uses either grant-based or declarative sharing, never both.

GRANT USAGE ON SCHEMA app_package.shared_schema
  TO SHARE IN APPLICATION PACKAGE app_package;
GRANT SELECT ON TABLE app_package.shared_schema.shared_table
  TO SHARE IN APPLICATION PACKAGE app_package;

CREATE APPLICATION ROLE app_user;

CREATE OR ALTER VERSIONED SCHEMA inst_schema;
GRANT USAGE ON SCHEMA inst_schema
  TO APPLICATION ROLE app_user;

CREATE VIEW IF NOT EXISTS inst_schema.shared_view
  AS SELECT c1, c2, c3, c4
  FROM shared_schema.shared_table;

GRANT SELECT ON VIEW inst_schema.shared_view
  TO APPLICATION ROLE app_user;

Sources67

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.The setup script can be written in Python or Java, like the app's stored procedures.Why is that wrong?

   Only the setup script is limited to SQL. Procedures and UDFs can use other languages, but the setup script that creates them is plain SQL.

   Covered in The setup script: SQL only, internal by default

2. 2.Every app object should go in a versioned schema so it is version-pinned.Why is that wrong?

   Only stateless objects belong in versioned schemas. Stateful objects such as configuration tables, and unsupported types such as tasks and application roles, go in regular schemas.

   Covered in Versioned schemas versus regular schemas

3. 3.A container-based app's services should be created in a versioned schema like the rest of its code.Why is that wrong?

   Snowpark Container Services is not supported in versioned schemas, so those objects go in a regular schema.

   Covered in The application package and its manifest

4. 4.A provider can grant an installed app access to a table in another database directly.Why is that wrong?

   Objects outside the application package cannot be shared directly with the installed app. The provider needs REFERENCE_USAGE plus a view in the package.

   Covered in Bundling data in the package and sharing it with the app