Criação de um script de configuração¶

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

Ele também descreve as funções do aplicativo e como elas são usadas no script de configuração.

Sobre o script de configuração¶

O script de configuração contém instruções SQL que são executadas quando o comando CREATE APPLICATION é executado em um dos seguintes contextos:

Um consumidor instala ou atualiza um Snowflake Native App.
A provider creates or upgrades an app when testing the application package.

Nota

O script de configuração suporta apenas o uso de comandos SQL. Outros idiomas não são suportados.

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.

O arquivo de manifesto especifica o nome de arquivo e o caminho para o script de configuração. O script de configuração deve existir em um estágio nomeado e ser acessível pelo pacote do aplicativo.

Restrições no script de configuração¶

O seguinte não pode ser executado em um script de configuração:

USE DATABASE
USE SCHEMA
USE ROLE
USE SECONDARY ROLES
Configuração das propriedades LOG_LEVEL, TRACE_LEVEL ou METRIC_LEVEL com o comando ALTER <objeto>.
Criação e invocação de procedimentos que são EXECUTE AS CALLER.
Criação de funções definidas pelo usuário (UDFs) ou procedimentos do Snowpark que usam IMPORT para incluir arquivos em um estágio nomeado.
Chamar procedimentos, funções ou blocos de código anônimos que se referem a códigos não incluídos no pacote de aplicativo.
Importação de arquivos de código de um estágio nomeado ao usar o comando CREATE FUNCTION.
Usando CALL para chamar um procedimento que é executado como EXECUTE AS CALLER.

Existem restrições adicionais em objetos criados em um esquema com versão.

Visibilidade dos objetos criados no script de configuração¶

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.

Nota

Os provedores podem acessar objetos criados pelo script de configuração usando o modo de desenvolvimento ao testar um pacote de aplicativo. Consulte Usar os modos de desenvolvimento, depuração e depuração de sessão para testar um aplicativo para obter mais informações.

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.

Defina o nível de log para mensagens geradas pelo script de configuração¶

Um provedor pode especificar o nível de log para mensagens geradas quando o script de configuração é executado. Consulte Registro de mensagens no Snowflake Scripting para obter informações adicionais.

Para configurar o nível de log do script de configuração, use uma das seguintes funções do sistema:

Por exemplo, para configurar o script de configuração para registrar mensagens de erro, adicione o seguinte comando no início do script de configuração:

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

Copy

Criação de scripts de configuração modular¶

O script de configuração de um aplicativo típico pode ser grande e complexo. Para tornar o script de configuração mais modular e fácil de manter, um provedor pode criar um script de configuração primário que chama vários scripts de configuração secundários.

Por exemplo, um provedor pode criar diferentes scripts de configuração para lidar com diferentes tipos de tarefas, por exemplo, criação de objetos, criação de exibições, criação de procedimentos armazenados etc.

Quando o comando CREATE APPLICATION é executado, ele executa o script de configuração principal especificado no arquivo de manifesto. Para executar scripts de configuração adicionais a partir do script de configuração principal, use o comando EXECUTE IMMEDIATE FROM.

Os scripts de configuração incluídos no script de configuração principal são executados na ordem em que são encontrados. Esses scripts de configuração secundária também podem incluir instâncias do comando EXECUTE IMMEDIATE FROM.

Adição de vários scripts de configuração a um aplicativo¶

Adicione o local do script de configuração principal ao arquivo de manifesto.
```
artifacts:
  ...
  setup_script: scripts/setup.sql
  ...
```
Copy
Crie o script de configuração principal.

O exemplo a seguir mostra uma estrutura de diretório típica para um aplicativo:
```
@test.schema1.stage1:
└── /
    ├── manifest.yml
    ├── readme.md
    ├── scripts/setup_script.sql
```
Copy
Onde setup_script.sql é o script de configuração principal.

Crie os scripts de configuração secundária.

O exemplo a seguir mostra uma estrutura de diretório típica para um aplicativo que contém vários scripts de configuração:

@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

No script de configuração principal, use o comando EXECUTE IMMEDIATE FROM para especificar um caminho relativo para cada script de configuração secundário:
```
...
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
O caminho fornecido para o comando EXECUTE IMMEDIATE FROM diferencia maiúsculas de minúsculas e pode ser usado com qualquer script de configuração. Use uma barra (/) para indicar o caminho relativo do diretório raiz do aplicativo, use um ponto e uma barra (./) para indicar o diretório atual do script de configuração e use dois pontos e uma barra (../) para indicar o diretório pai do script de configuração.

Um script de configuração primária é o script definido no manifesto. O comando EXECUTE IMMEDIATE FROM pode ser usado com qualquer script de configuração.

Limitações ao usar EXECUTE IMMEDIATE FROM em um script de configuração¶

As seguintes limitações se aplicam ao usar EXECUTE IMMEDIATE FROM em um script de configuração:

O registro de eventos não é compatível com scripts de configuração chamados usando EXECUTE IMMEDIATE FROM.
O acesso a arquivos armazenados em estágios externos criptografados na conta do consumidor não é compatível.
Durante o tempo de execução do aplicativo, somente o formato de caminho relativo com uma barra (/) é permitido. Por exemplo, EXECUTE IMMEDIATE FROM '/scripts/data/setup_data.sql'.

Práticas recomendadas ao criar o script de configuração¶

A Snowflake recomenda as seguintes práticas recomendadas ao criar o script de configuração de um aplicativo.

Uso das formas idempotentes de instruções CREATE¶

Ao usar um comando CREATE para criar objetos dentro do script de configuração, Snowflake recomenda o uso das seguintes versões desses comandos:

CREATE OR REPLACE
CREATE IF NOT EXISTS

O script de configuração pode ser executado várias vezes durante a instalação e atualização. Nos casos em que ocorre um erro, esses objetos podem já existir, especialmente se forem criados dentro de um esquema com versão.

Inclusão do esquema de destino ao criar objetos¶

O comando CREATE SCHEMA não altera o contexto da sessão. Os objetos devem ser qualificados com o esquema de destino quando são criados. Por exemplo, para criar um esquema no script de configuração, use os seguintes comandos:

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.

Esta prática recomendada se aplica a tabelas, procedimentos armazenados, funções definidas pelo usuário e referências criadas pelo script de configuração.

Consideração de possíveis falhas ao usar esquemas com ou sem versão¶

Os objetos em um esquema com versão podem referir-se a objetos em um esquema sem versão e vice-versa. O script de configuração deve levar em conta o que pode acontecer em caso de falha durante a instalação ou atualização. Por exemplo, um provedor deve levar em conta o que acontece se o script de configuração for executado novamente automaticamente se a execução inicial falhar.

Por exemplo, considere criar objetos usando o seguinte:

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

Copy

Neste exemplo, a instrução CREATE OR REPLACE substitui um procedimento existente, o que remove implicitamente os privilégios que foram concedidos anteriormente a esse procedimento. Embora as concessões possam ser restauradas posteriormente no script, se o script falhar ao ser executado, os consumidores poderão perder a capacidade de acessar o procedimento.

Se um script de configuração falhar devido a um problema que não possa ser resolvido por uma nova tentativa, por exemplo, um erro de sintaxe, o consumidor não poderá acessar o procedimento até que o aplicativo seja atualizado para uma nova versão ou patch e a concessão seja restaurada.

Cuidado

As orientações nesta seção não se aplicam a tags, políticas de mascaramento e políticas de acesso a linhas fora do contexto de Snowflake Native App Framework.

As atribuições de tags e políticas não se propagam para versões incrementais de um esquema com versão. Esses cenários acionam uma mensagem de erro (usando uma tag como exemplo):

Crie uma tag no esquema com versão e atribua a tag a um objeto em um esquema diferente.
Crie uma tag em um esquema sem versão e atribua a tag a um objeto em um esquema com versão.
Crie tabelas ou exibições no esquema com versão e atribua uma tag às tabelas ou exibições quando a tag existir em um esquema sem versão.
Crie tabelas ou exibições no esquema sem versão e atribua uma tag às tabelas ou exibições quando a tag existir em um esquema com versão.

A mensagem de erro é:

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.

Se a atribuição de política acionar a mensagem de erro, a mensagem de erro especificará POLICY em vez de TAG.

Para evitar a mensagem de erro:

O provedor Snowflake Native App deve atualizar o script de configuração para garantir que as tags (ou políticas) sejam definidas em objetos dentro do mesmo esquema que a tag quando um esquema com versão contém a tag ou o objeto no qual a tag está definida. Se um esquema sem versão contiver a tag ou o objeto no qual a tag está definida, não será necessário atualizar o script de configuração.
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.

Definição de exibições dentro de um esquema com versão¶

Sempre defina exibições em conteúdo compartilhado em um esquema com versão para garantir que qualquer código que acesse a exibição durante uma atualização use uma exibição consistente. Você também deve usar um esquema com versão ao adicionar ou remover novas colunas ou outros atributos.

Garantia de que operações demoradas sejam compatíveis¶

Se o script de configuração precisar executar operações muito longas, como atualizar grandes tabelas de estado, certifique-se de que essas atualizações sejam compatíveis com o código em execução existente da versão anterior.

Sobre as funções de aplicativo¶

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.

Nota

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.

Comandos SQL com suporte para trabalhar com funções de aplicativo¶

O Snowflake Native App Framework fornece os seguintes comandos SQL para trabalhar com funções de aplicativo:

Como usar funções de aplicativo no script de configuração¶

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.

Funções e versões do aplicativo¶

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.

Nota

As funções de aplicativo não podem receber propriedade de objetos. Isso significa que uma função de aplicativo definida no script de configuração só deve ser usada para permitir que os consumidores acessem objetos dentro do Snowflake Native App instalado.