Como usar o esquema com versão para gerenciar objetos de aplicativos entre versões¶

Sobre esquemas com versões¶

Os esquemas com versão são tipos especiais de esquemas de banco de dados projetados para lidar com objetos sem estado de uma versão para outra.

Um esquema com versão contém metadados sobre os objetos em um aplicativo que estão associados a uma versão específica. A fixação de versão é um recurso dos esquemas com versão que permite que um aplicativo saiba que trabalho, consultas etc. estão associados a esses objetos.

Quando um objeto em um esquema com controle de versão executa uma consulta, por exemplo, essa consulta é “fixada” na versão do aplicativo que está executando a consulta.

A fixação de versão é importante ao atualizar um aplicativo para uma nova versão. Considere o contexto em que V1 de um aplicativo executa uma consulta complexa que leva muito tempo para ser concluída.

Se ocorrer uma atualização enquanto essa consulta ainda estiver em execução, o estado de atualização do aplicativo será alterado para COMPLETE e o aplicativo será atualizado para v2. O estado da versão anterior muda para FINALIZING até que todos os trabalhos da versão v1 tenham sido concluídos.

Consulte Atualização de estados para obter mais informações sobre os estados de atualização de um aplicativo.

Restrições sobre esquemas com controle de versão¶

• O Snowpark Container Services não é compatível com esquemas com controle de versão.

• Os esquemas com controle de versão só estão disponíveis no contexto de um objeto de aplicativo. Eles são criados apenas no script de configuração. Cada versão de um aplicativo tem seu próprio script de configuração e contém um esquema com controle de versão específico para essa versão.

• Um esquema com controle de versão só pode ser usado no script de configuração de um pacote do aplicativo. Eles só podem ser criados no contexto de um objeto de aplicativo.

• Não há suporte para tarefas em esquemas com controle de versão. Por exemplo, os provedores não podem incluir tags ao criar ou alterar um esquema com controle de versão. No entanto, os provedores podem usar tags dentro de um esquema com controle de versão, desde que apliquem apenas esses objetos de tags dentro de um esquema com versão no mesmo aplicativo.

• Não há suporte para tags e políticas de mascaramento em esquemas com controle de versão.

• Não há suporte para concessões e concessões futuras em esquemas com controle de versão.

• Os esquemas com controle de versão não podem ser usados como origem ou destino de uma operação de clonagem.

• Não há suporte para o descarte de um esquema com controle de versão. O descarte de um esquema com controle de versão eliminaria todas as versões dos objetos que ele contém e afetaria as consultas executadas em versões ou patches mais antigos do aplicativo.

Implementação interna de esquemas com controle de versão¶

Internamente, os esquemas com controle de versão contêm subesquemas que correspondem a cada versão do aplicativo.

No entanto, esses subesquemas não são diretamente acessíveis ao consumidor dentro do objeto do aplicativo. Um consumidor só verá objetos no esquema com controle de versão que correspondam à versão do aplicativo que ele instalou em sua conta.

Por exemplo, se um consumidor usar o comando SHOW OBJECTS para visualizar os objetos em um esquema com versão, ele verá apenas os objetos da versão que está usando no momento.

Ao escrever o script de configuração, os provedores devem recriar os objetos em um esquema com versão usando CREATE OR REPLACE ou CREATE IF NOT EXISTS. Isso é importante porque, internamente, cada versão do aplicativo tem seus próprios objetos dentro do subesquema do esquema com controle de versão.

Uso de esquemas com e sem controle de versão no script de configuração¶

Para gerenciar o estado de um aplicativo durante as atualizações, o Snowflake Native App Framework usa esquemas com controle de versão. Um esquema com controle de versão é semelhante a um esquema de banco de dados comum, com funcionalidade adicional para lidar com várias versões de objetos criados por diferentes versões de aplicativos.

Os esquemas com controle de versão só estão disponíveis no contexto de um objeto de aplicativo. Eles são criados apenas no script de configuração. Cada versão de um aplicativo tem seu próprio script de configuração e contém um esquema com controle de versão específico para essa versão.

Ao desenvolver uma nova versão de um aplicativo, os provedores devem levar em conta as alterações nos objetos que o aplicativo cria usando o script de configuração.

O exemplo a seguir mostra uma situação comum em que tanto o esquema normal quanto o com controle de versão podem ser usados em um script de configuração para criar componentes com e sem estado:

CREATE OR ALTER VERSIONED SCHEMA stateless_objects;
CREATE OR REPLACE PROCEDURE stateless_object.py_echo_proc(STR string)
  RETURNS STRING
  LANGUAGE PYTHON
  RUNTIME_VERSION=3.8
  PACKAGES=('snowflake-snowpark-python')
  HANDLER='echo.echo_proc'
  IMPORTS=('/libraries/echo.py');

CREATE OR ALTER SCHEMA stateful_object;
CREATE TABLE stateful_object.config_props
  prop_name STRING;
  prop_value STRING;
  time_stamp TIMESTAMP;

Criação de um esquema com controle de versão¶

Para criar um esquema com controle de versão com o script de configuração, use o comando CREATE OR ALTER VERSIONED SCHEMA, conforme mostrado no exemplo a seguir:

CREATE OR ALTER VERSIONED SCHEMA version_schema;

Uso de esquemas sem controle de versão para objetos com estado¶

Os objetos dentro de um aplicativo podem precisar preservar o estado entre as versões. Por exemplo, os dados de configuração ou os dados coletados durante a execução do aplicativo podem ser preservados.

Esses tipos de objetos devem residir em um esquema de banco de dados normal e devem ser criados para persistir durante a instalação inicial e as atualizações.

O exemplo a seguir mostra como criar um objeto com estado no script de configuração:

CREATE SCHEMA IF NOT EXISTS stateful_object;

CREATE TABLE IF NOT EXISTS stateful_object.config (
  config_param STRING,
  config_value STRING,
  default_value STRING,
  modified_on  TIMESTAMP);

ALTER TABLE stateful_object.config
  ADD COLUMN IF NOT EXISTS modified_on TIMESTAMP;

Neste exemplo, o script de configuração define uma tabela de configuração que persistiria de uma versão de um aplicativo para outra. Se a versão anterior do aplicativo não tiver uma coluna modified_on, o script de configuração tentará primeiro criar totalmente a tabela (no caso da instalação inicial) ou modificar a tabela existente adicionando a coluna (no caso de uma atualização).

Uso de esquemas com controle de versão para objetos sem estado¶

Alguns objetos em um aplicativo não mantêm o estado entre as versões de um aplicativo. Por exemplo, o código que define a lógica do aplicativo, incluindo procedimentos armazenados, funções etc., pode ser totalmente recriado no script de configuração sem perder nenhum dado ou estado do usuário.

A Snowflake recomenda que esses objetos estejam contidos em um esquema com versão.

O exemplo a seguir mostra como criar uma UDF em um esquema com controle de versão.

CREATE OR ALTER VERSIONED SCHEMA stateless_object;
CREATE FUNCTION IF NOT EXISTS stateless_object.add(x int, y int)
  RETURNS INT
  LANGUAGE SQL
  AS $$ x + y $$;

Fixação de versão¶

Um esquema com versão contém metadados sobre quais objetos em um Snowflake Native App estão associados a uma versão específica. A fixação de versão é um recurso dos esquemas com versão que permite que um aplicativo saiba que trabalho, consultas etc. estão associados a esses objetos.

Quando um objeto em um esquema com controle de versão executa uma consulta, por exemplo, essa consulta é “fixada” na versão do aplicativo que está executando a consulta.

A fixação de versão é importante ao atualizar um aplicativo para uma nova versão. Considere o contexto em que V1 de um aplicativo executa uma consulta complexa que leva muito tempo para ser concluída. Se ocorrer uma atualização enquanto essa consulta ainda estiver em execução, o aplicativo não será atualizado até que a consulta seja concluída.