Upgrade Database (Application)

Upgrade Database, é um mecanismo automático de execução de scripts de atualização de base de dados, executado quando é publicado novo binário de produto que tenha alterações o normal upgrade de scripts.

Alterações, Web.Config produto:

Adicionar a seção abaixo, onde é importante destacar a tag "databaseVersion", nesta é definida o "target" de base de dados enquanto que o "previous" é obtida na tabela Operations.DbVersions. Outro pormenor importante, é os elementos no , estes definem o market do produto e é obrigatório criar as respetivas pastas, mesmo que vazias inicialmente.

<databaseUpgradeConfiguration>
    <elements>
      <add name="default" databaseVersion="1.03.0001.0320" databaseVersionValidation="product-database" databaseUpgradeCommandTimeout="600">
        <markets>
          <add key="market_pt" value="repositories\database\scripts\pt" />
          <add key="market_es" value="repositories\database\scripts\es" />
          <add key="market_en" value="repositories\database\scripts\en" />
        </markets>
      </add>
    </elements>
  </databaseUpgradeConfiguration>

O upgrade, é executado pelo endpoint:

• POST {{baseurl}}/api/{{AccountKey}}/{{SubscriptionKey}}/operations/upgradeVersions/upgradeApplication

Após o upgrade executado é validado o seu estado pelo endpoint:

• GET {{baseurl}}/api/{{AccountKey}}/{{SubscriptionKey}}/operations/upgradeVersions/checkUpgradeStatus

NOTA: O upgrade é executado pelo primeiro utilizador que selecionar a subscrição, nesse momento é criado no private container da subscrição, (se não existir), uma blob com o nome "application-update.json" este será o mecanismo de control e de registo de mensagens no decorrer do processo de upgrade.

application-update.json

[
   {
      "status":1,
      "message":"",
      "modifiedOn":"2020-11-27T17:46:49.3829024+00:00"
   },
   {
      "status":2,
      "message":"Upgrade iniciado.",
      "modifiedOn":"2020-11-27T17:46:49.8047912+00:00"
   },
   {
      "status":4,
      "message":"A versão de upgrade base ou a versão de destino tem o formato errado, CÓDIGO: 5004.",
      "modifiedOn":"2020-11-27T17:46:49.9142401+00:00"
   },
   {
      "status":5,
      "message":"",
      "modifiedOn":"2020-11-27T17:46:50.0079342+00:00"
   }
]

Condições do upgrade e para a sua execução:

• Versão diferente entre a databaseVersion no Web.Config e no Operations.DbVersions/DatabaseVersion;
• Após a validação anterior, irá validar se a subscrição (CMS ou Apps) contêm a CLAIM para executar o upgrade, sintax claim_xx tudo em "lowercase";
• Passando os passos anteriores, irá carregar as scripts da diretoria definida para o market da claim e executar;
• O padrão utilizado é o "Semantic Version", com 2 digitos para a major, 2 digitos para a minor, 4 digitos para o patch e 4 digitos para a build;

Azure Application Insights (Alarmística)

De forma a obter dados das exceções/erros ocorridos no processo de upgrade nas Web App do ambiente Azure, é possível através do filtro pela exception "UpgradeApplicationException", (caso não tenha permissões contate o CMS).

• Query

exceptions 
| project ['type'], outerMessage, innermostMessage, timestamp 
| where ['type'] contains "UpgradeApplicationException"
| order by timestamp desc 

FAQ

Como validar problemas:

• A versão do databaseVersion do Web.Config deverá ser sempre superior que a versão definida na DB, caso contrário irá retornar um erro e não deixará abrir a aplicação;
• A pasta de destino dos diferentes markets deve existir, mesmo que vazias;
• Estas scripts deverão ser IDEMPOTENTES;
• O nome dos ficheiros *.sql deverá ter só números, ex: 1.00.0000.0123.sql, tais como as versões definidas no Web.Config e Operations.DbVersions;
• A pasta das scripts ao correr no Visual Studio, validem se estão todos os ficheiros adicionados à solução, podem estar a carregar ficheiros que não estão visíveis no Visual Studio e pode provocar erros quando estes não cumprem o padrão de nome, (só digitos);
• Ao correr localmente e não fechando o ciclo de execução, pode ficar o Blob Leased, para permitir executar após resolução do problema é necessário fazer "break lease" ao blob application-update.json, para efetuar este passo, no Portal Azure ou aceder ao private container da subscrição;
• As scripts não podem ter GO seguidos sem qualquer bloco de script para executar;
• As scritps não podem ter GO em comentários;
• Existe uma limitação nesta funcionalidade, não permite que no upgrade de DB esteja incluida alterações em tabelas de FW que sejam core, como os Users por exemplo. Significa portanto que a atualização terá obrigatoriamente permitir a web app de arrancar no Azure;

Códigos de ERRO

public enum UpgradeApplicationExceptionErrorCode
{
    /// <summary>The error code was not specified.</summary>
    Unspecified = 5000,

    /// <summary>The specified script already executed.</summary>
    ScriptAlreadyExecutedOrWithIssues = 5001,

    /// <summary>Issues update db version executed.</summary>
    UpdateDbVersion = 5002,

    /// <summary>Issues when scripts were executed.</summary>
    SqlTransactionIssues = 5003,

    /// <summary>The semantic version with wrong format.</summary>
    SemanticVersionWrongFormat = 5004,

    /// <summary>The semantic version Unspecified.</summary>
    SemanticVersionUnspecified = 5005,

    /// <summary>The semantic version with wrong format between in files names.</summary>
    SemanticVersionWrongFormatBetweenFiles = 5006,

    /// <summary>Defined directory not exists.</summary>
    DirectoryNotFound = 5007,

    /// <summary>Files not found in defined directory.</summary>
    FilesNotFoundInDirectory = 5008,

    /// <summary>The exception corresponds to an internal error.</summary>
    InternalError = 5010
}