Création d’un script de configuration¶

This topic describes how to use the setup script to create objects in the app when running the CREATE APPLICATION command.

Il décrit également les rôles de l’application et leur utilisation dans le script d’installation.

À propos du script d’installation¶

Le script d’installation contient des instructions SQL qui sont exécutées lorsque la commande CREATE APPLICATION est lancée dans l’un des contextes suivants :

Un consommateur installe ou met à niveau une Snowflake Native App.
A provider creates or upgrades an app when testing the application package.

Note

Le script d’installation ne prend en charge que les commandes SQL. Les autres langues ne sont pas prises en charge.

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.

Le fichier manifeste spécifie le nom du fichier et le chemin relatif vers le script d’installation. Le script d’installation doit exister sur une zone de préparation nommée et être accessible par le paquet d’application.

Restrictions sur le script d’installation¶

Les opérations suivantes ne peuvent pas être effectuées dans un script d’installation :

USE DATABASE
USE SCHEMA
USE ROLE
USE SECONDARY ROLES
Définir les propriétés LOG_LEVEL, TRACE_LEVEL ou METRIC_LEVEL avec la commande ALTER <objet>.
Création ou invocation de procédures qui sont EXECUTE AS CALLER.
Création de fonctions définies par l’utilisateur (UDFs) Snowpark ou de procédures qui utilisent IMPORT pour inclure des fichiers sur une zone de préparation nommée.
Appel de procédures, de fonctions ou de blocs de code anonymes qui font référence à du code non inclus dans le paquet d’application.
Mise en zone en zone de préparation nommée lors de l’utilisation de la commande CREATE FUNCTION.
Utilisation de CALL pour appeler une procédure qui s’exécute en tant que EXECUTE AS CALLER.

Des restrictions supplémentaires s’appliquent aux objets créés dans un schéma versionné.

Visibilité des objets créés dans le script d’installation¶

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.

Note

Les fournisseurs peuvent accéder aux objets créés par le script d’installation lorsqu’ils testent un paquet d’application en utilisant le mode développement. Voir Utilisez les modes développement, débogage et débogage de session pour tester une application pour plus d’informations.

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.

Définir le niveau de journalisation des messages émis par le script d’installation¶

Un fournisseur peut spécifier le niveau de journalisation des messages générés lors de l’exécution du script d’installation. Voir Enregistrement des messages dans Snowflake Scripting pour plus d’informations.

Pour configurer le niveau de journalisation du script d’installation, utilisez l’une des fonctions système suivantes :

Par exemple, pour configurer le script d’installation afin qu’il consigne les messages d’erreur, ajoutez la commande suivante au début du script d’installation :

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

Copy

Créer des scripts d’installation modulaires¶

Le script d’installation d’une application classique peut être volumineux et complexe. Pour rendre le script d’installation plus modulaire et plus facile à maintenir, un fournisseur peut créer un script d’installation principal qui appelle plusieurs scripts d’installation secondaires.

Par exemple, un fournisseur peut créer différents scripts d’installation pour gérer différents types de tâches, comme la création d’objets, la création de vues, la création de procédures stockées, etc.

Lorsque la commande CREATE APPLICATION est exécutée, elle lance le script d’installation principal spécifié dans le fichier manifeste. Pour exécuter des scripts d’installation supplémentaires à partir du script d’installation principal, utilisez la commande EXECUTE IMMEDIATE FROM.

Les scripts d’installation inclus dans le script d’installation principal sont exécutés dans l’ordre où ils sont rencontrés. Ces scripts d’installation secondaires peuvent également inclure des instances de la commande EXECUTE IMMEDIATE FROM.

Ajouter plusieurs scripts d’installation à une application¶

Ajoutez l’emplacement du script d’installation principal au fichier manifeste.
```
artifacts:
  ...
  setup_script: scripts/setup.sql
  ...
```
Copy
Créez le script d’installation principal.

L’exemple suivant montre une structure de répertoire typique pour une application :
```
@test.schema1.stage1:
└── /
    ├── manifest.yml
    ├── readme.md
    ├── scripts/setup_script.sql
```
Copy
Où setup_script.sql est le script d’installation principal.

Créez les scripts d’installation secondaires.

L’exemple suivant montre une structure de répertoire typique pour une application contenant plusieurs scripts d’installation :

@test.schema1.stage1:
└── /
    ├── manifest.yml
    ├── readme.md
    ├── scripts/setup_script.sql
    ├── scripts/secondary_script.sql
    ├── scripts/procs/setup_procs.sql
    ├── scripts/views/setup_views.sql
    ├── scripts/data/setup_data.sql

Copy

Dans le script d’installation principal, utilisez la commande EXECUTE IMMEDIATE FROM pour spécifier un chemin relatif vers chaque script d’installation secondaire :
```
...
EXECUTE IMMEDIATE FROM 'secondary_script.sql';
EXECUTE IMMEDIATE FROM './procs/setup_procs.sql';
EXECUTE IMMEDIATE FROM '../scripts/views/setup_views.sql';
EXECUTE IMMEDIATE FROM '/scripts/data/setup_data.sql';
...
```
Copy
Le chemin fourni à la commande EXECUTE IMMEDIATE FROM est sensible à la casse et peut être utilisé avec n’importe quel script d’installation. Utilisez une barre oblique (/) pour indiquer le chemin relatif du répertoire racine de l’application, utilisez un point et une barre oblique (./) pour indiquer le répertoire actuel du script d’installation et utilisez deux points et une barre oblique (../) pour indiquer le répertoire parent du script d’installation.

Un script d’installation principal est le script défini dans le manifeste. La commande EXECUTE IMMEDIATE FROM peut être utilisée avec n’importe quel script d’installation.

Limites de l’utilisation de EXECUTE IMMEDIATE FROM dans un script d’installation¶

Les limites suivantes s’appliquent lors de l’utilisation de EXECUTE IMMEDIATE FROM dans un script d’installation :

La journalisation des événements n’est pas prise en charge dans les scripts d’installation appelés à l’aide de EXECUTE IMMEDIATE FROM.
L’accès aux fichiers stockés dans des zones de préparation externes cryptées dans le compte du consommateur n’est pas possible.
Pendant l’exécution de l’application, seul le format du chemin relatif avec une barre oblique (/) est autorisé. Par exemple, EXECUTE IMMEDIATE FROM '/scripts/data/setup_data.sql'.

Bonnes pratiques lors de la création du script d’installation¶

Snowflake recommande les meilleures pratiques suivantes lors de la création du script d’installation d’une application.

Utiliser les formes idempotentes des instructions CREATE¶

Lorsque vous utilisez une commande CREATE pour créer des objets dans le script d’installation, Snowflake recommande d’utiliser les versions de ces commandes :

CREATE OR REPLACE
CREATE IF NOT EXISTS

Le script d’installation peut être exécuté plusieurs fois au cours de l’installation et de la mise à niveau. Dans les cas où une erreur se produit, ces objets peuvent déjà exister, en particulier s’ils sont créés dans un schéma avec versions.

Inclure le schéma cible lors de la création d’objets¶

La commande CREATE SCHEMA ne modifie pas le contexte de la session. Les objets doivent être qualifiés avec le schéma cible lorsqu’ils sont créés. Par exemple, pour créer un schéma dans le script d’installation, utilisez les commandes suivantes :

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

Copy

Do not refer to objects in the app from outside the app¶

Do not create objects outside the app that refer to objects within the app. Although the Snowflake Native App Framework does not prohibit creating these objects, it can lead to problems when a consumer installs the Snowflake Native App.

For example, consider the context where a setup script creates a database, schema, and view outside of the app and the view refers to a table within the app. In this context, the view in the database breaks when the consumer takes ownership of the database and drops the app.

Cette meilleure pratique s’applique aux tables, aux procédures stockées, aux fonctions définies par l’utilisateur et aux références créées par le script d’installation.

Tenir compte des défaillances possibles lors de l’utilisation de schémas avec ou sans versions¶

Les objets d’un schéma avec version peuvent faire référence à des objets d’un schéma sans versions et vice versa. Le script d’installation doit tenir compte de ce qui pourrait se produire en cas de défaillance lors de l’installation ou de la mise à niveau. Par exemple, un fournisseur doit tenir compte de ce qui se passe si le script d’installation s’exécute à nouveau automatiquement en cas d’échec de l’exécution initiale.

Par exemple, il est possible de créer des objets à l’aide de la méthode suivante :

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

Copy

Dans cet exemple, l’instruction CREATE OR REPLACE remplace une procédure existante, ce qui supprime implicitement les privilèges précédemment accordés à cette procédure. Bien que les attributions puissent être rétablies à un stade ultérieur du script, si le script échoue lors de son exécution, les consommateurs risquent de ne plus pouvoir accéder à la procédure.

Si le script d’installation échoue en raison d’un problème qui ne peut être résolu par une nouvelle tentative, par exemple une erreur de syntaxe, le consommateur ne peut accéder à la procédure jusqu’à ce qu’une nouvelle version ou un correctif soit mis à niveau pour l’application et que l’attribution soit rétablie.

Prudence

Les orientations de cette section ne s’appliquent pas aux balises, aux politiques de masquage et aux politiques d’accès aux lignes en dehors du contexte de la Snowflake Native App Framework.

Les attributions de balises et de règles ne se propagent pas aux versions incrémentielles d’un schéma avec versions. Ces scénarios déclenchent un message d’erreur (en utilisant une balise comme exemple) :

Création d’une balise dans le schéma versionné et affectation de la balise à un objet dans un schéma différent.
Création d’une balise dans un schéma non versionné et affectation de la balise à un objet dans un schéma versionné.
Création de tables ou de vues dans le schéma versionné et attribution d’une balise aux tables ou aux vues lorsque la balise existe dans un schéma non versionné.
Création de tables ou de vues dans un schéma non versionné et attribution d’une balise aux tables ou aux vues lorsque la balise existe dans un schéma versionné.

Le message d’erreur est le suivant :

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.

Si l’affectation de la politique déclenche le message d’erreur, celui-ci indique POLICY au lieu de TAG.

Pour éviter le message d’erreur :

Le fournisseur de Snowflake Native App doit mettre à jour le script d’installation pour s’assurer que les balises (ou politiques) sont définies sur des objets du même schéma que la balise lorsqu’un schéma avec versions contient soit la balise, soit l’objet sur lequel la balise est définie. Si un schéma non versionné contient la balise ou l’objet sur lequel la balise est définie, il n’est pas nécessaire de mettre à jour le script de configuration.
If the Snowflake Native App consumer sees this error message when installing an app, the consumer should ask the provider to update their setup script. Additionally, the consumer should not assign any tag that exists in a versioned schema to any object in their account, such as a warehouse, or assign a policy that exists in a versioned schema to a table or column, or assign a policy or tag to an object that exists in a versioned schema inside the Snowflake Native App. If so, Snowflake returns the same error message.

Définir des vues dans un schéma avec versions¶

Définissez toujours les vues sur le contenu partagé dans un schéma versionné afin de garantir que tout code accédant à la vue lors d’une mise à niveau utilise une vue cohérente. Vous devez également utiliser un schéma versionné lorsque vous ajoutez ou supprimez de nouvelles colonnes ou d’autres attributs.

Assurez la compatibilité des opérations fastidieuses¶

Si le script d’installation doit effectuer des opérations de très longue durée, telles que la mise à jour de grandes tables de statut, assurez-vous que ces mises à jour sont compatibles avec le code d’exécution existant de la version précédente.

À propos des rôles d’applications¶

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.

Note

Application roles are the only type of role that can be created within an app. Database roles, for example, are not permitted within the app.

Likewise, application roles can only be created in an app and not, for example, in a normal database or at the account level.

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.

Commandes SQL prises en charge pour l’utilisation de rôles d’application¶

Le Snowflake Native App Framework fournit les commandes SQL suivantes pour travailler avec les rôles d’application :

Utilisation des rôles d’application dans le script d’installation¶

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;

Copy

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.

Rôles et versions des applications¶

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.

Note

Les rôles d’application ne peuvent pas se voir attribuer la propriété d’objets. Cela signifie qu’un rôle d’application défini dans le script d’installation ne doit être utilisé que pour permettre aux consommateurs d’accéder à des objets dans l”Snowflake Native App installée.