Atualização de um Snowflake Native App

O Snowflake Native App Framework permite que os provedores atualizem um Snowflake Native App para adicionar novas funcionalidades, corrigir bugs e fazer outras alterações. Este tópico descreve como adicionar versões e patches a um pacote de aplicativo. Ele também descreve como atualizar instâncias instaladas de um Snowflake Native App.

Sobre versões e patches

No contexto de Snowflake Native App Framework, versão e patch referem-se ao seguinte:

Versão

Geralmente contém atualizações importantes para um Snowflake Native App. As versões são definidas em um pacote de aplicativo. Um pacote de aplicativo só pode ter duas versões ativas ao mesmo tempo. Para adicionar uma nova versão a um pacote de aplicativo que já possui duas versões definidas, você deve primeiro descartar uma das versões.

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. Embora um pacote de aplicativo possa conter apenas duas versões ativas por vez, uma única versão pode ter vários patches.

Nota

Uma única versão pode ter até 130 patches.

Quando um provedor adiciona uma nova versão a um pacote de aplicativo, a nova versão recebe automaticamente o patch 0. Quando um provedor adiciona um novo patch a uma versão, ele pode especificar manualmente o número do patch. Se nenhum número de patch for fornecido, o Snowflake incrementará automaticamente a versão do patch em 1.

Depois de adicionar uma versão ou patch a um pacote de aplicativo, você poderá testar as alterações localmente criando um objeto de aplicativo com base na versão ou patch. Consulte Criação de um objeto de aplicativo de uma versão ou nível de patch para obter mais informações.

Nota

Cada versão e patch definidos em um pacote de aplicativo devem ter sua própria versão do script de configuração e dos arquivos do aplicativo.

Diferenças entre versões e patches

Quando um provedor publica uma nova versão de um aplicativo, o Snowflake Native App Framework garante que apenas a versão anterior do aplicativo esteja ativa. Por exemplo, se um provedor publicou V1 e V2 de um aplicativo, o Snowflake Native App Framework garante que apenas V2 esteja atualmente instalado em uma conta de consumidor antes de atualizar para V3. Isso garante que o script de configuração tenha apenas em conta as diferenças entre V2 e V3. Em outras palavras, o script de configuração é compatível apenas com a versão mais recente do aplicativo. Se um provedor fizer uma alteração de estado no aplicativo, por exemplo, criando uma nova tabela ou adicionando colunas a uma tabela, não haverá problemas de compatibilidade entre versões.

Por outro lado, quando um provedor publica um novo patch para uma versão de um aplicativo, o Snowflake Native App Framework não impõe nenhuma restrição ao número de patches ativos em execução. Os provedores devem evitar fazer alterações no estado de um aplicativo em um patch.

Sobre as diretrizes de versão

Uma diretriz de versão especifica a versão e, opcionalmente, o patch usado quando um consumidor instala um Snowflake Native App. As diretrizes de versão também são usadas para acionar uma atualização automatizada em todas as instâncias instaladas de uma versão ou patch específico.

As diretrizes de versão são definidas no pacote de aplicativo. Há dois tipos de diretrizes de versão:

Diretriz de versão personalizada

Permite que um provedor especifique a versão de um aplicativo que as contas específicas Snowflake podem instalar. Consulte Adição de uma diretriz de versão personalizada para obter mais informações.

Diretriz de versão padrão

Especifica a versão e o patch aplicáveis a todos os consumidores ao instalar um Snowflake Native App. Se um provedor criar versões V1 e V2 de um aplicativo, definir a diretriz de versão padrão como V2 garante que quando um consumidor instalar o Snowflake Native App, ele instalará a versão V2. Consulte definição de uma diretriz de versão padrão para obter mais informações.

Se um provedor criar as versões V2 e V3 de um aplicativo, ele poderá atribuir a V2 como a versão padrão e criar uma diretriz de versão personalizada para compartilhar a V3 somente com contas específicas. Um provedor também pode compartilhar a versão V3 do aplicativo com uma conta de teste antes de publicar essa versão.

Nota

Se você especificar uma diretriz de versão padrão e personalizada, a diretriz de versão personalizada sempre terá precedência. No exemplo acima, as contas de consumidor especificadas na diretriz de versão personalizada só poderiam instalar a V3 do aplicativo.

Você deve definir uma diretriz de versão em um pacote de aplicativo antes de poder executar as seguintes tarefas:

  • Crie uma listagem pública com o pacote de aplicativo como conteúdo de dados.

  • Instale um Snowflake Native App em uma conta de consumidor.

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, por exemplo, uma correção de bug, para um consumidor.

Quando uma nova versão ou patch está disponível, o provedor modifica a diretriz de versão no pacote de aplicativo e, em seguida, notifica o consumidor de que uma nova versão está disponível. O consumidor então realiza o upgrade executando o comando ALTER APPLICATION para realizar o upgrade. Em geral, os upgrades manuais permitem que o consumidor atualize o aplicativo instalado mais rapidamente do que os upgrades automatizados.

Para obter informações sobre o fluxo de trabalho para realizar um upgrade, consulte Upgrade de um Snowflake Native App.

Sobre upgrades entre regiões

Consulte Upgrade de um aplicativo instalado em várias regiões para obter informações sobre como fazer o upgrade de um aplicativo instalado entre regiões.

Adição de uma versão ou patch a um pacote de aplicativo

As informações de versão de um aplicativo são especificadas no pacote do aplicativo.

Privilégios necessários para adicionar ou remover versões e patches

Para especificar uma versão ou patch para um pacote de aplicativo, você deve ter um dos seguintes privilégios concedidos no pacote de aplicativo para sua função:

  • OWNERSHIP

  • MANAGE VERSIONS

Por exemplo, para conceder o privilégio MANAGE VERSION no pacote de aplicativo à função release_mgr, use o comando GRANT <privilégios> conforme mostrado no exemplo a seguir:

GRANT MANAGE VERSIONS ON APPLICATION PACKAGE hello_snowflake_package
  TO ROLE release_mgr;
Copy

Adição de uma versão a um pacote de aplicativo usando SQL

O exemplo a seguir mostra como usar o comando ALTER APPLICATION PACKAGE para adicionar uma versão a um pacote de aplicativo.

ALTER APPLICATION PACKAGE MyAppPackage
  ADD VERSION v1_0
  USING '@dev_stage/v1_0'
  LABEL = 'MyApp Version 1.0';
Copy

Neste exemplo, v1_0 é um identificador para a versão que não fica visível para os consumidores quando eles instalam o aplicativo. O consumidor vê as informações da versão conforme definido na cláusula LABEL.

Apenas duas versões de um aplicativo podem existir ao mesmo tempo. Por exemplo, se você definir v1_0 e v1_1 em um aplicativo, deverá descartar v1_0 para criar v1_2. No entanto, você pode ter vários patches para uma única versão.

Você pode definir o nome da versão e o rótulo no arquivo manifest.yml, ou especifique-os diretamente com o comando ALTER APPLICATION PACKAGE. Se você os definir no arquivo manifest.yml, bem como com o comando SQL, os valores especificados no comando SQL tem precedência sobre os valores especificados no arquivo manifest.yml.

Adição de um patch a um pacote de aplicativo usando SQL

Além de criar versões para um aplicativo, você também pode criar patches para uma versão específica. Assim como as versões, os patches de aplicativo também têm seus próprios arquivos de aplicativo.

Para criar um novo patch para um pacote de aplicativo, use a cláusula ADD PATCH FOR VERSION do comando ALTER APPLICATION PACKAGE … VERSION, conforme o exemplo a seguir:

ALTER APPLICATION PACKAGE MyAppPackage
 ADD PATCH FOR VERSION V1_0
 USING '@dev_stage/v1_0_p1;
Copy

No exemplo, nenhum número de patch é fornecido para a cláusula ADD PATCH FOR VERSION V1_0. Neste caso, o Snowflake incrementa automaticamente o número do patch em 1.

Para criar um novo patch para um aplicativo com número de patch personalizado, forneça o número de patch na cláusula ADD PATCH FOR VERSION do comando ALTER APPLICATION PACKAGE … VERSION, conforme mostrado no exemplo a seguir:

ALTER APPLICATION PACKAGE MyAppPackage
 ADD PATCH 3
 FOR VERSION V1_0
 USING '@dev_stage/v1_0_p1;
Copy

Exibição das versões e patches para um pacote de aplicativo

Como provedor, você pode visualizar as versões e patches definidos para um aplicativo executando o comando SHOW VERSIONS no pacote de aplicativo.

O comando a seguir exibe as versões e patches que foram definidos para um pacote de aplicativo chamado hello_snowflake_package:

SHOW VERSIONS IN APPLICATION PACKAGE hello_snowflake_package;
Copy

Remoção de uma versão de um pacote de aplicativo

Para remover uma versão de um pacote de aplicativo, você deve verificar se não há diretrizes de versão apontando atualmente para a versão que você deseja remover.

Para visualizar as diretrizes de versão especificadas em um pacote de aplicativo, execute o comando SHOW RELEASE DIRECTIVES conforme mostrado no exemplo a seguir:

SHOW RELEASE DIRECTIVES IN APPLICATION PACKAGE hello_snowflake_package;
Copy

Para remover uma versão de um pacote de aplicativo, use a cláusula DROP VERSION do comando ALTER APPLICATION PACKAGE como mostrado no exemplo a seguir:

ALTER APPLICATION PACKAGE hello_snowflake_package
  DROP VERSION v1_0;
Copy

Depois de executar este comando, a versão não será descartada até que todas as instâncias instaladas do aplicativo sejam descartadas. Para verificar o status do comando drop, use SHOW VERSIONS conforme mostrado no exemplo a seguir:

SHOW VERSIONS IN APPLICATION PACKAGE hello_snowflake_package;
Copy

A coluna dropped_on lista o carimbo de data/hora em que o descarte foi iniciado.

Nota

A versão descartada só aparece na saída deste comando enquanto o status for DROPPED. Quando todas as instâncias instaladas do aplicativo forem descartadas, a versão descartada não aparecerá mais.

Quando uma versão é descartada, os consumidores não podem mais instalar novas instâncias dessa versão do aplicativo.

Dependendo de como o aplicativo é publicado para os consumidores, pode levar diferentes períodos para que a versão seja descartada:

  • Se o pacote de aplicativo não tiver sido publicado para os consumidores, a versão será descartada imediatamente.

  • Se o pacote de aplicativo tiver sido publicado como uma listagem pública ou privada em uma única região, a versão será descartada imediatamente.

  • Se o pacote de aplicativo for publicado como produto de dados de uma listagem compartilhada na mesma região que o pacote de aplicativo, a versão será descartada em algumas horas.

  • Se o pacote de aplicativo for publicado como produto de dados de uma listagem usando o preenchimento automático entre nuvens, poderá levar mais tempo para que a versão seja descartada em todas as regiões.

Definição da diretriz de versão para um pacote de aplicativo

Depois de adicionar uma versão a um pacote de aplicativo, você pode especificar as diretrizes de versão para o pacote de aplicativo. As diretrizes de versão determinam a versão do aplicativo que está disponível para um consumidor quando ele instala o aplicativo ou quando um aplicativo instalado é atualizado automaticamente.

Privilégios necessários para definir a diretriz de versão

Para definir uma diretriz de versão, um provedor deve ter o privilégio MANAGE RELEASES ou propriedade do pacote de aplicativo.

GRANT MANAGE RELEASES ON APPLICATION PACKAGE hello_snowflake_package
  TO ROLE release_mgr;
Copy

Definição da diretriz de versão padrão para um pacote de aplicativo

Use o comando ALTER APPLICATION PACKAGE com SET DEFAULT RELEASE DIRECTIVE para definir a diretriz de versão padrão, conforme mostrado no exemplo a seguir:

ALTER APPLICATION PACKAGE hello_snowflake_package
  SET DEFAULT RELEASE DIRECTIVE
  VERSION = v1_0
  PATCH = 2;
Copy

Para atualizar a diretriz de versão padrão para um pacote de aplicativo, execute o comando ALTER APPLICATION PACKAGE com SET DEFAULT RELEASE DIRECTIVE novamente, especificando novos valores para VERSION ou PATCH, conforme apropriado.

Definição de uma diretriz de versão personalizada para um pacote de aplicativo

Para adicionar uma diretriz de versão personalizada, use o comando ALTER APPLICATION PACKAGE com SET RELEASE DIRECTIVE. Use a cláusula ACCOUNTS para especificar as contas às quais esta diretriz de versão se aplica. Por exemplo:

ALTER APPLICATION PACKAGE hello_snowflake_package
  SET RELEASE DIRECTIVE hello_snowflake_package_custom
  ACCOUNTS = (CONSUMER_ORG.CONSUMER_ACCOUNT)
  VERSION = v1_0
  PATCH = 0;
Copy

Atualização de uma diretriz de versão personalizada

Para atualizar a versão ou patch para uma diretriz de versão personalizada, use o comando ALTER APPLICATION PACKAGE com MODIFY RELEASE DIRECTIVE como mostrado no exemplo a seguir:

ALTER APPLICATION PACKAGE hello_snowflake_package
  MODIFY RELEASE DIRECTIVE hello_snowflake_package_custom
  VERSION = v1_0
  PATCH = 0;
Copy

No entanto, você não pode modificar as contas associadas à diretriz de versão. Para alterar a organização e a conta associadas a uma diretriz de versão, faça o seguinte:

  1. Remova a diretriz de versão do pacote de aplicativo executando o comando ALTER APPLICATION PACKAGE com UNSET RELEASE DIRECTIVE.

  2. Adicione a diretriz de versão de volta ao pacote de aplicativo executando o comando ALTER APPLICATION PACKAGE com SET RELEASE DIRECTIVE e usando a cláusula ACCOUNTS para especificar a lista de contas.

Nota

Ao alterar a organização e a conta associadas à diretriz de versão, certifique-se de adicionar a nova versão diretamente imediatamente após remover a antiga. Caso contrário, os aplicativos instalados para as contas atribuídas à diretriz de versão personalizada serão revertidos para a diretriz de versão padrão.

Remoção de uma diretriz de versão personalizada

Para remover uma diretriz de versão personalizada de um pacote de aplicativo, use o comando ALTER APPLICATION PACKAGE com UNSET RELEASE DIRECTIVE como mostrado no exemplo a seguir:

ALTER APPLICATION PACKAGE hello_snowflake_package
  UNSET RELEASE DIRECTIVE hello_snowflake_package_custom;
Copy

Teste de uma versão e patch usando uma diretriz de versão

Ao instalar um aplicativo de um pacote de aplicativo no modo de desenvolvimento, a versão e o patch são explicitamente especificados. No entanto, quando o aplicativo é instalado usando o seguinte comando:

CREATE APPLICATION hello_snowflake
  FROM APPLICATION PACKAGE hello_snowflake_package
Copy

A diretriz de versão determina a versão instalada ao executar este comando.

Upgrade de um Snowflake Native App

Um upgrade é iniciado quando o provedor define ou altera a diretriz de versão no pacote de aplicativo.

Fluxo de trabalho para fazer o upgrade de um Snowflake Native App

Um provedor faz o upgrade de um aplicativo instalado usando o seguinte fluxo de trabalho:

  1. Atualize lógica do aplicativo e o script de configuração do pacote de aplicativo.

  2. Se houver duas versões definidas atualmente, remova uma versão do pacote de aplicativo.

  3. Crie uma nova versão ou patch para as alterações no pacote de aplicativo.

    Se a propriedade DISTRIBUTION do aplicativo estiver definida como EXTERNAL, a verificação de segurança automatizada será iniciada. A verificação de segurança deve passar antes que o upgrade possa ocorrer.

  4. Teste a nova versão criando um objeto APPLICATION na conta de teste do provedor.

  5. Atualize a diretriz de versão da versão ou patch.

    Isso inicia um upgrade automatizado que atualizará todas as instâncias instaladas da versão anterior. Um provedor pode notificar o consumidor de que um upgrade está disponível e solicitar que ele execute manualmente um upgrade manual.

Nota

Depois de fazer o upgrade de um pacote de aplicativo, as alterações no Snowflake Native App instalado na conta do consumidor podem não ficar visíveis até que a atualização para regiões remotas seja executada.

Você pode usar a exibição APPLICATION_STATE no esquema DATA_SHARING_USAGE para monitorar o status. Se o upgrade não for concluído mais de 1 dia após a primeira atualização após o upgrade, poderá haver um problema no processo de atualização. Entre em contato com o suporte Snowflake.

Upgrade de um aplicativo instalado em várias regiões

Se um provedor publicar um Snowflake Native App usando o preenchimento automático entre nuvens, os upgrades automatizados poderão demorar um pouco para serem atualizados, dependendo dos seguintes fatores:

  • O valor do agendamento de atualização.

  • O número de instâncias instaladas do aplicativo.

  • O número de regiões onde o aplicativo está implantado.

Se o upgrade contiver uma correção urgente que precise ser atualizada em uma região remota, os provedores poderão considerar as seguintes maneiras de realizar um upgrade mais rapidamente:

Execução de um upgrade manual para um aplicativo instalado

Os upgrades manuais permitem que um consumidor inicie o upgrade de uma versão instalada ou patch de um aplicativo usando a diretriz de versão especificada no pacote de aplicativo.

Para fazer o upgrade de um Snowflake Native App instalado para a versão mais recente disponível, um consumidor pode usar a cláusula UPGRADE do comando ALTER APPLICATION para modificar o objeto do aplicativo:

ALTER APPLICATION <name> UPGRADE
Copy

Exibição do status de um upgrade

Para exibir o estado do upgrade de um aplicativo, use a exibição do sistema Exibição APPLICATION_STATE conforme mostrado no exemplo a seguir:

SELECT * FROM snowflake.data_sharing_usage.APPLICATION_STATE
Copy

Essa exibição inclui colunas específicas para upgrades, incluindo o estado do upgrade e a região onde o aplicativo está implantado.