Scripts de pré-implementação e pós-implementação para o Fabric Data Warehouse (Pré-visualização)

Aplica-se a:✅ Armazém de Dados no Microsoft Fabric

Os scripts antes da implementação e após a implementação permitem executar comandos Transact-SQL personalizados no âmbito da implementação de um armazém no Fabric. Utilize scripts de pré-implementação e de pós-implementação para limpar dados, popular dados de referência ou aplicar definições de segurança SQL que não estejam definidas no esquema do armazém de dados.

Numa Fabric Data Warehouse, um script pré-implantação ou pós-implementação é uma consulta SQL partilhada. Pode criar estes scripts num projeto de base de dados SQL e designá-los a partir do portal Fabric. A designação é armazenada como metadados ao nível do armazém e é registada no controlo de versões como parte do ficheiro .sqlproj do armazém, pelo que circula entre o Git e os pipelines de implementação sem necessidade de reaplicação manual.

Este artigo explica o que são scripts pré-e pós-implementação, como os configurar no portal Fabric, como se comportam com controlo de versões e pipelines de implementação, e como os criar no Visual Studio Code e no SQL Server Management Studio (SSMS).

O que são scripts pré-implementação e pós-implementação?

Quando se liga um espaço de trabalho ao controlo de versão, cada armazém é representado como um projeto de base de dados SQL: um script controlado por código-fonte dos objetos SQL que compõem o esquema do armazém (tabelas, vistas, procedimentos armazenados e funções). Cada objeto é armazenado como um .sql ficheiro que contém a sua sintaxe de linguagem de definição de dados (DDL), como CREATE TABLE. Os objetos descrevem o estado desejado do esquema, e o processo de implementação compara esse estado desejado com o armazém alvo e gera um script diferencial T-SQL que cria, altera ou elimina objetos para que o alvo corresponda ao projeto.

Os scripts de pré-implantação e pós-implantação expandem este processo com código Transact-SQL executado antes e depois da implantação do esquema:

• Um script pré-implementação é executado antes de o plano de implementação do esquema ser aplicado.
• Um script pós-implementação é executado após a conclusão do plano de implementação do esquema.

Um script de pré-implementação ou de pós-implementação é uma consulta partilhada armazenada na pasta Queries do armazém de dados. Um armazém suporta, no máximo, um script pré-implementação e um script pós-implementação. A designação é armazenada como metadados ao nível do armazém, em vez de duplicar o conteúdo do script, pelo que introduz uma sobrecarga de armazenamento negligenciável.

Como cada script designado corre sempre que o warehouse é implementado, cria o Transact-SQL para ser idempotente (seguro para executar repetidamente).

Casos comuns de utilização

• Gestão de referência e de dados estáticos: Inserir, atualizar ou eliminar linhas de tabelas de consulta, configuração ou referência após a implementação do esquema.
• Limpeza de dados: Remover dados obsoletos ou temporários antes ou depois de serem aplicadas alterações no esquema.
• Configuração do ambiente: Aplicar definições ou inicializar o estado que diferia entre ambientes de desenvolvimento, teste e produção.
• Inicialização do pipeline orientada por metadados: Prepare o estado do armazém de dados necessário para as etapas subsequentes do pipeline.
• Segurança SQL: Os dados de tabelas de armazém e as funcionalidades de segurança SQL, como funções, utilizadores e GRANT/DENY permissões, não estão incluídos no projeto de base de dados SQL. Use um script pós-implementação para recriar estes objetos após a implementação, incluindo diferenças entre os ambientes de teste e produção. Para exemplos, veja Exemplo de script pós-implementação para segurança SQL.

Estrutura e sintaxe de ficheiros de projeto SQL

Um projeto SQL de armazém de dados faz referência aos scripts de pré-implementação e pós-implementação no ficheiro do projeto (.sqlproj) através dos tipos de item PreDeploy e PostDeploy. Cada entrada aponta para um único ficheiro de consulta partilhado no projeto.

O exemplo seguinte designa pre-deployment.sql como o script pré-implantação e post-deployment.sql como o script pós-implantação:

<ItemGroup>
  <PreDeploy Include="pre-deployment.sql" />
  <PostDeploy Include="post-deployment.sql" />
</ItemGroup>

Exemplo de script pós-implementação para segurança SQL

Como as funcionalidades de segurança SQL não são capturadas no projeto de base de dados SQL, um script pós-implementação é uma forma comum de as recriar após a implementação de um armazém. Escreve o script para que possa correr em todas as implementações.

O exemplo seguinte cria um papel personalizado de base de dados nomeado DataReaders e concede SELECT permissões ao dbo esquema.

-- post-deployment.sql
-- Recreate a role and grant permissions after deployment.
IF NOT EXISTS (SELECT 1 FROM sys.database_principals WHERE name = N'DataReaders')
BEGIN
    CREATE ROLE DataReaders;
END;
GO

GRANT SELECT ON SCHEMA::dbo TO DataReaders;
GO

Configurar scripts de pré-implementação e pós-implementação no portal Fabric

No portal Fabric, designe uma consulta partilhada existente como o script pré-implementação ou pós-implementação. Podes fazer isto a partir do Object Explorer ou das Definições do item do armazém.

Não podes designar uma consulta partilhada como script pré-implantação e pós-implementação ao mesmo tempo.

Do Object Explorer

1. No editor de armazém, expanda a pasta Queries no Object Explorer.
2. Clique com o botão direito na consulta partilhada que pretende usar.
3. Selecione Definir scripts de implementação. Esta ação leva-o ao painel de definições dos itens.

A partir das definições de itens

1. Abre as definições de Itens do armazém.
2. Vai à secção CI-CD .
3. Use os menus pendentes Script de pré-implementação e Script de pós-implementação para selecionar uma consulta partilhada em cada um deles. Cada menu suspenso lista todas as consultas partilhadas no armazém, além de uma opção (nenhuma) para deixar a designação por definir.

As seleções que faz são armazenadas como metadados ao nível do armazém e são mantidas sincronizadas entre o Object Explorer e as Definições do item.

Como os scripts pré-e pós-implementação se comportam com a implementação

Com integração do Git

Quando liga uma área de trabalho a um repositório Git, as designações de pré-implementação e pós-implementação são serializadas no ficheiro .sqlproj do armazém ao efetuar o commit. Quando atualizas o warehouse a partir do Git, o Fabric aplica as alterações ao live warehouse e executa os scripts por ordem:

1. O script pré-implementação corre antes de as alterações de esquema serem aplicadas.
2. Aplica-se o plano de implementação do esquema.
3. O script pós-implementação corre após a conclusão das alterações de esquema.

Designações ida e volta pelo Git: configurar um script no portal e commitá-lo, ou criá-lo no .sqlproj e atualizar o espaço de trabalho, produz um resultado consistente. Commits e atualizações repetidas não duplicam nem perdem a configuração. Como apenas são permitidos um script de pré-implementação e um script de pós-implementação, uma configuração definida em Git substitui qualquer definição existente no armazém de dados quando é atualizada.

Com pipelines de implementação

Os pipelines de implementação assumem as designações de pré e pós-implementação ao promover um armazém de dados entre as fases Desenvolvimento, Teste e Produção. Os scripts designados executam-se deterministicamente em cada ambiente-alvo, por isso podes usá-los para aplicar a configuração do ambiente ou para reaplicar a segurança SQL à medida que o conteúdo se move entre etapas.

Em espaços de trabalho sem controlo de versões

A definição do item de armazém inclui as designações de pré-implementação e pós-implementação, mesmo quando o espaço de trabalho não está ligado ao controlo de código-fonte. Exportar o armazém inclui a configuração, e importá-la restaura a configuração intacta.

Criar scripts de pré-implementação e pós-implementação num projeto de base de dados SQL

Em vez do portal Fabric, pode criar scripts pré-implantação e pós-implementação diretamente no projeto de base de dados SQL do armazém, usando a extensão SQL Database Projects no Visual Studio Code ou a experiência integrada de projetos SQL no SQL Server Management Studio. A configuração aparece no portal Fabric – tanto no Object Explorer como nas Definições de itens – após a próxima atualização do Git.

Código do Visual Studio

1. Instale a extensão SQL Database Projects no Visual Studio Code.
2. Abre o projeto de base de dados SQL para o teu armazém. Se o seu espaço de trabalho estiver ligado ao Git, clone o repositório e depois abra a pasta do projeto do armazém.
3. Na vista de Projetos de Base de Dados , clique com o botão direito no nó do projeto e selecione Adicionar Script Pré-Implementação ou Adicionar Script Pós-Implementação.
4. Forneça um nome de script sem a extensão do arquivo. O ficheiro de script é adicionado ao projeto e aberto no editor.
5. Adiciona o teu Transact-SQL ao script e guarda o ficheiro. Certifica-te de que o ficheiro está guardado na .sharedqueries pasta para a próxima atualização do Git.
6. Confirma e envia as alterações para o repositório Git e, em seguida, atualiza a área de trabalho a partir do controlo de código-fonte para aplicar a configuração.

SQL Server Management Studio

1. Use o SQL Server Management Studio 22 ou posterior, que inclui a experiência dos Projetos de Bases de Dados SQL.
2. Abre o projeto de base de dados SQL para o teu armazém.
3. No Explorador de Soluções, clique com o botão direito no nó do projeto e selecione Adicionar>Script. Selecione Script de pré-implantação ou Script de pós-implantação.
4. O ficheiro de script é adicionado ao projeto e aberto no editor de consultas.
5. Adiciona o teu Transact-SQL ao script e guarda o ficheiro. Certifica-te de guardar o ficheiro na .sharedqueries pasta para a próxima atualização do Git.
6. Confirma e envia as alterações para o repositório Git e, em seguida, atualiza a área de trabalho a partir do controlo de código-fonte para aplicar a configuração.

Editar diretamente o ficheiro do projeto

Em qualquer ferramenta, pode designar um script editando o .sqlproj ficheiro e adicionando um único PreDeploy ou PostDeploy item a um ItemGroup:

<ItemGroup>
  <PreDeploy Include="./sharedqueries/pre-deployment.sql" />
  <PostDeploy Include="./sharedqueries/post-deployment.sql" />
</ItemGroup>

Migrar a partir de projetos SQL existentes

Se migrar um .sqlproj do SQL Server Data Tools (SSDT) ou do Visual Studio que já contém entradas <PreDeploy> e <PostDeploy>, essas entradas são reconhecidas e mapeadas para a configuração de pré-implementação e pós-implementação do Fabric quando importar o projeto através do Git. Como o Fabric suporta apenas um script pré-implementação e um pós-implantação, certifique-se de que o projeto contém no máximo uma entrada de cada tipo antes de importar.

Considerações e limitações

• Um armazém suporta apenas um único script pré-implementação e um único script pós-implantação. Não suporta múltiplos ficheiros por script.
• Não podes atribuir a mesma consulta partilhada como script de pré-implementação e de pós-implementação.
• Se eliminar uma consulta partilhada definida como script de pré-implantação ou de pós-implantação, a designação correspondente é automaticamente removida.
• Se transformar uma consulta partilhada designada como script pré-implantação ou pós-implementação numa consulta de utilizador, a designação correspondente é automaticamente apagada.
• Os scripts de pré e pós-implementação são executados em cada implementação do armazém de dados. Os scripts Transact-SQL devem ser idempotentes, para que execuções repetidas não falhem nem criem objetos duplicados.
• Os scripts pré-e pós-implementação não são validados contra o modelo da base de dados em tempo de compilação. Erros nos scripts surgem no momento da implementação, e uma falha no script interrompe a implementação.
• Só podes usar Transact-SQL que seja suportado em Fabric Data Warehouse.
• A identidade que executa a implementação deve ter as permissões necessárias para executar o conteúdo do script.

Conteúdo relacionado

• Fluxos de trabalho de desenvolvimento e implantação
• Desenvolver e implantar dependências entre armazéns
• Comece a usar pipelines de implantação do Fabric