Scripts de pré-implantação e pós-implantação para Fabric Data Warehouse (versão prévia)

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

Os scripts de pré-implantação e pós-implantação permitem executar comandos de Transact-SQL personalizados como parte da implantação de um warehouse em Fabric. Use scripts de pré-implantação e pós-implantação para limpar dados, dados de referência de semente ou aplicar a segurança do SQL que não é expressa no esquema do warehouse.

Em um Fabric Data Warehouse, um script de pré-implantação ou pós-implantação é uma consulta SQL compartilhada. Você pode criar esses scripts em um projeto de banco de dados SQL e designá-los no portal do Fabric. A designação é armazenada como metadados no nível do armazém e está comprometida com o controle do código-fonte como parte do arquivo do .sqlproj armazém, portanto, ele percorre o Git e os pipelines de implantação sem reaplicação manual.

Este artigo explica o que são scripts de pré-implantação e pós-implantação, como configurá-los no portal Fabric, como eles se comportam com pipelines de controle do código-fonte e implantação e como criar no SSMS (Visual Studio Code e SQL Server Management Studio).

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

Quando você conecta um workspace ao controle do código-fonte, cada warehouse é representado como um projeto de banco de dados SQL: um script controlado pela origem dos objetos SQL que compõem o esquema do warehouse (tabelas, exibições, procedimentos armazenados e funções). Cada objeto é armazenado como um .sql arquivo que contém sua sintaxe DDL (linguagem de definição de dados), como CREATE TABLE. Os objetos descrevem o estado desejado do esquema e o processo de implantação compara esse estado desejado com o warehouse de destino e gera um script T-SQL diferencial que cria, altera ou descarta objetos para que o destino corresponda ao projeto.

Os scripts de pré-implantação e pós-implantação estendem esse processo com Transact-SQL executados em torno da implantação do esquema:

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

Um script de pré-implantação ou pós-implantação é uma das consultas compartilhadas armazenadas na pasta Consultas do armazém. Um warehouse dá suporte a no máximo um script de pré-implantação e um script pós-implantação. A designação é armazenada como metadados no nível do armazém em vez de duplicar o conteúdo do script, de modo que adiciona uma sobrecarga de armazenamento insignificante.

Como cada script designado é executado sempre que o armazém é implantado, crie o Transact-SQL para ser idempotente (seguro para ser executado repetidamente).

Casos de uso comuns

• Referência e gerenciamento de dados estáticos: inserir, atualizar ou excluir linhas de tabelas de pesquisa, configuração ou referência após a implantação do esquema.
• Limpeza de dados: remova dados obsoletos ou temporários antes ou depois que as alterações de esquema forem aplicadas.
• Configuração do ambiente: aplique configurações ou inicialize o estado que difere entre ambientes de desenvolvimento, teste e produção.
• Inicialização de pipeline orientada por metadados: Prepare o estado do armazém de dados necessário para as etapas posteriores do pipeline.
• Segurança do SQL: os dados da tabela do warehouse e os recursos de segurança do SQL, como funções, usuários e GRANT/DENY permissões, não estão incluídos no projeto do banco de dados SQL. Use um script pós-implantação para recriar esses objetos após a implantação, incluindo diferenças entre ambientes de teste e de produção. Para obter exemplos, consulte Exemplo de script pós-implantação para segurança do SQL.

Estrutura e sintaxe de arquivo do projeto SQL

Um projeto SQL de warehouse faz referência aos scripts de pré-implantação e pós-implantação no arquivo de projeto (.sqlproj) com os tipos de item PreDeploy e PostDeploy. Cada entrada aponta para um único arquivo de consulta compartilhado no projeto.

O exemplo a seguir designa pre-deployment.sql como o script de 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-implantação para segurança do SQL

Como os recursos de segurança do SQL não são incluídos no projeto de banco de dados SQL, um script de pós-implantação é uma maneira comum de recriá-los após a implantação de um data warehouse. Escreva o script para que ele possa ser executado em cada implantação.

O exemplo a seguir cria uma função de banco de dados personalizada nomeada 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é-implantação e pós-implantação no portal do Fabric

No portal do Fabric, defina uma consulta compartilhada existente como script de pré-implantação ou de pós-implantação. Você pode fazer isso de Pesquisador de Objetos ou das Configurações do item de armazém.

Você não pode definir uma consulta compartilhada como o script de pré-implantação e o de pós-implantação ao mesmo tempo.

De Pesquisador de Objetos

1. No editor do warehouse, expanda a pasta Consultas em Pesquisador de Objetos.
2. Clique com o botão direito do mouse na consulta compartilhada que você deseja usar.
3. Selecione Definir scripts de implantação. Essa ação leva você ao painel de configurações do item.

Nas configurações do Item

1. Abra as configurações de Item do armazém.
2. Vá para a seção CI-CD .
3. Use as listas suspensas Script de pré-implantação e Script de pós-implantação para selecionar uma consulta compartilhada em cada uma delas. Cada menu suspenso exibe todas as consultas compartilhadas no armazém, além da opção (nenhuma) para deixar a definição sem configuração.

As seleções que você faz são armazenadas como metadados no nível do armazém e são mantidas em sincronia entre Pesquisador de Objetos e configurações de item.

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

Com a integração do Git

Quando você conecta um espaço de trabalho a um repositório Git, as designações de pré-implantação e pós-implantação são serializadas no arquivo .sqlproj do warehouse ao fazer commit. Quando você atualiza o warehouse do Git, Fabric aplica as alterações ao live warehouse e executa os scripts na ordem:

1. O script de pré-implantação é executado antes que as alterações de esquema sejam aplicadas.
2. O plano de implantação do esquema foi aplicado.
3. O script pós-implantação é executado após a conclusão das alterações de esquema.

Designações de ida e volta pelo Git: configurar um script no portal e emiti-lo, ou criar no .sqlproj espaço de trabalho e atualizá-lo, produz um resultado consistente. Confirmações e atualizações repetidas não duplicam ou perdem a configuração. Como apenas uma pré-implantação e um script pós-implantação são permitidos, uma configuração criada no Git substitui qualquer designação existente no warehouse na atualização.

Com pipelines de implantação

Os pipelines de implantação recebem as designações de pré-implantação e pós-implantação ao promover um warehouse entre os estágios Desenvolvimento, Teste e Produção. Os scripts designados são executados deterministicamente em cada ambiente de destino, para que você possa usá-los para aplicar a configuração do ambiente ou reaplicar a segurança do SQL à medida que o conteúdo se move entre os estágios.

Em workspaces sem controle do código-fonte

A definição de item do warehouse inclui as designações de pré-implantação e pós-implantação mesmo quando o workspace não está conectado ao controle do código-fonte. Exportar o warehouse inclui a configuração e importá-lo restaura a configuração intacta.

Criar scripts de pré-implantação e pós-implantação em um projeto de banco de dados SQL

Em vez do portal Fabric, você pode criar scripts de pré-implantação e pós-implantação diretamente no projeto do banco de dados SQL do armazém usando a extensão projetos do Banco de Dados SQL em Visual Studio Code ou a experiência integrada de projetos SQL no SQL Server Management Studio. A configuração aparece no portal do Fabric — em ambos, Pesquisador de Objetos e item Configurações — após a próxima atualização do Git.

Visual Studio Code

1. Instale a extensão Projetos do Banco de Dados SQL no Visual Studio Code.
2. Abra o projeto do banco de dados SQL para seu armazém. Se o seu espaço de trabalho estiver conectado ao Git, clone o repositório e, em seguida, abra a pasta do projeto do data warehouse.
3. Na exibição Projetos de Banco de Dados , clique com o botão direito do mouse no nó do projeto e selecione Adicionar Script de Pré-Implantação ou Adicionar Script pós-implantação.
4. Forneça um nome de script sem a extensão do arquivo. O arquivo de script é adicionado ao projeto e aberto no editor.
5. Adicione sua Transact-SQL ao script e salve o arquivo. Verifique se o arquivo foi salvo na .sharedqueries pasta para a próxima atualização do Git.
6. Confirme e envie por push as alterações para o repositório Git e atualize o workspace do controle do código-fonte para aplicar a configuração.

SQL Server Management Studio

1. Use SQL Server Management Studio 22 ou posterior, que inclui a experiência de Projetos do Banco de Dados SQL.
2. Abra o projeto do banco de dados SQL para seu armazém.
3. Em Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e selecione Adicionar>Script. Selecione o Script de pré-implantação ou Script de pós-implantação.
4. O arquivo de script é adicionado ao projeto e aberto no editor de consultas.
5. Adicione sua Transact-SQL ao script e salve o arquivo. Salve o arquivo na .sharedqueries pasta para a próxima atualização do Git.
6. Faça commit e push das alterações no seu repositório Git e, em seguida, atualize o espaço de trabalho a partir do controle de código-fonte para aplicar a configuração.

Editar o arquivo de projeto diretamente

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

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

Migrar de projetos SQL existentes

Se você migrar um .sqlproj do SQL Server Data Tools (SSDT) ou do Visual Studio que já contém itens <PreDeploy> e <PostDeploy>, esses itens são reconhecidos e mapeados para a configuração de pré-implantação e pós-implantação do Fabric quando você importar o projeto via Git. Como Fabric dá suporte apenas a uma pré-implantação e um script pós-implantação, verifique se o projeto contém no máximo uma entrada de cada tipo antes de importar.

Considerações e limitações

• Um warehouse dá suporte apenas a um único script de pré-implantação e um único script pós-implantação. Ele não dá suporte a vários arquivos por script.
• Você não pode definir a mesma consulta compartilhada como script de pré-implantação e de pós-implantação.
• Se você excluir uma consulta compartilhada designada como um script de pré-implantação ou pós-implantação, a atribuição correspondente será removida automaticamente.
• Se você alterar uma consulta compartilhada definida como script de pré-implantação ou pós-implantação para uma consulta de usuário, a designação correspondente será removida automaticamente.
• Os scripts pré e pós-implantação são executados em cada implantação de armazém. Os scripts Transact-SQL devem ser idempotentes, para que as execuções repetidas não falhem ou criem objetos duplicados.
• Os scripts de pré-implantação e pós-implantação não são validados no modelo de banco de dados no momento da compilação. Erros nos scripts surgem durante a implantação, e uma falha em um script interrompe a implantação.
• Você só pode usar Transact-SQL com suporte no Fabric Data Warehouse.
• A identidade que executa a implantaçã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 implementar dependências entre armazéns
• Comece a usar os pipelines de implantação do Fabric