Création d’un script de configuration¶

Cette rubrique décrit comment utiliser le script de configuration pour créer des objets dans l’objet d’application lors de l’exécution de la commande CREATE APPLICATION.

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.
Un fournisseur crée ou met à niveau un objet d’application lorsqu’il teste un paquet d’application.

Note

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

Les instructions SQL du script d’installation créent des objets dans l’objet d’application qui sont nécessaires à l’application. Cela comprend les objets de la base de données, les procédures stockées, les vues, les rôles d’application, etc.

Le script d’installation est requis par le paquet d’application. Le fichier manifest.yml spécifie à la fois le nom du fichier et le chemin relatif vers le script d’installation. Le fichier manifest.yml et le script d’installation doivent tous deux exister sur une zone de préparation nommée lors de la création d’un 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 ou TRACE_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¶

Le script d’installation peut créer la plupart des types d’objets au niveau de la base de données. Les objets de base de données créés par le script d’installation sont internes à l’application. Lorsqu’un consommateur installe une application, ces objets sont par défaut invisibles et inaccessibles directement au compte du consommateur.

Note

Les fournisseurs peuvent accéder aux objets créés par le script d’installation lorsqu’ils testent un paquet d’application en utilisant À propos du mode développement.

Un fournisseur peut rendre ces objets visibles au consommateur à l’aide des rôles d’application. Tout rôle d’application créé dans le script d’installation est automatiquement attribué au rôle propriétaire de l’objet d’application. Les rôles d’application accordés par le script d’installation ne peuvent pas être révoqués.

Les utilisateurs ayant le rôle de propriétaire de l’objet d’application peuvent ensuite attribuer des rôles d’application à d’autres rôles au sein de leur organisation. Par exemple, le script d’installation peut définir un rôle d’application, tel que APP_ADMIN, auquel il accorde l’autorisation d’accès aux objets de l’application. Un utilisateur ayant le rôle de propriétaire de l’objet d’application peut accorder des rôles d’application sur ces objets à d’autres rôles.

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 l’Exécution de scripts Snowflake 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 la commande manifest.yml. 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¶

Pour ajouter plusieurs scripts d’installation à une application, procédez comme suit :

Ajoutez l’emplacement du script d’installation principal à l’élément manifest.yml.
```
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 './views/setup_views.sql'
EXECUTE IMMEDIATE FROM './data/setup_data.sql'
...

Copy

Le chemin fourni à la commande EXECUTE IMMEDIATE FROM est relatif à l’emplacement du script d’installation principal.

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 de configuration :

La journalisation des événements n’est pas prise en charge dans les scripts d’installation appelés à l’aide de EXECUTE IMMEDIATE FROM.
EXECUTE IMMEDIATE FROM n’est pris en charge que dans un script d’installation. L’utilisation de cette commande dans d’autres contextes que le script d’installation n’est pas prise en charge.
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.

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

Ne pas faire référence à des objets de l’objet d’application à partir de l’extérieur de l’objet d’application¶

Ne créez pas d’objets en dehors de l’objet d’application qui font référence à des objets de l’objet d’application. Bien que le Snowflake Native App Framework n’interdise pas la création de ces objets, il peut entraîner des problèmes lorsqu’un consommateur installe le Snowflake Native App.

Prenons l’exemple d’un script d’installation qui crée une base de données, un schéma et une vue en dehors de l’objet d’application et dont la vue fait référence à une table de l’objet d’application. Dans ce contexte, si le consommateur prend possession de la base de données et supprime l’objet de l’application, la vue dans la base de données sera interrompue.

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.
Si le consommateur de Snowflake Native App voit ce message d’erreur lors de l’installation d’une application, il doit demander au fournisseur de mettre à jour son script d’installation. En outre, le consommateur ne doit pas attribuer à un objet de son compte, tel qu’un entrepôt, une balise qui existe dans un schéma avec versions, ni attribuer à une table ou à une colonne une politique qui existe dans un schéma avec versions, ni attribuer une politique ou une balise à un objet qui existe dans un schéma avec versions à l’intérieur de Snowflake Native App. Si c’est le cas, Snowflake renvoie le même message d’erreur.

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

Définissez toujours les vues sur le contenu partagé dans un schéma avec versions. Cela garantit que tout code accédant à la vue lors d’une mise à niveau utilisera une vue cohérente, même si de nouvelles colonnes ou d’autres attributs sont ajoutés ou supprimés.

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¶

Par défaut, le consommateur n’a aucun privilège sur les objets créés au sein de l’application. Même le rôle ACCOUNTADMIN ne peut pas voir les objets à l’intérieur d’une application. Les objets que l’application crée en dehors d’elle-même, par exemple une base de données, ne sont visibles que par le rôle ACCOUNTADMIN du compte consommateur.

Les rôles d’application sont similaires aux rôles de base de données, mais ils ne peuvent être créés qu’au sein de l’application. Contrairement aux rôles de base de données, les rôles d’application peuvent se voir accorder des privilèges sur des objets qui existent en dehors de l’application.

Les rôles d’application doivent être créés par le script d’installation lors de l’installation de l’application et sont automatiquement attribués au rôle propriétaire de l’application, qui peut ensuite attribuer les rôles d’application appropriés à d’autres rôles dans le compte consommateur.

Note

Les rôles d’application sont le seul type de rôle pouvant être créé au sein d’une application. Les rôles de base de données, par exemple, ne sont pas autorisés dans l’application.

De même, les rôles d’application ne peuvent être créés que dans une application et non, par exemple, dans une base de données normale ou au niveau du compte.

Tout privilège accordé aux rôles d’application est transmis au propriétaire de l’application, qui est le rôle utilisé pour installer l’application. Le propriétaire peut en outre déléguer des rôles d’application à d’autres rôles au sein du compte consommateur.

Le script d’installation peut également définir un rôle d’application (par exemple USER). Ce rôle permet aux consommateurs d’utiliser les fonctionnalités fournies par l’application. Le script d’installation peut définir un rôle d’application, tel que READ_ONLY, pour fournir un accès restreint à des zones de données sélectionnées dans l’application.

Contrairement aux rôles de base de données, les rôles d’application peuvent également se voir accorder des privilèges sur des objets extérieurs à l’application installée. Ils peuvent donc être utilisés pour accorder des privilèges sur des objets extérieurs à l’application. Cependant, le rôle d’application lui-même doit être créé au sein de l’application.

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¶

Les rôles d’application définis dans le script d’installation sont automatiquement accordés au rôle propriétaire de l’instance d’application. Lors de l’installation de l’application, le rôle utilisé pour installer l’application est le propriétaire de l’application. Toutefois, le propriétaire de l’application peut accorder des privilèges à d’autres rôles du compte consommateur.

Les rôles d’application permettent d’attribuer au consommateur des privilèges sur les objets au sein de l’application. Par exemple :

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

Dans cet exemple, le script de configuration crée des rôles d’application nommés admin et un user. Le script de configuration accorde ensuite aux deux rôles d’application l’accès au schéma contenant le code d’application. Il permet également l’accès à la fonction add du schéma. Le rôle admin se voit également accorder l’accès à la procédure config_app.

Rôles et versions des applications¶

Les rôles d’application ne sont pas versionnés. Cela signifie que la suppression d’un rôle d’application ou la révocation d’une autorisation pour un objet qui ne figure pas dans un schéma versionné peut avoir un impact sur la version actuelle d’une application ou sur la version en cours de mise à niveau. Les rôles d’application ne peuvent être supprimés en toute sécurité que lorsque vous avez supprimé toutes les versions de l’application qui utilisent ces rôles.

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.