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

Este tópico descreve como usar o script de configuração para criar objetos no objeto aplicativo ao executar o comando CREATE APPLICATION.

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.
Um provedor cria ou atualiza um objeto de aplicativo ao testar um pacote de aplicativos.

Nota

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

As instruções SQL no script de configuração criam objetos dentro do objeto do aplicativo que são exigidos pelo aplicativo. Isso inclui objetos de banco de dados, procedimentos armazenados, exibições, funções de aplicativos etc.

O script de configuração é exigido pelo pacote de aplicativo. O arquivo manifest.yml especifica o nome do arquivo e o caminho relativo para o script de configuração. Tanto o arquivo manifest.yml quanto o script de configuração devem existir em um estágio nomeado quando um pacote de aplicativo é criado.

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 ou TRACE_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¶

O script de configuração pode criar a maioria dos tipos de objetos no nível do banco de dados. Os objetos de banco de dados criados pelo script de configuração são internos ao aplicativo. Quando um consumidor instala um aplicativo, por padrão, esses objetos ficam invisíveis e inacessíveis diretamente para a conta do consumidor.

Nota

Os provedores podem acessar objetos criados pelo script de configuração ao testar um pacote de aplicativo usando Sobre o modo de desenvolvimento.

Um provedor pode tornar esses objetos visíveis para o consumidor usando funções de aplicativo. Uma função de aplicativo criada no script de configuração é automaticamente concedida à função proprietária do objeto de aplicativo. As funções de aplicativo concedidas pelo script de configuração não podem ser revogadas.

Os usuários com a função que possui o objeto de aplicativo podem conceder funções de aplicativo a outras funções em sua organização. Por exemplo, o script de configuração pode definir uma função de aplicativo, como APP_ADMIN, à qual concede permissão para acessar objetos dentro do aplicativo. Um usuário que recebe a função que possui o objeto de aplicativo pode conceder funções de aplicativo nesses objetos para outras funções.

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 Script Snowflake 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 em manifest.yml. 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ários também podem incluir instâncias do comando EXECUTE IMMEDIATE FROM.

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

Para adicionar vários scripts de configuração a um aplicativo, faça o seguinte:

Adicione o local do script de configuração principal a manifest.yml.
```
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 './views/setup_views.sql'
EXECUTE IMMEDIATE FROM './data/setup_data.sql'
...

Copy

O caminho fornecido para o comando EXECUTE IMMEDIATE FROM é relativo ao local do script de configuração principal.

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

A seguinte limitação se aplica 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.
EXECUTE IMMEDIATE FROM só é compatível com um script de configuração. Não há suporte para o uso desse comando em outros contextos fora do script de configuração.
O acesso a arquivos armazenados em estágios externos criptografados na conta do consumidor não é compatível.

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

Não faça referência a objetos no objeto aplicativo de fora do objeto aplicativo¶

Não crie objetos fora do objeto de aplicativo que se refiram a objetos dentro do objeto de aplicativo. Embora o Snowflake Native App Framework não proíba a criação desses objetos, ele pode causar problemas quando um consumidor instala o Snowflake Native App.

Por exemplo, considere o contexto em que um script de configuração cria um banco de dados, um esquema e uma exibição fora do objeto de aplicativo e a exibição se refere a uma tabela dentro do objeto de aplicativo. Nesse contexto, se o consumidor se apropriar do banco de dados e descartar o objeto de aplicativo, a exibição no banco de dados será quebrada.

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.
Se o consumidor Snowflake Native App vir essa mensagem de erro ao instalar um aplicativo, ele deverá solicitar ao provedor que atualize seu script de configuração. Além disso, o consumidor não deve atribuir nenhuma tag que exista em um esquema com versão a qualquer objeto em sua conta, como um warehouse, ou atribuir uma política que exista em um esquema com versão a uma tabela ou coluna, ou atribuir uma política ou tag a um objeto que existe em um esquema com versão dentro de Snowflake Native App. Nesse caso, Snowflake retorna a mesma mensagem de erro.

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

Sempre defina exibições de conteúdo compartilhado em um esquema com versão. Isso garante que qualquer código que acesse a exibição durante uma atualização use uma exibição consistente, mesmo que novas colunas ou outros atributos sejam adicionados ou removidos.

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¶

Por padrão, o consumidor não possui privilégios em objetos criados dentro do aplicativo. Mesmo a função ACCOUNTADMIN não pode visualizar os objetos dentro de um aplicativo. Os objetos que o aplicativo cria fora dele, por exemplo, um banco de dados, são visíveis apenas para a função ACCOUNTADMIN da conta do consumidor.

As funções de aplicativo são semelhantes às funções de banco de dados, mas só podem ser criadas dentro do aplicativo. Ao contrário das funções de banco de dados, as funções de aplicativo podem receber privilégios em objetos que existem fora do aplicativo.

As funções de aplicativo devem ser criadas pelo script de configuração quando o aplicativo é instalado e são concedidas automaticamente à função do proprietário do aplicativo, que pode conceder funções de aplicativo apropriadas a outras funções na conta do consumidor.

Nota

As funções de aplicativo são o único tipo de função que pode ser criado em um aplicativo. Funções de banco de dados, por exemplo, não são permitidas no aplicativo.

Da mesma forma, as funções de aplicativo só podem ser criadas em um aplicativo e não, por exemplo, em um banco de dados normal ou no nível da conta.

Quaisquer privilégios concedidos a funções de aplicativo são passados para o proprietário do aplicativo, que é a função usada para instalar o aplicativo. O proprietário pode ainda delegar funções de aplicativo a outras funções dentro da conta do consumidor.

O script de configuração também pode definir uma função de aplicativo (por exemplo, USER). Usando esta função, os consumidores recebem acesso para usar a funcionalidade fornecida pelo aplicativo. O script de configuração pode definir uma função de aplicativo, como READ_ONLY, para fornecer acesso restrito a áreas selecionadas de dados no aplicativo.

Ao contrário das funções de banco de dados, as funções de aplicativo também podem receber privilégios em objetos fora do aplicativo instalado. Eles podem, portanto, ser usados para conceder privilégios em objetos fora do aplicativo. No entanto, a própria função do aplicativo deve ser criada no aplicativo.

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¶

As funções de aplicativo definidas no script de configuração são concedidas automaticamente à função que possui a instância do aplicativo. Quando o aplicativo é instalado, a função usada para instalar o aplicativo é a proprietária do aplicativo. No entanto, o proprietário do aplicativo pode conceder privilégios a outras funções de conta na conta do consumidor.

As funções de aplicativo permitem que privilégios em objetos do aplicativo sejam concedidos ao consumidor. Por exemplo:

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

Neste exemplo, o script de configuração cria funções de aplicativo denominadas admin e user. O script de configuração concede a ambas as funções de aplicativo acesso ao esquema que contém o código do aplicativo. Também concede acesso à função add dentro do esquema. A função admin também tem acesso ao procedimento config_app.

Funções e versões do aplicativo¶

As funções de aplicativo não têm versão. Isso significa que descartar uma função de aplicativo ou revogar uma permissão de um objeto que não esteja em um esquema com versão pode afetar a versão atual de um aplicativo ou a versão que está sendo atualizada. As funções de aplicativo só podem ser descartadas com segurança quando você tiver descartado todas as versões do aplicativo que usam essas funções.

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.