Création du script d’installation¶

Cette rubrique décrit comment utiliser le script d’installation pour spécifier les objets créés lors de l’installation de votre 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 de l’application contient des instructions SQL qui sont exécutées lorsque le consommateur installe ou met à niveau une application ou lorsqu’un fournisseur installe ou met à niveau une application à des fins de test. Chaque application doit contenir un script d’installation. L’emplacement du script d’installation est spécifié dans le fichier manifeste.

Le script d’installation définit les objets qui sont créés lors de l’installation ou de la mise à jour d’une application.

Note

Le script d’installation est nécessaire pour créer un paquet d’application. Le nom et le chemin du script d’installation sont spécifiés dans le fichier manifest.yml.

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 Snowpark (UDFs) ou de procédures qui utilisent IMPORT à partir d’une zone de préparation nommée.
Appel de procédures, de fonctions ou de blocs de code anonymes qui utilisent un code d’extension.
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 a 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 pour les consommateurs¶

Le script d’installation peut définir la plupart des 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. Ils sont invisibles et inaccessibles au compte consommateur directement.

Vous pouvez 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’instance de l’application installée. Ces rôles ne peuvent pas être révoqués.

Les utilisateurs ayant le rôle de propriétaire de l’instance 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. Cet utilisateur peut ensuite utiliser ces objets pour administrer l’application.

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.

Le script d’installation est utilisé à la fois pour l’installation initiale et pour les mises à jour. Le script doit être écrit de manière idempotente. Par exemple, créer des objets avec CREATE .. IF NOT EXISTS ou CREATE OR REPLACE.

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 :

Lorsque vous utilisez la commande CREATE pour créer des objets dans le script d’installation, Snowflake recommande d’utiliser les versions CREATE OR REPLACE ou CREATE IF NOT EXISTS des commandes. Le script d’installation peut être exécuté plusieurs fois au cours de l’installation et de la mise à niveau, ainsi que dans les cas où une erreur se produit. Dans ces situations, par exemple, un schéma versionné peut ne pas être vide.
CREATE SCHEMA ne modifie pas le contexte de la session, de sorte que les objets doivent être qualifiés avec le schéma cible lors de leur création. 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
Les objets de schéma versionnés peuvent faire référence à des objets non versionnés et vice versa. Vous devez envisager la possibilité d’une défaillance lorsque le script d’installation est en cours d’exécution. Étant donné que le script d’installation est écrit pour être idempotent, il est automatiquement relancé si l’exécution initiale échoue.

Tenez-en compte lorsque vous accordez des rôles d’application au sein d’un schéma. Par exemple, vous pouvez utiliser le texte suivant :
```
CREATE OR REPLACE PROCEDURE app_state.proc()...;
-- Additional CREATE statements
GRANT USAGE ON PROCEDURE app_state.proc()
   TO APPLICATION ROLE app_user;
```
Copy
L’instruction CREATE OR REPLACE remplace la procédure, ce qui supprime implicitement les attributions accordées précédemment à cette procédure. Bien que les attributions soient 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 et que l’attribution soit rétablie.
Les vues sur le contenu partagé doivent toujours être définies dans un schéma versionné. 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.
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.

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.