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

Este tópico descreve como usar o script de configuração para especificar quais objetos são criados quando seu aplicativo é instalado. 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 do aplicativo contém instruções SQL que são executadas quando o consumidor instala ou atualiza um aplicativo ou quando um provedor instala ou atualiza um aplicativo para teste. Cada aplicativo deve conter um script de configuração. A localização do script de configuração é especificada no arquivo de manifesto.

O script de configuração define os objetos que são criados quando um aplicativo é instalado ou atualizado.

Nota

O script de configuração é necessário para criar um pacote de aplicativo. O nome e o caminho para o script de configuração são especificados no arquivo manifest.yml.

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

As seguintes operações não podem ser executadas 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 do Snowpark (UDFs) ou procedimentos que utilizam IMPORT de um estágio nomeado.
Chamadas de procedimentos, funções ou blocos de código anônimos que fazem uso de código de extensão.
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 possui 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 para os consumidores¶

O script de configuração pode definir a maioria dos 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. Eles são invisíveis e inacessíveis diretamente à conta do consumidor.

Você pode tornar esses objetos visíveis para o consumidor usando funções de aplicativo. Qualquer função de aplicativo criada no script de configuração é concedida automaticamente à função que possui a instância do aplicativo instalado. Essas funções não podem ser revogadas.

Os usuários com a função que possui a instância do 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. Esse usuário pode usar esses objetos para administrar o aplicativo.

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.

O script de configuração é usado tanto para instalação inicial quanto para atualizações. O script deve ser escrito de forma idempotente. Por exemplo, crie objetos com CREATE .. IF NOT EXISTS ou CREATE OR REPLACE.

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 para um aplicativo:

Ao usar o comando CREATE para criar objetos dentro do script de configuração, Snowflake recomenda usar as versões CREATE OR REPLACE ou CREATE IF NOT EXISTS dos comandos. O script de configuração pode ser executado várias vezes durante a instalação e atualização e nos casos em que ocorrer um erro. Nessas situações, por exemplo, um esquema com versão pode não estar vazio.
CREATE SCHEMA não altera o contexto da sessão, portanto, os objetos devem ser qualificados com o esquema de destino quando 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
Objetos de esquema com versão podem se referir a objetos sem versão e vice-versa. Você deve considerar a possibilidade de falha quando o script de configuração estiver em execução. Dado que o script de configuração foi escrito para ser idempotente, ele será executado automaticamente novamente se a execução inicial falhar.

Considere isso ao conceder funções de aplicativo em um esquema. Por exemplo, considere usar o seguinte:
```
CREATE OR REPLACE PROCEDURE app_state.proc()...;
-- Additional CREATE statements
GRANT USAGE ON PROCEDURE app_state.proc()
   TO APPLICATION ROLE app_user;
```
Copy
A instrução CREATE OR REPLACE substitui o procedimento que remove implicitamente as concessões feitas anteriormente a esse procedimento. Embora as concessões sejam restauradas posteriormente no script, se o script falhar ao ser executado, os consumidores poderão perder a capacidade de acessar o procedimento.

Se o script de configuração falhar devido a um problema que não pode ser resolvido por uma nova tentativa, por exemplo, um erro de sintaxe, o consumidor não poderá acessar o procedimento até que uma nova versão ou patch seja atualizado e a concessão seja restaurada.
As exibições no conteúdo compartilhado sempre devem ser definidas no 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.
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.

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.