Setup-Skript erstellen¶

Unter diesem Thema wird beschrieben, wie Sie das Setup-Skript verwenden, um Objekte im Anwendungsobjekt zu erstellen, wenn Sie den Befehl CREATE APPLICATION ausführen.

Außerdem werden im Setup-Skript Anwendungsrollen und deren Verwendung beschrieben.

Allgemeine Informationen zum Setup-Skript¶

Das Setup-Skript enthält SQL-Anweisungen, die ausgeführt werden, wenn der Befehl CREATE APPLICATION in einem der folgenden Kontexte ausgeführt wird:

Ein Verbraucher installiert oder aktualisiert eine Snowflake Native App.
Ein Anbieter erstellt oder aktualisiert ein Anwendungsobjekt, wenn ein Anwendungspaket getestet wird.

Bemerkung

Das Setup-Skript unterstützt nur die Verwendung von SQL-Befehlen. Andere Sprachen werden nicht unterstützt.

Die SQL-Anweisungen im Setup-Skript erstellen Objekte innerhalb des Anwendungsobjekts, die von der App benötigt werden. Dazu gehören Datenbankobjekte, gespeicherte Prozeduren, Ansichten, Anwendungsrollen usw.

Das Setup-Skript ist für das Anwendungspaket erforderlich. Die Datei manifest.yml gibt sowohl den Dateinamen als auch den relativen Pfad zum Setup-Skript an. Sowohl die Datei manifest.yml als auch das Setup-Skript müssen in einem benannten Stagingbereich vorhanden sein, wenn das Anwendungspaket erstellt wird.

Einschränkungen für das Setup-Skript¶

Folgendes kann innerhalb eines Setup-Skripts nicht ausgeführt werden:

USE DATABASE
USE SCHEMA
USE ROLE
USE SECONDARY ROLES
Einstellen der Eigenschaften LOG_LEVEL oder TRACE_LEVEL mit dem Befehl ALTER <Objekt>.
Erstellen oder Aufrufen von Prozeduren, die EXECUTE AS CALLER verwenden
Erstellen von benutzerdefinierten Snowpark-Funktionen (UDFs) oder Prozeduren, die IMPORT verwenden, um Dateien in einem benannten Stagingbereich einzuschließen.
Aufrufen von Prozeduren, Funktionen oder anonymen Codeblöcken, die sich auf Code beziehen, der nicht im Anwendungspaket enthalten ist.
Importieren von Codedateien aus einem benannten Stagingbereich bei Verwendung des Befehls CREATE FUNCTION
Verwenden von CALL zum Aufrufen einer Prozedur, die EXECUTE AS CALLER ausführt.

Es gibt weitere Einschränkungen für Objekte, die innerhalb eines versionierten Schemas erstellt werden.

Sichtbarkeit von im Setup-Skript erstellten Objekten¶

Das Setup-Skript kann die meisten Objekttypen auf Datenbankebene erstellen. Die vom Setup-Skript erstellten Datenbankobjekte sind intern für die Anwendung. Wenn ein Verbraucher eine App installiert, sind diese Objekte standardmäßig nicht sichtbar und für das Verbraucherkonto nicht direkt zugänglich.

Bemerkung

Anbieter können beim Testen eines Anwendungspakets mit Allgemeine Informationen zum Entwicklungsmodus auf Objekte zugreifen, die durch das Setup-Skript erstellt wurden.

Ein Anbieter kann diese Objekte mithilfe von Anwendungsrollen für den Verbraucher sichtbar machen. Eine im Setup-Skript erstellte Anwendungsrolle wird automatisch der Rolle zugewiesen, die Eigentümer des installierten Anwendungsobjekts ist. Durch das Setup-Skript zugewiesene Anwendungsrollen können nicht entzogen werden.

Benutzer mit der Rolle, die Eigentümer des Anwendungsobjekts ist, können dann anderen Rollen innerhalb ihrer Organisation Anwendungsrollen zuweisen. Das Setup-Skript kann zum Beispiel eine Anwendungsrolle APP_ADMIN definieren, der es die Berechtigung zum Zugriff auf Objekte innerhalb der Anwendung erteilt. Ein Benutzer, dem die Rolle zugewiesen wurde, die Eigentümer des Anwendungsobjekts ist, kann anderen Rollen Anwendungsrollen für diese Objekte zuweisen.

Protokolliergrad für Meldungsausgabe über Setup-Skript festlegen¶

Ein Anbieter kann den Protokolliergrad für Meldungen angeben, die beim Ausführen des Setup-Skripts generiert werden. Weitere Informationen dazu finden Sie unter Protokollierung von Meldungen in Snowflake Scripting.

Um den Protokolliergrad für das Setup-Skript zu konfigurieren, verwenden Sie eine der folgenden Systemfunktionen:

Um beispielsweise das Setup-Skript so zu konfigurieren, dass Fehlermeldungen protokolliert werden, fügen Sie den folgenden Befehl am Anfang des Setup-Skripts ein:

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

Copy

Modulare Setup-Skripte erstellen¶

Das Setup-Skript einer typischen App kann umfangreich und komplex sein. Um das Setup-Skript modularer zu gestalten, damit es einfacher gepflegt werden kann, kann ein Anbieter ein primäres Setup-Skript erstellen, das mehrere sekundäre Setup-Skripte aufruft.

So kann ein Anbieter beispielsweise verschiedene Setup-Skripte erstellen, um verschiedene Typen von Aufgaben zu bearbeiten, z. B. Erstellen von Objekten, Erstellen von Ansichten, Erstellen von gespeicherten Prozeduren usw.

Wenn der Befehl CREATE APPLICATION ausgeführt wird, führt er das in manifest.yml angegebene primäre Setup-Skript aus. Um zusätzliche Setup-Skripte vom primären Setup-Skript aus zu starten, verwenden Sie den Befehl EXECUTE IMMEDIATE FROM.

Die im primären Setup-Skript enthaltenen Setup-Skripte werden in der Reihenfolge ausgeführt, in der sie gefunden werden. Diese sekundären Setup-Skripte können auch Instanzen des Befehls EXECUTE IMMEDIATE FROM enthalten.

Mehrere Setup-Skripte zu einer App hinzufügen¶

Um einer App mehrere Setup-Skripte hinzuzufügen, gehen Sie wie folgt vor:

Fügen Sie den Speicherort des primären Setup-Skripts zu manifest.yml hinzu.
```
artifacts:
  ...
  setup_script: scripts/setup.sql
  ...
```
Copy
Erstellen Sie das primäre Setup-Skript.

Das folgende Beispiel zeigt eine typische Verzeichnisstruktur für eine App:
```
@test.schema1.stage1:
└── /
    ├── manifest.yml
    ├── readme.md
    ├── scripts/setup_script.sql
```
Copy
Dabei ist setup_script.sql das primäre Setup-Skript.

Erstellen Sie die sekundären Setup-Skripte.

Das folgende Beispiel zeigt eine typische Verzeichnisstruktur für eine App, die mehrere Setup-Skripte enthält:

@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

Verwenden Sie innerhalb des primären Setup-Skripts den Befehl EXECUTE IMMEDIATE FROM, um einen relativen Pfad zu jedem sekundären Setup-Skript anzugeben:

...
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

Der für den Befehl EXECUTE IMMEDIATE FROM angegebene Pfad ist relativ zum Speicherort des primären Setup-Skripts.

Einschränkungen bei Verwendung von EXECUTE IMMEDIATE FROM in einem Setup-Skript¶

Die folgenden Einschränkungen gelten bei der Verwendung von EXECUTE IMMEDIATE FROM in einem Setup-Skript:

Die Ereignisprotokollierung wird in Setup-Skripten, die mit EXECUTE IMMEDIATE FROM aufgerufen werden, nicht unterstützt.
EXECUTE IMMEDIATE FROM wird nur in einem Setup-Skript unterstützt. Die Verwendung dieses Befehls in anderen Kontexten außerhalb des Setup-Skripts wird nicht unterstützt.
Der Zugriff auf Dateien, die in verschlüsselten externen Stagingbereichen des Verbraucherkontos gespeichert sind, wird nicht unterstützt.

Bewährte Methoden für das Erstellen des Setup-Skripts¶

Snowflake empfiehlt die folgenden bewährten Methoden für das Erstellen des Setup-Skripts für eine App.

Idempotente Formen von CREATE-Anweisungen verwenden¶

Wenn Sie den CREATE-Befehl verwenden, um Objekte innerhalb des Setup-Skripts zu erstellen, empfiehlt Snowflake die Verwendung der folgenden Versionen dieser Befehle:

CREATE OR REPLACE
CREATE IF NOT EXISTS

Das Setup-Skript kann während der Installation oder des Upgrades mehrfach ausgeführt werden. In Fällen, in denen ein Fehler auftritt, könnten diese Objekte bereits existieren, insbesondere wenn sie innerhalb eines versionierten Schemas erstellt wurden.

Zielschema beim Erstellen von Objekten einbinden¶

Mit dem Befehl CREATE SCHEMA wird der Sitzungskontext nicht geändert. Objekte müssen bei ihrer Erstellung mit dem Zielschema qualifiziert werden. Um beispielsweise ein Schema innerhalb des Setup-Skripts zu erstellen, verwenden Sie die folgenden Befehle:

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

Copy

Nicht auf Objekte im Anwendungsobjekt von außerhalb des Anwendungsobjekts verweisen¶

Erstellen Sie keine Objekte außerhalb des Anwendungsobjekts, die auf Objekte innerhalb des Anwendungsobjekts verweisen. Obwohl Snowflake Native App Framework das Erstellen dieser Objekte zulässt, kann es zu Problemen führen, wenn ein Verbraucher die Snowflake Native App installiert.

Angenommen, dass ein Setup-Skript eine Datenbank, ein Schema und eine Ansicht außerhalb des Anwendungsobjekts erstellt und sich die Ansicht auf eine Tabelle innerhalb des Anwendungsobjekts bezieht. Wenn in diesem Zusammenhang der Verbraucher die Eigentümerschaft über die Datenbank übernimmt und das Anwendungsobjekt löscht, wird die Ansicht in der Datenbank beschädigt.

Diese bewährte Methode gilt für Tabellen, gespeicherte Prozeduren, benutzerdefinierte Funktionen und Referenzen, die durch das Setup-Skript erstellt werden.

Berücksichtigung möglicher Fehler bei der Verwendung versionierter oder nicht versionierter Schemas¶

Objekte in einem versionierten Schema können auf Objekte in einem nicht versionierten Schema verweisen und umgekehrt. Das Setup-Skript muss berücksichtigen, was im Falle eines Fehlers während der Installation oder des Upgrades passieren könnte. So muss ein Anbieter beispielsweise berücksichtigen, was passiert, wenn das Setup-Skript automatisch erneut ausgeführt wird, falls die erstmalige Ausführung fehlschlägt.

Sie können zum Beispiel folgende Objekte erstellen:

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

Copy

In diesem Beispiel ersetzt die Anweisung CREATE OR REPLACE eine bestehende Prozedur, wodurch implizit die Berechtigungen, die dieser Prozedur zuvor erteilt wurden, wieder entzogen werden. Obwohl die Berechtigungszuweisungen zu einem späteren Zeitpunkt im Skript wiederhergestellt werden, kann es vorkommen, dass Verbraucher den Zugriff auf die Prozedur verlieren, wenn die Ausführung des Skripts fehlschlägt.

Wenn das Setup-Skript aufgrund eines Problems fehlschlägt, das nicht durch eine wiederholte Ausführung behoben werden kann, z. B. bei einem Syntaxfehler, kann der Verbraucher erst wieder auf die Prozedur zugreifen, wenn eine neue Version oder ein Patch für die App erstellt und die Berechtigungszuweisung wiederhergestellt wurde.

Vorsicht

Die Hinweise in diesem Abschnitt gelten nicht für Tags, Maskierungsrichtlinien und Zeilenzugriffsrichtlinien außerhalb des Kontexts des Snowflake Native App Framework.

Tag- und Richtlinienzuweisungen werden nicht auf inkrementelle Versionen eines versionierten Schemas übertragen. Diese Szenarios lösen eine Fehlermeldung aus (am Beispiel eines Tags):

Erstellen eines Tags im versionierten Schema und Zuweisen des Tags zu einem Objekt in einem anderen Schema.
Erstellen eines Tags in einem nicht versionierten Schema und Zuweisen des Tags zu einem Objekt in einem versionierten Schema.
Erstellen von Tabellen oder Ansichten im versionierten Schema und Zuweisen der Tabellen oder Ansichten zu einem Tag, wenn das Tag in einem nicht versionierten Schema existiert.
Erstellen von Tabellen oder Ansichten in einem nicht versionierten Schema und Zuweisen der Tabellen oder Ansichten zu einem Tag, wenn das Tag in einem versionierten Schema existiert.

Die Fehlermeldung lautet:

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.

Wenn die Fehlermeldung von der Richtlinienzuweisung ausgelöst wird, wird in der Fehlermeldung POLICY anstelle von TAG angegeben.

So vermeiden Sie die Fehlermeldung:

Der Snowflake Native App-Anbieter muss das Setup-Skript aktualisieren, um sicherzustellen, dass Tags (oder Richtlinien) auf Objekte innerhalb desselben Schemas wie das Tag gesetzt werden, wenn ein versioniertes Schema entweder das Tag oder das Objekt enthält, auf das das Tag gesetzt ist. Wenn ein nicht versioniertes Schema entweder das Tag oder das Objekt enthält, auf das das Tag gesetzt ist, ist es nicht notwendig, das Setup-Skript zu aktualisieren.
Wenn der Snowflake Native App-Verbraucher diese Fehlermeldung bei der Installation einer Anwendung sieht, sollte er den Anbieter bitten, sein Setup-Skript zu aktualisieren. Darüber hinaus sollte der Verbraucher keinem Objekt in seinem Konto, z. B. einem Warehouse, ein Tag zuweisen, das in einem versionierten Schema existiert, oder einer Tabelle oder Spalte eine Richtlinie zuweisen, die in einem versionierten Schema existiert, oder einem Objekt eine Richtlinie oder ein Tag zuweisen, das in einem versionierten Schema innerhalb der Snowflake Native App existiert. In diesem Fall gibt Snowflake die gleiche Fehlermeldung zurück.

Ansichten innerhalb eines versionierten Schemas definieren¶

Definieren Sie Ansichten auf freigegebenen Inhalten immer in einem versionierten Schema. Dadurch wird sichergestellt, dass jeder Code, der während eines Upgrades auf die Ansicht zugreift, eine konsistente Ansicht verwendet, auch wenn neue Spalten oder andere Attribute hinzugefügt oder entfernt werden.

Kompatibilität von zeitintensiven Operationen sicherstellen¶

Wenn das Setup-Skript Operationen mit sehr langen Ausführungszeiten ausführen muss, wie z. B. das Aktualisieren großer Zustandstabellen, müssen Sie sicherstellen, dass diese Aktualisierungen mit bereits in Ausführung befindlichem Code der Vorgängerversion kompatibel sind.

Allgemeine Informationen zu Anwendungsrollen¶

Standardmäßig hat der Verbraucher keine Berechtigungen für Objekte, die innerhalb der Anwendung erstellt werden. Auch für die Rolle ACCOUNTADMIN sind die Objekte innerhalb einer Anwendung nicht sichtbar. Objekte, die von der Anwendung außerhalb ihrer selbst erstellt werden, wie z. B. eine Datenbank, sind nur für die Rolle ACCOUNTADMIN des Verbraucherkontos sichtbar.

Anwendungsrollen sind ähnlich wie Datenbankrollen, können aber nur innerhalb der Anwendung erstellt werden. Im Gegensatz zu Datenbankrollen können Anwendungsrollen Berechtigungen für Objekte zugewiesen werden, die außerhalb der Anwendung existieren.

Anwendungsrollen müssen während der Installation der Anwendung durch das Setup-Skript erstellt werden. Sie werden automatisch der Rolle des Anwendungseigentümers zugewiesen, der dann anderen Rollen im Verbraucherkonto entsprechende Anwendungsrollen zuweisen kann.

Bemerkung

Anwendungsrollen sind der einzige Rollentyp, der innerhalb einer Anwendung erstellt werden kann. Datenbankrollen sind zum Beispiel innerhalb der Anwendung nicht zulässig.

Ebenso können Anwendungsrollen nur in einer Anwendung erstellt werden und nicht z. B. in einer normalen Datenbank oder auf der Kontoebene.

Alle Berechtigungen, die Anwendungsrollen zugewiesen werden, werden an den Eigentümer der Anwendung weitergegeben, d. h. an die Rolle, die für die Installation der Anwendung verwendet wird. Der Eigentümer kann außerdem Anwendungsrollen an andere Rollen innerhalb des Verbraucherkontos delegieren.

Das Setup-Skript kann auch eine Anwendungsrolle definieren (z. B. USER). Mit dieser Rolle wird den Verbrauchern der Zugriff auf die von der Anwendung bereitgestellten Funktionen gewährt. Das Setup-Skript kann eine Anwendungsrolle definieren, z. B. READ_ONLY, um innerhalb der Anwendung eingeschränkten Zugriff auf bestimmte Bereiche der Daten bereitzustellen.

Im Gegensatz zu Datenbankrollen können Anwendungsrollen auch Berechtigungen für Objekte außerhalb der installierten Anwendung zugewiesen werden. Sie können daher verwendet werden, um Berechtigungen für Objekte außerhalb der Anwendung zuzuweisen. Die Anwendungsrolle selbst muss jedoch innerhalb der Anwendung erstellt werden.

Unterstützte SQL-Befehle für die Verwendung von Anwendungsrollen¶

Das Snowflake Native App Framework bietet die folgenden SQL-Befehle für die Verwendung von Anwendungsrollen:

Verwenden von Anwendungsrollen im Setup-Skript¶

Die im Setup-Skript definierten Anwendungsrollen werden automatisch der Rolle zugewiesen, die Eigentümer der Anwendungsinstanz ist. Wenn die Anwendung installiert wird, wird die Rolle, mit der die Anwendung installiert wird, zum Eigentümer der Anwendung. Der Eigentümer der Anwendung kann anderen Kontorollen im Verbraucherkonto Berechtigungen zuweisen.

Mit Anwendungsrollen können dem Verbraucher innerhalb der Anwendung Berechtigungen für Objekte zugewiesen werden. Beispiel:

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

Im folgenden Beispiel erstellt das Setup-Skript Anwendungsrollen mit den Namen admin und user. Das Setup-Skript gewährt dann beiden Anwendungsrollen Zugriff auf das Schema, das den Anwendungscode enthält. Sie weist außerdem die Zugriffsberechtigung auf die Funktion add innerhalb des Schemas zu. Die Rolle admin erhält außerdem Zugriff auf die Prozedur config_app.

Anwendungsrollen und Versionen¶

Anwendungsrollen sind nicht versioniert. Das bedeutet, dass das Löschen einer Anwendungsrolle oder der Entzug einer Berechtigung für ein Objekt, das nicht in einem versionierten Schema enthalten ist, Auswirkungen auf die aktuelle Version einer Anwendung oder die zu aktualisierende Version haben kann. Anwendungsrollen werden nur dann sicher gelöscht, wenn Sie alle Versionen der Anwendung, die diese Rollen verwenden, gelöscht haben.

Bemerkung

Anwendungsrollen kann nicht die Eigentümerschaft an Objekten zugewiesen werden. Das bedeutet, dass eine im Setup-Skript definierte Anwendungsrolle nur verwendet werden sollte, um Verbrauchern den Zugriff auf Objekte innerhalb der installierten Snowflake Native App zu ermöglichen.