Tutorial 3: Atualize um aplicativo com contêineres¶

Tutoriais de pré-requisito¶

Este tutorial pressupõe que você saiba como desenvolver um Snowflake Native App básico e possa criar um Snowflake Native App with Snowpark Container Services. Este tutorial se baseia no conhecimento adquirido ao concluir os tutoriais a seguir:

• Tutorial 1: Crie um Snowflake Native App básico

• Tutorial 2: Crie um aplicativo com contêineres

Antes de seguir este tutorial para atualizar um aplicativo com contêineres, certifique-se de ter concluído esses dois tutoriais.

O que você aprenderá neste tutorial¶

Este tutorial expande o aplicativo com os contêineres que você criou em Tutorial 2: Crie um aplicativo com contêineres. Neste tutorial, você aprenderá a:

• Usar a função de retorno de chamada do inicializador de versão para lidar com atualizações e falhas de serviço.

• Criar definições de versão para um aplicativo.

• Atualizar um aplicativo.

• Simular a falha de upgrade de um aplicativo.

• Criar um patch para o aplicativo para corrigir a falha.

Descarte do objeto do aplicativo¶

Se o aplicativo que você criou ao trabalhar em Tutorial 2: Crie um aplicativo com contêineres ainda existir na sua conta, será necessário descartar o objeto do aplicativo antes de prosseguir com este tutorial.

1. Para determinar se o aplicativo do tutorial anterior (na_spcs_tutorial_app) existe em sua conta, execute o seguinte comando em uma planilha:

   SHOW APPLICATIONS LIKE 'na_spcs_tutorial_app';
   

   Copy

2. Se o aplicativo na_spcs_tutorial_app aparecer na saída desse comando, descarte o aplicativo executando os seguintes comandos em uma planilha:

   USE ROLE tutorial_role;
   DROP APPLICATION IF EXISTS na_spcs_tutorial_app CASCADE;
   

   Copy

O que você concluiu nesta seção¶

Nesta seção, você verificou que os arquivos do aplicativo e os objetos do Snowflake do tutorial anterior ainda estão funcionando na sua conta.

Na próxima seção, você saberá mais sobre versões e upgrades no Snowflake Native App Framework.

Sobre versões e patches¶

As versões no Snowflake Native App Framework são combinações de números de versão e patch. Elas são definidas no pacote do aplicativo.

. rst-class:: bulleted-definition-list

Versão

Geralmente contém atualizações importantes para um Snowflake Native App. As versões são definidas em um pacote de aplicativo.

Patch

Geralmente contém atualizações menores para Snowflake Native App. Assim como as versões, os patches são definidos no pacote de aplicativo.

Sobre upgrades¶

No contexto de Snowflake Native App Framework, upgrades são atualizações para uma versão ou patch de um Snowflake Native App instalado na conta do consumidor. O Snowflake Native App Framework oferece suporte a dois tipos de upgrades:

Upgrades automatizados

Upgrades automatizados são atualizações iniciadas pelo provedor. Quando uma nova versão ou patch está disponível, o provedor modifica a diretriz de versão no pacote de aplicativo. Isso aciona um upgrade automático de todas as instâncias instaladas do aplicativo especificado pela diretriz de versão.

Upgrades manuais

Upgrades manuais são atualizações iniciadas pelo consumidor em resposta à comunicação do provedor. Os upgrades manuais são úteis quando um provedor precisa lançar rapidamente uma atualização, tais como uma correção de bug, para um consumidor.

Nota

Este tutorial descreve como realizar uma atualização manual de um aplicativo com contêineres.

Quando uma nova versão ou patch está disponível, o provedor modifica a diretriz de versão no pacote do aplicativo e, em seguida, notifica o consumidor de que uma nova versão está disponível.

O consumidor realiza a atualização executando o comando ALTER APPLICATION em sua conta para realizar a atualização. Em geral, os upgrades manuais permitem que o consumidor atualize o aplicativo instalado mais rapidamente do que os upgrades automatizados.

Sobre o inicializador de versão¶

Um inicializador de versão é usado para iniciar ou atualizar serviços ou outros processos relacionados. O inicializador de versão é um procedimento armazenado de retorno de chamada definido no arquivo de manifesto e implementado no script de configuração. A função de retorno de chamada do inicializador de versão é invocada nos seguintes contextos:

• Durante a instalação, o inicializador de versão é chamado assim que o script de configuração do aplicativo termina sem erros.

• Durante a atualização, há dois cenários possíveis em que o inicializador de versão é chamado:

  • Se o script de configuração da nova versão for bem-sucedido, a nova versão do inicializador de versão será chamada.

  • Se o script de configuração ou o inicializador de versão da nova versão falhar, o inicializador de versão da versão anterior será chamado. Isso permite que o inicializador de versão da versão anterior use o comando ALTER SERVICE para reverter os serviços para a versão anterior.

Como adicionar o inicializador de versão ao arquivo de manifesto¶

O inicializador de versão é definido no arquivo de manifesto do aplicativo. Para definir o inicializador de versão, adicione o seguinte código ao final do arquivo manifest.yml:

lifecycle_callbacks:
  version_initializer: app_public.version_init

Isso especifica o esquema e o nome do procedimento armazenado usado como inicializador de versão. Na próxima seção, implemente o procedimento armazenado version_init.

Como adicionar o inicializador de versão como um procedimento armazenado ao script de configuração¶

Na seção anterior, você adicionou o nome do inicializador de versão ao arquivo de manifesto. Nesta seção, você adiciona o código do procedimento armazenado ao script de configuração.

1. Adicione o seguinte código no final do arquivo setup_script.sql:

CREATE OR REPLACE PROCEDURE app_public.version_init()
RETURNS STRING
LANGUAGE SQL
AS
$$
DECLARE
can_create_compute_pool BOOLEAN;  -- Flag to check if 'CREATE COMPUTE POOL' privilege is held
BEGIN
-- Check if the account holds the 'CREATE COMPUTE POOL' privilege
   SELECT SYSTEM$HOLD_PRIVILEGE_ON_ACCOUNT('CREATE COMPUTE POOL')
      INTO can_create_compute_pool;

   ALTER SERVICE IF EXISTS core.echo_service
      FROM SPECIFICATION_FILE = 'service/echo_spec.yaml';
   IF (can_create_compute_pool) THEN
      -- When installing app, the app has no 'CREATE COMPUTE POOL' privilege at that time,
      -- so it will not execute the code below

      -- Since the ALTER SERVICE is an async process, wait for the service to be ready
      SELECT SYSTEM$WAIT_FOR_SERVICES(120, 'core.echo_service');
   END IF;
   RETURN 'DONE';
END;
$$;

Como carregar os arquivos alterados e criar uma versão¶

Depois de modificar o script de configuração, carregue os arquivos modificados no estágio e crie uma versão executando o procedimento a seguir:

1. Execute o seguinte comando para carregar os arquivos e criar uma versão:

   snow app version create v1 -c tut-connection
   

   Copy

O comando snow app version carrega os arquivos atualizados para o estágio. Se o pacote do aplicativo e os arquivos já existirem, esse comando só carregará os arquivos que foram alterados.

Esse comando cria uma nova versão do aplicativo chamada v1 com o patch padrão definido como 0.

Como definir a diretriz de versão padrão para o aplicativo¶

Na seção anterior, você carregou os arquivos alterados e criou a versão v1 do aplicativo. Nesta seção, você define a diretriz de versão padrão para usar a versão v1.

Para atualizar a diretriz de versão padrão, execute o seguinte comando em uma planilha:

ALTER APPLICATION PACKAGE na_spcs_tutorial_pkg
  SET DEFAULT RELEASE DIRECTIVE VERSION=v1 PATCH=0;

Quando você define a diretriz de versão padrão para um aplicativo, os consumidores instalam automaticamente essa versão quando instalam o aplicativo em suas contas. Na próxima seção, você cria o aplicativo na sua conta local com base na diretriz de versão.

Criação e teste do aplicativo¶

Agora que você adicionou uma versão e definiu a diretriz de versão padrão, pode criar o aplicativo e conceder os privilégios necessários:

1. Crie o aplicativo a partir da diretriz de versão executando o seguinte comando:

   snow app run --from-release-directive -c tut-connection
   

   Copy

   Esse comando cria o aplicativo usando a diretriz de versão que você definiu na seção anterior.

2. Depois de criar o aplicativo, conceda os privilégios necessários ao aplicativo para que ele possa ser executado, executando os seguintes comandos em uma planilha.

   GRANT CREATE COMPUTE POOL ON ACCOUNT TO APPLICATION na_spcs_tutorial_app;
   GRANT BIND SERVICE ENDPOINT ON ACCOUNT TO APPLICATION na_spcs_tutorial_app;
   

   Copy

3. Chame o procedimento app_public.start_app que você definiu no arquivo setup_script.sql: executando o seguinte comando em uma planilha:

   CALL na_spcs_tutorial_app.app_public.start_app();
   

   Copy

4. Confirme que a função foi criada executando o seguinte comando em uma planilha:

   SHOW FUNCTIONS LIKE '%my_echo_udf%' IN APPLICATION na_spcs_tutorial_app;
   

   Copy

5. Para verificar se o serviço foi criado e está íntegro, execute o seguinte comando em uma planilha:

   CALL na_spcs_tutorial_app.app_public.service_status();
   

   Copy

6. Para chamar a função de serviço para enviar uma solicitação ao serviço e verificar a resposta, execute o seguinte comando em uma planilha:

   SELECT na_spcs_tutorial_app.core.my_echo_udf('hello');
   

   Copy

7. Para exibir informações sobre o aplicativo, execute o seguinte comando em uma planilha:

   DESC APPLICATION na_spcs_tutorial_app;
   

   Copy

Revisão do que você aprendeu nesta seção¶

Nesta seção, você realizou as seguintes tarefas:

• Aprendeu sobre o inicializador de versão e como podemos adicioná-lo ao arquivo de manifesto e ao script de configuração.

• Aprendeu os conceitos básicos de versões e patches no Snowflake Native App Framework.

• Definiu a diretriz de versão padrão para apontar para uma versão específica de um aplicativo.

• Instalou o aplicativo com base na diretriz de versão.

• Testou o aplicativo chamando um procedimento armazenado e usou o comando DESCRIBE APPLICATION para visualizar o status do aplicativo.

Como adicionar uma nova tabela ao aplicativo¶

Para simular a adição de um novo recurso ao seu aplicativo, adicione uma nova tabela ao script de configuração.

1. Adicione os seguintes comandos ao final do setup_script.yml

   CREATE TABLE IF NOT EXISTS core.setup_script_run(run_at TIMESTAMP);
   GRANT SELECT ON TABLE core.setup_script_run to APPLICATION ROLE app_user;
   INSERT INTO core.setup_script_run(run_at) values(current_timestamp());
   

   Copy

Como criar uma versão do aplicativo¶

Para carregar o script de configuração modificado no estágio e criar a versão v2 do aplicativo:

1. Execute o seguinte comando na pasta na-spcs-tutorial:

snow app version create v2 -c tut-connection

Esse comando cria uma nova versão do aplicativo chamada v2 com o patch padrão definido como 0.

O comando snow app version carrega os arquivos atualizados para o estágio. Se o pacote do aplicativo e os arquivos já existirem, esse comando só carregará os arquivos que foram alterados.

Como definir a diretriz de versão padrão para o aplicativo¶

Depois de criar a versão v2 do aplicativo, defina a diretriz de versão para o pacote do aplicativo executando o seguinte comando em uma planilha:

ALTER APPLICATION PACKAGE na_spcs_tutorial_pkg
  SET DEFAULT RELEASE DIRECTIVE VERSION=v2 PATCH=0;

Esse comando define a diretriz de versão para a versão v2 e o patch 0.

Atualização do aplicativo da v1 para a v2¶

Agora que você atualizou a diretriz de versão para apontar para a nova versão, atualize o aplicativo executando o seguinte comando em uma planilha:

snow app run --from-release-directive -c tut-connection

Como testar o aplicativo atualizado¶

Depois de atualizar o aplicativo, teste-o executando o seguinte comando em uma planilha:

SELECT na_spcs_tutorial_app.core.my_echo_udf('hello');

Revisão do que você aprendeu nesta seção¶

Parabéns! Você atualizou com sucesso o aplicativo da versão v1 para a versão v2.

Nesta seção, você realizou as seguintes tarefas:

• Atualizei o aplicativo para incluir uma tabela.

• Criei uma nova versão para o aplicativo com base nessa atualização.

• Atualizei a diretriz de versão padrão para apontar para a nova versão.

• Atualizei manualmente o aplicativo.

Na próxima seção, você atualiza o serviço do aplicativo e simula um erro no processo de atualização, adicionando intencionalmente um erro no script de configuração.

Atualização do arquivo de especificação do serviço¶

Nesta seção, o usuário atualiza a especificação do serviço do aplicativo para simular uma alteração no serviço.

1. No arquivo service/echo_spec.yaml, altere o valor de CHARACTER_NAME de Bob para Tom.

   Essa alteração faz com que o serviço retorne a seguinte mensagem:

   `Tom said hello.`
   

   Copy

O objetivo dessa alteração é permitir que você veja qual versão do serviço está em execução depois de tentar fazer um upgrade nas seções a seguir.

Atualização do script de configuração para incluir um erro intencional¶

Para simular um erro durante o processo de upgrade, introduza um erro intencional no script de configuração adicionando uma instrução SELECT para uma tabela que não existe.

Adicione a seguinte instrução ao final do procedimento app_public.version_init() no setup_script.sql.

SELECT * FROM table_does_not_exist;

Essa instrução está sintaticamente correta, mas se refere a uma tabela que não existe. Isso causa um erro quando o script de configuração é executado durante a atualização.

Depois de fazer essa alteração, a função app_public.version_init() deve se parecer com o exemplo a seguir:

GRANT USAGE ON PROCEDURE app_public.service_status() TO APPLICATION ROLE app_user;

CREATE OR REPLACE PROCEDURE app_public.version_init()
RETURNS STRING
LANGUAGE SQL
AS
$$
DECLARE
  -- Flag to check if 'CREATE COMPUTE POOL' privilege is held
  can_create_compute_pool BOOLEAN;
BEGIN
   -- Check if the account holds the 'CREATE COMPUTE POOL' privilege
   SELECT SYSTEM$HOLD_PRIVILEGE_ON_ACCOUNT('CREATE COMPUTE POOL')
     INTO can_create_compute_pool;

   ALTER SERVICE IF EXISTS core.echo_service
     FROM SPECIFICATION_FILE = 'service/echo_spec.yaml';
   IF (can_create_compute_pool) THEN
     -- When installing app, the app has no 'CREATE COMPUTE POOL' privilege at that time,
     -- so it will not execute the code below

     -- Since the ALTER SERVICE is an async process, wait for the service to be ready
     SELECT SYSTEM$WAIT_FOR_SERVICES(120, 'core.echo_service');
   END IF;

   -- trigger an error. The upgrade fails
   SELECT * FROM non_exist_table;

   RETURN 'DONE';
END;
$$;

Como carregar os arquivos revisados e criar um novo patch¶

Nas seções anteriores, você atualizou a especificação do serviço e o script de configuração do aplicativo.

Para carregar os arquivos e criar um novo patch para o aplicativo, execute as seguintes tarefas:

1. Execute o seguinte comando para adicionar um patch ao pacote do aplicativo.

snow app version create v2 --patch 1 -c tut-connection

1. Quando solicitado, digite y para adicionar um novo patch ao pacote do aplicativo.

Como definir a diretriz de versão padrão para o aplicativo¶

Na seção anterior, você carregou os arquivos e criou um patch para as atualizações. Para definir a diretriz de versão padrão para o patch, execute o seguinte comando em uma planilha:

ALTER APPLICATION PACKAGE na_spcs_tutorial_pkg
  SET DEFAULT RELEASE DIRECTIVE VERSION=v2 PATCH=1;

Esse comando define o patch do aplicativo para o patch 1.

Atualização do aplicativo¶

Nas seções anteriores, você fez atualizações no aplicativo e criou um novo patch. Nesta seção, o usuário atualiza o aplicativo com a expectativa de que ele falhe devido ao erro introduzido nas seções anteriores.

Para atualizar o aplicativo, execute o seguinte comando:

snow app run --from-release-directive -c tut-connection

Para visualizar o estado de atualização do aplicativo, execute o seguinte comando em uma planilha:

DESC APPLICATION na_spcs_tutorial_app;

Esse comando exibe informações sobre o aplicativo, incluindo o estado da atualização, o número de tentativas da atualização e o motivo de uma falha no upgrade.

Após a falha do upgrade, o Snowflake CLI retorna a seguinte mensagem:

Object 'TABLE_DOES_NOT_EXIST' does not exist or not authorized.'

Além disso, após a falha do upgrade, o comando DESC APPLICATION exibe as seguintes propriedades relacionadas aos upgrades:

Propriedade	Valor
upgrade_state	FAILED
upgrade_failure_reason	upgrade_failure_reason[ErrorCode 2003] Uncaught exception of type “STATEMENT_ERROR” on line 89 at position 0 : Uncaught exception of type “STATEMENT_ERROR” on line 19 at position 3 : SQL compilation error: O objeto “TABLE_DOES_NOT_EXIST” não existe ou não foi autorizado.

Como executar o serviço do aplicativo para ver qual versão do serviço está em execução¶

Na seção anterior, você simulou uma falha ao fazer upgrade da versão v2, patch 0 para a versão v2, patch 1.

Para determinar qual versão do serviço está sendo executada no momento, execute o seguinte comando em uma planilha.

SELECT na_spcs_tutorial_app.core.my_echo_udf('hello');

Esse comando retorna a seguinte cadeia de caracteres:

Bob said hello

Aqui, você vê que, como a atualização falhou, o aplicativo continua a executar o serviço da v2, patch 0.

No entanto, se você não incluísse um inicializador de versão no aplicativo, o processo de atualização teria atualizado o serviço para a v2, patch 1, embora a atualização do aplicativo tenha falhado. Se uma atualização do aplicativo falhar, o inicializador de versão garante que a versão do serviço não seja atualizada e continue sincronizada com o aplicativo.

Revisão do que você aprendeu nesta seção¶

Nesta seção, você realizou as seguintes tarefas:

• Introduziu um erro no script de configuração para simular um erro no processo de atualização.

• Verificou a versão do aplicativo e do serviço após a falha.

• Aprendeu como o inicializador de versão garante que a versão de um serviço esteja em sincronia com a versão do aplicativo quando uma atualização falha.

Como modificar o script de configuração¶

Para corrigir o erro intencional que você introduziu em uma seção anterior, remova a seguinte instrução do arquivo setup_script.yaml:

SELECT * FROM table_does_not_exist;

Como carregar os arquivos atualizados e criar um novo patch¶

Para carregar o script de configuração modificado em um estágio e criar um novo patch, execute as seguintes tarefas:

1. Execute o seguinte comando para criar um novo patch para o aplicativo:

2. Quando solicitado, digite y para adicionar um novo patch ao pacote do aplicativo.

Como atualizar a diretriz de versão padrão¶

Na seção anterior, você criou o patch 2 para o aplicativo. Para definir a diretriz de versão padrão para o patch, execute o seguinte comando em uma planilha:

ALTER APPLICATION PACKAGE na_spcs_tutorial_pkg
  SET DEFAULT RELEASE DIRECTIVE VERSION=v2 PATCH=2;

Como atualizar o aplicativo e verificar a versão do serviço¶

Depois de criar uma nova versão e definir a diretriz de versão padrão, atualize o aplicativo e teste o serviço executando as seguintes tarefas:

1. Para atualizar o aplicativo da versão v2 patch 0 para a versão v2 patch 2, execute o seguinte comando:

   snow app run --from-release-directive -c tut-connection
   

   Copy

2. Para verificar a versão do serviço que está em execução no momento, execute o seguinte comando em uma planilha:

   SELECT na_spcs_tutorial_app.core.my_echo_udf('hello');
   

   Copy

3. Para visualizar o status do aplicativo, incluindo a versão instalada no momento, execute o seguinte comando:

   DESC APPLICATION na_spcs_tutorial_app;
   

   Copy

   Na saída, a propriedade version é v2 e a propriedade patch é 2.

Revisão do que você aprendeu nesta seção¶

Parabéns! Você atualizou o aplicativo com sucesso após a falha de atualização.

Nesta seção, você realizou as seguintes tarefas:

• Corrigiu o erro no script de configuração.

• Criou um novo patch, p2, para atualizar o aplicativo.

• Atualizou o aplicativo para o novo patch.

Resumo¶

Neste tutorial, você realizou as seguintes tarefas:

• Adicionou um procedimento armazenado de inicialização de versão para lidar com serviços durante upgrades e falhas.

• Criou uma nova definição de versão do aplicativo no pacote de aplicativo. As definições de versão especificam o número da versão e o patch do aplicativo.

• Definiu a diretriz de versão padrão para um aplicativo. As diretrizes de versão determinam qual versão e patch são instalados quando um consumidor instala ou atualiza um aplicativo.

• Atualizou um aplicativo e verificou o que acontece durante a falha de atualização.