Controle de versão, aplicação de patches e atualização de um aplicativo

Este tópico descreve como adicionar versões e patches a um aplicativo criado usando o Native Apps Framework. Este tópico também descreve como usar o esquema com versão para garantir a atualização perfeita dos arquivos do aplicativo e do script de configuração de seu aplicativo.

Sobre versões, patches e atualizações

O Native Framework fornece funcionalidade que permite atualizar seu aplicativo ou corrigir problemas. Ele também fornece uma maneira de atualizar um aplicativo sem problemas depois que ele é instalado em uma conta de consumidor.

Sobre versões e patches

Em geral, use novas versões para introduzir novos recursos ou mudanças de comportamento em um aplicativo. O processo de atualização (e reversão) de uma versão principal para outra versão principal garante que nenhum código possa ser executado a partir de uma versão anterior. Isso significa que o script de configuração precisa ser compatível apenas com a versão principal imediatamente anterior.

Os patches são considerados versões completas do aplicativo, o que significa que são definidos por um script de configuração exatamente da mesma maneira que uma versão principal. Ao contrário das atualizações de versão completa, no entanto, não há restrições quanto à ordem em que o provedor pode instalá-las nem quantos patches podem ter o código em execução ao mesmo tempo.

Vários patches podem ser adicionados a uma determinada versão. Ao contrário das versões, não há nada que restrinja a instalação de um patch na versão atualmente instalada. Isso significa que é possível que o código seja executado simultaneamente a partir de vários patches diferentes quando instalados em rápida sucessão. Isso também significa que uma nova versão precisa ser compatível com todos os possíveis patches em execução da versão anterior.

Criação de versões e patches

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

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

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

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, conforme o exemplo a seguir:

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

Quando você adiciona a primeira versão a um pacote de aplicativo, essa versão recebe o patch 0. À medida que você adiciona patches adicionais, o Snowflake aumenta o número do patch em 1.

Nota

Você não pode especificar o número do patch sozinho. O Snowflake gerencia os números de patch internamente.

Visualizaçã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 HelloSnowflakePackage:

SHOW VERSIONS IN APPLICATION PACKAGE HelloSnowflakePackage;
Copy

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

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 HelloSnowflakePackage
  DROP VERSION v1_0;
Copy

Nota

A eliminação de uma versão que está sendo usada atualmente por um aplicativo instalado pode fazer com que essa versão se torne inutilizável até que o aplicativo instalado seja atualizado.

Este comando não é concluído até que todos os aplicativos sejam atualizados para uma nova versão. Tome cuidado ao descartar uma versão que está em uso em uma conta de consumidor.

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

Depois de adicionar versões a um pacote de aplicativo, você pode especificar a diretriz 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.

Sobre as diretrizes de versão

Você pode definir uma diretriz de versão padrão para um pacote de aplicativo. A diretriz de versão padrão especifica a versão aplicável a todos os consumidores ao instalar um aplicativo. Por exemplo, se você criou uma V1 e uma V2 de um aplicativo, definir a diretriz de versão padrão como V2 garante que, quando um consumidor instalar o aplicativo, ele instale a versão v2.

Você também pode adicionar uma diretriz de versão personalizada a um pacote de aplicativo. As diretrizes de versão personalizadas permitem que você especifique a versão de um aplicativo que contas específicas Snowflake podem instalar.

Por exemplo, se você criar V2 e V3 de um aplicativo, poderá atribuir V2 como a versão padrão e criar uma diretriz de versão personalizada para compartilhar V3 com contas específicas. Um caso de uso comum para diretrizes de versão personalizadas é compartilhar um aplicativo com a conta do consumidor que você usa para teste.

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 para um pacote de aplicativo para poder fazer o seguinte:

  • Instale um aplicativo na conta do consumidor.

  • Crie uma listagem privada para um pacote de aplicativo.

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

A especificação de diretrizes de versão requer o privilégio MANAGE RELEASES ou propriedade do pacote de aplicativo.

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

Configuraçã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 HelloSnowflakePackage
  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 e PATCH.

Adição de uma diretriz de versão personalizada a 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 HelloSnowflakePackage
  SET RELEASE DIRECTIVE HelloSnowflakePackage_Custom
  ACCOUNTS = (CONSUMER_ORG.CONSUMER_ACCOUNT)
  VERSION = v1_0
  PATCH = 0;
Copy

Depois de adicionar uma diretriz de versão personalizada a um pacote de aplicativo, você pode atualizar a versão e o patch para a diretriz de versão executando o ALTER APPLICATION PACKAGE com MODIFY RELEASE DIRECTIVE e especificando valores atualizados para VERSION e PATCH.

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.

Atualização de uma diretriz de versão personalizada em um pacote de aplicativo

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 HelloSnowflakePackage
  MODIFY RELEASE DIRECTIVE HelloSnowflakePackage_Custom
  VERSION = v1_0
  PATCH = 0;
Copy

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

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 HelloSnowflakePackage
  UNSET RELEASE DIRECTIVE HelloSnowflakePackage_Custom;
Copy

Lançamento de versões e patches

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 normalmente, como:

CREATE APPLICATION HelloSnowflake
  FROM APPLICATION PACKAGE HelloSnowflakePackage
Copy

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