创建安装脚本¶

关于安装脚本¶

安装脚本包含在如下上下文之一中运行 CREATE APPLICATION 命令时所运行的 SQL 语句：

• 使用者安装或升级 Snowflake Native App。

• A provider creates or upgrades an app when testing the application package.

The SQL statements in the setup script create objects within the app that are required by the app. This includes database objects, stored procedures, views, and application roles.

The manifest file specifies the filename and relative path to the setup script. The setup script must exist on a named stage and be accessible by the app package.

安装脚本的限制¶

在安装脚本中无法执行以下操作：

• USE DATABASE

• USE SCHEMA

• USE ROLE

• USE SECONDARY ROLES

• 使用 ALTER <object> 命令设置 LOG_LEVEL、TRACE_LEVEL 或 METRIC_LEVEL 属性。

• 创建或调用 EXECUTE AS CALLER 过程。

• 创建 Snowpark 用户定义的函数 (UDFs) 或在命名暂存区中使用 IMPORT 包含文件的过程。

• 调用引用应用程序包中未包含的代码的过程、函数或匿名代码块。

• 使用 CREATE FUNCTION 命令时从命名暂存区导入代码文件。

• 使用 CALL 调用作为 EXECUTE AS CALLER 运行的过程。

在带有版本控制的架构中创建的对象还存在其他限制。

安装脚本中创建的对象的可见性¶

The setup script can create most types of database-level objects. Database objects created by the setup script are internal to the app. When a consumer installs an app, by default, these objects are invisible and inaccessible to the consumer account directly.

A provider can make these objects visible to the consumer using application roles. An application role created within the setup script is automatically granted to the role owning the app. Application roles granted by the setup script cannot be revoked.

Users that have been granted a role that owns the application object can grant application roles to other roles within their account. For example, the setup script can define an application role, such as APP_ADMIN, and this role can grant permission to access objects within the app.

设置安装脚本输出的消息的日志级别¶

提供商可为安装脚本运行时生成的消息指定日志级别。有关更多信息，请参阅 Snowflake Scripting 中的日志记录消息。

要配置安装脚本的日志级别，请使用以下系统函数之一：

• SYSTEM$LOG

• SYSTEM$LOG_<level>

例如，要配置安装脚本以在日志中记录错误消息，请在安装脚本的开头添加以下命令：

SYSTEM$LOG('error', 'Error message');

创建模块化安装脚本¶

典型应用程序的安装脚本可能庞大而复杂。为了使安装脚本更加模块化且更易于维护，提供商可创建一个主安装脚本，并使该脚本调用多个辅助安装脚本。

例如，提供商可以创建不同的安装脚本来处理不同类型的任务，如创建对象、创建视图、创建存储过程等。

When the CREATE APPLICATION command runs, it runs the main setup script specified in the manifest file. To run additional setup scripts from the main setup script, use the EXECUTE IMMEDIATE FROM command.

主安装脚本中包含的安装脚本将按照遇到它们的顺序运行。这些辅助安装脚本还可以包含 EXECUTE IMMEDIATE FROM 命令的实例。

创建安装脚本时遵循的最佳实践¶

Snowflake 建议在为应用程序创建安装脚本时遵循以下最佳实践：

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

CREATE OR REPLACE PROCEDURE app_state.proc()...;
GRANT USAGE ON PROCEDURE app_state.proc()
  TO APPLICATION ROLE app_user;

A TAG in a versioned schema can only be assigned to the objects in the same schema. An object in a versioned schema can only have a TAG assigned that is defined in the same schema.

关于应用程序角色¶

By default the consumer has no privileges on objects created within the app. Even the ACCOUNTADMIN role cannot view the objects within an app. Objects that the app creates outside itself, such as a database, are visible only to the ACCOUNTADMIN role of the consumer account.

Application roles are similar to database roles, but may only be created within the app. Unlike database roles, application roles can be granted privileges on objects that exist outside of the app.

Application roles should be created by the setup script when the app is installed and are automatically granted to the app owner's role, who then can grant appropriate application roles to other roles in the consumer account.

Any privileges granted to application roles is passed to the app owner, which is the role used to install the app. The owner may further delegate application roles to other roles within the consumer account.

The setup script can also define an application role (e.g. USER). Using this role, consumers are granted access to use the functionality provided by the app. The setup script can define an application role, such as READ_ONLY, to provide restricted access to select areas of data within the app.

Unlike database roles, application roles may also be granted privileges on objects outside of the installed app. They may therefore be used to grant privileges on objects outside of the app. However, the application role itself must be created within the app.

支持与应用程序角色结合使用的 SQL 命令¶

Snowflake Native App Framework 提供以下与应用程序角色结合使用的 SQL 命令：

• ALTER APPLICATION ROLE

• CREATE APPLICATION ROLE

• DROP APPLICATION ROLE

• GRANT APPLICATION ROLE

• REVOKE APPLICATION ROLE

• SHOW APPLICATION ROLES

在安装脚本中使用应用程序角色¶

Application roles defined in the setup script are automatically granted to the role owning the app instance. When the app is installed, the role used to install the app is the owner of the app. However, the app owner can grant privileges to other account roles in the consumer account.

Application roles allow privileges on objects within the app to be granted 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 example, the setup script creates application roles named admin and a user. The setup script then grants both application roles access to the schema containing the app code. It also grants access to the add function within the schema. The admin role is also granted access to the config_app procedure.

应用程序角色和版本¶

Application roles are not versioned. This means that dropping an application role or revoking a permission from an object that is not in a versioned schema can impact the current version of an application or the version being upgraded. Application roles may only be safely dropped when you have dropped all versions of the app that use those roles.