Script di pre-distribuzione e post-distribuzione per Fabric Data Warehouse (anteprima)

si applica a:✅ Magazzino di dati in Microsoft Fabric

Important

Questa funzionalità si trova in Anteprima.

Gli script di pre-distribuzione e post-distribuzione consentono di eseguire comandi di Transact-SQL personalizzati come parte della distribuzione di un warehouse in Fabric. Usare script di pre-distribuzione e post-distribuzione per pulire i dati, i dati di riferimento di inizializzazione o applicare la sicurezza SQL non espressa nello schema del warehouse.

In un Fabric Data Warehouse, uno script di pre-distribuzione o post-distribuzione è una query SQL condivisa. È possibile creare questi script in un progetto di database SQL e designarli dal portale di Fabric. La designazione viene archiviata come metadato a livello di warehouse e sottoposta a commit nel controllo del codice sorgente come parte del file .sqlproj del warehouse, così da passare attraverso Git e le pipeline di distribuzione senza doverla riapplicare manualmente.

Questo articolo illustra quali script di pre-distribuzione e post-distribuzione sono, come configurarli nel portale di Fabric, come si comportano con le pipeline di controllo del codice sorgente e di distribuzione e come crearle in Visual Studio Code e SQL Server Management Studio (SSMS).

Important

Esaminare sempre gli script e le impostazioni di distribuzione prima della pubblicazione. Eseguire prima test negli ambienti di sviluppo e test per evitare perdite di dati impreviste.

Che cosa sono gli script di pre-distribuzione e post-distribuzione?

Quando si connette un'area di lavoro al controllo del codice sorgente, ogni warehouse viene rappresentato come progetto di database SQL: uno script controllato dal codice sorgente degli oggetti SQL che costituiscono lo schema del warehouse (tabelle, viste, stored procedure e funzioni). Ogni oggetto viene archiviato come .sql file contenente la sintassi DDL (Data Definition Language), ad esempio CREATE TABLE. Gli oggetti descrivono lo stato desiderato dello schema e il processo di distribuzione confronta lo stato desiderato con il warehouse di destinazione e genera uno script T-SQL differenziale che crea, modifica o elimina oggetti in modo che la destinazione corrisponda al progetto.

Gli script di pre-distribuzione e post-distribuzione estendono questo processo con Transact-SQL che esegue la distribuzione dello schema:

  • Uno script di pre-distribuzione viene eseguito prima dell'applicazione del piano di distribuzione dello schema.
  • Uno script di post-distribuzione viene eseguito dopo il completamento del piano di distribuzione dello schema.

Uno script di pre-distribuzione o post-distribuzione è una delle query condivise archiviate nella cartella Query del warehouse. Un warehouse supporta al massimo uno script di pre-distribuzione e uno script post-distribuzione. La designazione viene archiviata come metadati a livello di warehouse anziché duplicare il contenuto dello script, quindi aggiunge un sovraccarico di archiviazione trascurabile.

Poiché ogni script designato viene eseguito ogni volta che viene distribuito il warehouse, creare il Transact-SQL come idempotente (sicuro da eseguire ripetutamente).

Tip

Quando uno script è idempotente, può essere eseguito più volte senza causare problemi ed è possibile eseguire la distribuzione in più database senza dover predeterminare il proprio stato.

Casi d'uso comuni

  • Gestione dei dati statici e di riferimento: inserire, aggiornare o eliminare righe da tabelle di ricerca, configurazione o riferimento dopo la distribuzione dello schema.
  • Pulizia dei dati: rimuovere dati non aggiornati o temporanei prima o dopo l'applicazione delle modifiche dello schema.
  • Configurazione dell'ambiente: applicare impostazioni o inizializzare lo stato che differisce tra ambienti di sviluppo, test e produzione.
  • Inizializzazione della pipeline basata sui metadati: preparare lo stato del data warehouse necessario per le fasi a valle della pipeline.
  • Sicurezza SQL: i dati delle tabelle di Warehouse e le funzionalità di sicurezza SQL, ad esempio ruoli, utenti e GRANT/DENY autorizzazioni, non sono inclusi nel progetto di database SQL. Usare uno script di post-distribuzione per ricreare questi oggetti dopo la distribuzione, incluse le differenze tra ambienti di test e di produzione. Per un esempio, vedi Esempio di script post-distribuzione per la sicurezza SQL.

Struttura e sintassi dei file di progetto SQL

Un progetto SQL warehouse fa riferimento agli script di pre-distribuzione e post-distribuzione nel file di progetto (.sqlproj) con i PreDeploy tipi di elemento e PostDeploy . Ogni voce punta a un unico file di query condiviso all’interno del progetto.

L'esempio seguente definisce pre-deployment.sql come script di pre-distribuzione e post-deployment.sql come script post-distribuzione:

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

Important

Fabric Data Warehouse supporta solo un singolo file per lo script di pre-distribuzione e un singolo file per lo script di post-distribuzione. La composizione di uno script da più file, ad esempio usando il comando SQLCMD :r per fare riferimento ad altri file, non è supportata. .sqlproj Se contiene più voci di pre-distribuzione o post-distribuzione, l'aggiornamento Git ha esito negativo.

Esempio di script post-distribuzione per la sicurezza SQL

Poiché le funzionalità di sicurezza SQL non vengono acquisite nel progetto di database SQL, uno script post-distribuzione è un modo comune per ricrearli dopo la distribuzione di un warehouse. Scrivere lo script in modo che possa essere eseguito in ogni distribuzione.

L'esempio seguente crea un ruolo di database personalizzato denominato DataReaders e concede SELECT le autorizzazioni allo dbo schema.

-- 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

Note

Fabric Data Warehouse non supporta tutte le istruzioni Transact-SQL disponibili in SQL Server. Assicurarsi che le istruzioni presenti negli script siano supportate in Fabric Data Warehouse.

Configurare script di pre-distribuzione e post-distribuzione nel portale di Fabric

Nel portale di Fabric designare una query condivisa esistente come script di pre-distribuzione o post-distribuzione. È possibile eseguire questa operazione da Esplora oggetti o dalle impostazioni dell'articolo del magazzino.

Non è possibile designare una query condivisa come script di pre-distribuzione e post-distribuzione contemporaneamente.

Da Esplora oggetti

  1. Nell'editor del data warehouse, espandi la cartella Queries in Esplora oggetti.
  2. Fare clic con il pulsante destro del mouse sulla query condivisa da usare.
  3. Selezionare Imposta script di distribuzione. Questa azione consente di visualizzare il riquadro delle impostazioni dell'elemento.

Da Impostazioni dell'elemento

  1. Aprire le impostazioni articolo del magazzino.
  2. Passare alla sezione CI-CD .
  3. Utilizzare i menu a discesa Script di pre-distribuzione e Script di post-distribuzione per selezionare una query condivisa per ciascuno. Ogni elenco a discesa elenca tutte le query condivise nel data warehouse, più un'opzione (nessuna) per lasciare la designazione non impostata.

Le selezioni effettuate vengono archiviate come metadati a livello di magazzino e vengono mantenute sincronizzate tra Esplora oggetti e impostazioni dell'elemento.

Come si comportano gli script di pre-distribuzione e post-distribuzione con la distribuzione

Con l'integrazione di Git

Quando si connette un'area di lavoro a un repository Git, le designazioni di pre-distribuzione e post-distribuzione vengono serializzate nel file del .sqlproj warehouse al commit. Quando si aggiorna il warehouse da Git, Fabric applica le modifiche al warehouse attivo ed esegue gli script in ordine:

  1. Lo script di pre-distribuzione viene eseguito prima dell'applicazione delle modifiche dello schema.
  2. Viene applicato il piano di distribuzione dello schema.
  3. Lo script post-distribuzione viene eseguito dopo il completamento delle modifiche dello schema.

Le designazioni possono essere sincronizzate tramite Git: configurare uno script nel portale ed eseguirne il commit, oppure crearlo in .sqlproj e aggiornare l'area di lavoro, produce un risultato coerente. I commit e gli aggiornamenti ripetuti non duplicano o perdono la configurazione. Poiché è consentito un solo script di pre-distribuzione e uno script post-distribuzione, una configurazione creata in Git sostituisce qualsiasi designazione esistente nel warehouse in fase di aggiornamento.

Con le pipeline di distribuzione

Le pipeline di distribuzione contengono le designazioni di pre-distribuzione e post-distribuzione durante la promozione di un magazzino nelle fasi sviluppo, test e produzione . Gli script designati vengono eseguiti in modo deterministico in ogni ambiente di destinazione, quindi è possibile usarli per applicare la configurazione dell'ambiente o per riapplicare la sicurezza SQL quando il contenuto si sposta tra le fasi.

Nelle aree di lavoro senza controllo del codice sorgente

La definizione dell'elemento del magazzino include le designazioni di pre-distribuzione e post-distribuzione anche quando l'area di lavoro non è connessa al controllo del codice sorgente. L'esportazione del magazzino include la configurazione e l'importazione ripristina la configurazione intatta.

Creare script di pre-distribuzione e post-distribuzione in un progetto di database SQL

Anziché il portale di Fabric, è possibile creare script di pre-distribuzione e post-distribuzione direttamente nel progetto di database SQL del warehouse usando l'estensione Progetti di database SQL in Visual Studio Code o l'esperienza integrata dei progetti SQL in SQL Server Management Studio. La configurazione viene visualizzata nel portale di Fabric, sia in Esplora oggetti che nelle impostazioni dell'elemento, dopo l'aggiornamento Git successivo.

Visual Studio Code

  1. Installare l'estensione Progetti di database SQL in Visual Studio Code.
  2. Aprire il progetto di database SQL per il warehouse. Se l'area di lavoro è connessa a Git, clonare il repository, quindi aprire la cartella del progetto warehouse.
  3. Nella visualizzazione Progetti di database fare clic con il pulsante destro del mouse sul nodo del progetto e scegliere Aggiungi script di pre-distribuzione o Aggiungi script post-distribuzione.
  4. Specificare un nome dello script senza l'estensione del file. Il file di script viene aggiunto al progetto e aperto nell'editor.
  5. Aggiungere il Transact-SQL allo script e salvare il file. Assicurarsi che il file venga salvato nella .sharedqueries cartella per l'aggiornamento Git successivo.
  6. Eseguire il commit e il push delle modifiche nel repository Git, quindi aggiornare l'area di lavoro dal controllo del codice sorgente per applicare la configurazione.

SQL Server Management Studio

  1. Usare SQL Server Management Studio 22 o versioni successive, che comprende la funzionalità Progetti di database SQL.
  2. Aprire il progetto di database SQL per il warehouse.
  3. In Esplora soluzioni fare clic con il pulsante destro del mouse sul nodo del progetto e scegliere Aggiungi>script. Selezionare Script pre-distribuzione o Script post-distribuzione.
  4. Il file di script viene aggiunto al progetto e aperto nell'editor di query.
  5. Aggiungere il Transact-SQL allo script e salvare il file. Assicurarsi di salvare il file nella .sharedqueries cartella per l'aggiornamento Git successivo.
  6. Eseguire il commit e il push delle modifiche nel repository Git, quindi aggiornare l'area di lavoro dal controllo del codice sorgente per applicare la configurazione.

Modificare direttamente il file di progetto

In qualsiasi strumento, è possibile specificare uno script modificando il file .sqlproj e aggiungendo un singolo elemento PreDeploy o PostDeploy a un ItemGroup:

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

Eseguire la migrazione da progetti SQL esistenti

Se si esegue la migrazione di un oggetto .sqlproj da SQL Server Data Tools (SSDT) o Visual Studio che già contiene <PreDeploy> e <PostDeploy> voci, tali voci vengono riconosciute e mappate alla configurazione di pre-distribuzione e post-distribuzione Fabric quando si importa il progetto tramite Git. Poiché Fabric supporta un solo script pre-distribuzione e un solo script post-distribuzione, assicurarsi che il progetto contenga al massimo un elemento di ciascun tipo prima dell'importazione.

Considerazioni e limitazioni

  • Un warehouse supporta solo uno script di pre-distribuzione e un singolo script di post-distribuzione. Non supporta file multipli per script.
  • Non è possibile specificare la stessa query condivisa come script di pre-distribuzione e di post-distribuzione.
  • Se si elimina una query condivisa designata come script di pre-distribuzione o post-distribuzione, la designazione corrispondente viene cancellata automaticamente.
  • Se si modifica una query condivisa designata come script di pre-distribuzione o post-distribuzione in una query utente, la designazione corrispondente viene cancellata automaticamente.
  • Gli script eseguiti prima e dopo la distribuzione vengono eseguiti a ogni distribuzione del data warehouse. Gli script Transact-SQL devono essere idempotenti, in modo che le esecuzioni ripetute non riescano o creino oggetti duplicati.
  • Gli script di pre-distribuzione e post-distribuzione non vengono convalidati rispetto al modello di database in fase di compilazione. Gli errori negli script vengono visualizzati in fase di distribuzione e un errore di script interrompe la distribuzione.
  • È possibile usare solo Transact-SQL supportato da Fabric Data Warehouse.
  • L'identità che esegue la distribuzione deve disporre delle autorizzazioni necessarie per eseguire il contenuto dello script.

Contenuti correlati

  • Last updated on