Esercitazione: creare e implementare un progetto SQL
Si applica a: 
SQL Server database SQL di Azure Istanza gestita di SQL di Azure database SQL in Microsoft Fabric
Il ciclo di sviluppo di un progetto di database SQL consente di integrare lo sviluppo di database in flussi di lavoro di integrazione continua e distribuzione continua (CI/CD), noto come procedura consigliata per lo sviluppo. Anche se l’implementazione di un progetto di database SQL può essere eseguita manualmente, è consigliabile usare una pipeline di distribuzione per automatizzare il processo di distribuzione in modo che le distribuzioni in corso vengano eseguite in base allo sviluppo locale continuo senza ulteriori sforzi.
Questo articolo illustra come creare un nuovo progetto SQL, aggiungere oggetti al progetto e configurare una pipeline di distribuzione continua per la compilazione e la distribuzione del progetto con GitHub actions. L'esercitazione è un superset del contenuto dell'articolo introduttivo ai progetti SQL. Mentre l'esercitazione implementa la pipeline di distribuzione in GitHub actions, gli stessi concetti si applicano ad Azure DevOps, GitLab e ad altri ambienti di automazione.
In questa esercitazione:
- Creare un nuovo script SQL
- Aggiungere oggetti al progetto
- Creare il progetto in locale
- Controllare il progetto nel controllo del codice sorgente
- Aggiungere un passaggio di compilazione del progetto a una pipeline di distribuzione continua
- Aggiungere un passaggio di distribuzione
.dacpaca una pipeline di distribuzione continua
Se sono già stati completati i passaggi descritti nell'articolo Introduzione ai progetti SQL, è possibile passare al passaggio 4. Alla fine di questa esercitazione, il progetto SQL creerà e distribuirà automaticamente le modifiche in un database di destinazione.
Prerequisiti
# install SqlPackage CLI
dotnet tool install -g Microsoft.SqlPackage
# install Microsoft.Build.Sql.Templates
dotnet new install Microsoft.Build.Sql.Templates
Assicurarsi di avere gli elementi seguenti per completare la configurazione della pipeline in GitHub:
Un account GitHub in cui è possibile creare un repository. Crearne una gratuitamente.
GitHub Actions è abilitato nel repository.
Nota
Per completare l’implementazione di un progetto di database SQL, è necessario accedere a un'istanza di Azure SQL o SQL Server. È possibile sviluppare in locale gratuitamente con SQL Server Developer Edition in Windows o in contenitori.
Passaggio 1: Creare un nuovo progetto
Per iniziare il progetto, creare un nuovo progetto di database SQL prima di aggiungerli manualmente. Esistono altri modi per creare un progetto che consente di popolare immediatamente il progetto con oggetti di un database esistente, ad esempio usando gli strumenti di confronto schemi.
Scegliere File, Nuovo e poi Progetto.
Nella finestra di dialogo Nuovo progetto selezionare SQL Server nella casella di ricerca. Il risultato principale deve essere Progetto di database di SQL Server.
Selezionare Avanti per andare al passaggio successivo. Specificare un nome di progetto, che non deve corrispondere a un nome di database. Verificare e modificare il percorso del progetto in base alle esigenze.
Selezionare Crea per creare il progetto. Il progetto vuoto verrà aperto e visualizzato nella vista Esplora soluzioni per la modifica.
Scegliere File, Nuovo e poi Progetto.
Nella finestra di dialogo Nuovo progetto selezionare SQL Server nella casella di ricerca. Il risultato principale deve essere Progetto di database di SQL Server, stile SDK (anteprima).
Selezionare Avanti per andare al passaggio successivo. Specificare un nome di progetto, che non deve corrispondere a un nome di database. Verificare e modificare il percorso del progetto in base alle esigenze.
Selezionare Crea per creare il progetto. Il progetto vuoto verrà aperto e visualizzato nella vista Esplora soluzioni per la modifica.
Nella vista Progetti di database di VS Code o Azure Data Studio selezionare il pulsante Nuovo progetto.
Il primo prompt determina il modello di progetto da usare, principalmente in base al fatto che la piattaforma di destinazione sia SQL Server o Azure SQL. Se viene richiesto di selezionare una versione specifica di SQL, scegliere la versione corrispondente al database di destinazione, ma se la versione del database di destinazione è sconosciuta, scegliere la versione più recente perché il valore può essere modificato in un secondo momento.
Immettere un nome di progetto nell'input di testo visualizzato, che non deve corrispondere a un nome di database.
Nella finestra di dialogo “Seleziona cartella” che appare, selezionare una directory in cui inserire la cartella del progetto, il file .sqlproj e altri contenuti.
Quando viene richiesto se creare un progetto in stile SDK (anteprima), selezionare Sì.
Una volta completato, il progetto vuoto verrà aperto e visualizzato nella vista Progetti del database per la modifica.
Con i modelli .NET per i progetti Microsoft.Build.Sql installati, è possibile creare un nuovo progetto di database SQL dalla riga di comando. L'opzione -n specifica il nome del progetto e l'opzione -tp specifica la piattaforma di destinazione del progetto.
Usare l'opzione -h per visualizzare tutte le opzioni disponibili.
# install Microsoft.Build.Sql.Templates
dotnet new sqlproject -n MyDatabaseProject
Passaggio 2: aggiungere oggetti al progetto
In Esplora soluzioni fare clic con il pulsante destro del mouse sul nodo di progetto e scegliere Aggiungi poi Tabella. Viene visualizzata la finestra di dialogo Aggiungi nuovo elemento, in cui è possibile specificare il nome della tabella. Selezionare Aggiungi per creare la tabella nel progetto SQL.
La tabella viene aperta nella finestra di progettazione tabelle di Visual Studio con la definizione della tabella modello, in cui è possibile aggiungere colonne, indici e altre proprietà della tabella. Salvare il file dopo aver apportato le modifiche iniziali.
È possibile aggiungere altri oggetti di database tramite la finestra di dialogo Aggiungi nuovo elemento, ad esempio viste, stored procedure e funzioni. Accedere alla finestra di dialogo facendo clic con il pulsante destro del mouse sul nodo del progetto in Esplora soluzioni e selezionando Aggiungi, quindi il tipo di oggetto desiderato. I file nel progetto possono essere organizzati in cartelle tramite l'opzione Nuova cartella in Aggiungi.
In Esplora soluzioni, fare clic con il pulsante destro del mouse sul nodo del progetto e quindi scegliere Aggiungi, quindi Nuovo elemento. Verrà visualizzata la finestra di dialogo Aggiungi nuovo elemento, selezionare Mostra tutti i modelli e quindi Tabella. Specificare il nome della tabella come nome file e selezionare Aggiungi per creare la tabella nel progetto SQL.
La tabella viene aperta nell'editor di query Visual Studio con la definizione della tabella modello, in cui è possibile aggiungere colonne, indici e altre proprietà della tabella. Salvare il file dopo aver apportato le modifiche iniziali.
È possibile aggiungere altri oggetti di database tramite la finestra di dialogo Aggiungi nuovo elemento, ad esempio viste, stored procedure e funzioni. Accedere alla finestra di dialogo facendo clic con il pulsante destro del mouse sul nodo del progetto in Esplora soluzioni e selezionando Aggiungi, quindi il tipo di oggetto desiderato dopo Mostra tutti i modelli. I file nel progetto possono essere organizzati in cartelle tramite l'opzione Nuova cartella in Aggiungi.
Nella visualizzazione Progetti del database di VS Code o Azure Data Studio fare clic con il pulsante destro del mouse sul nodo del progetto e scegliere Aggiungi tabella. Nella finestra di dialogo visualizzata specificare il nome della tabella.
La tabella viene aperta nell'editor di testo con la definizione della tabella modello, in cui è possibile aggiungere colonne, indici e altre proprietà della tabella. Salvare il file dopo aver apportato le modifiche iniziali.
È possibile aggiungere altri oggetti di database tramite il menu di scelta rapida nel nodo del progetto, ad esempio viste, stored procedure e funzioni. Accedere alla finestra di dialogo facendo clic con il pulsante destro del mouse sul nodo del progetto nella vista Progetti del database di VS Code o Azure Data Studio, quindi sul tipo di oggetto desiderato. I file nel progetto possono essere organizzati in cartelle tramite l'opzione Nuova cartella in Aggiungi.
I file possono essere aggiunti al progetto creandoli nella directory del progetto o nelle cartelle annidate. L'estensione del file deve essere .sql e l'organizzazione in base al tipo di oggetto o allo schema e al tipo di oggetto è consigliato.
Il modello di base per una tabella può essere usato come punto di partenza per la creazione di un nuovo oggetto tabella nel progetto:
CREATE TABLE [dbo].[Table1]
(
[Id] INT NOT NULL PRIMARY KEY
)
Passaggio 3: compilare il progetto
Il processo di compilazione convalida le relazioni tra oggetti e la sintassi rispetto alla piattaforma di destinazione specificata nel file di progetto. L'output dell'artefatto del processo di compilazione è un file .dacpac, che può essere usato per distribuire il progetto in un database di destinazione e contiene il modello compilato dello schema del database.
In Esplora soluzioni fare clic con il pulsante destro del mouse sul nodo di progetto e scegliere Crea.
Verrà visualizzata automaticamente la finestra di output per visualizzare il processo di compilazione. Se sono presenti errori o avvisi, vengono visualizzati nella finestra di output. In una compilazione completata, l'artefatto di compilazione (file .dacpac) viene creato il relativo percorso è incluso nell'output di compilazione (il valore predefinito è bin\Debug\projectname.dacpac).
In Esplora soluzioni fare clic con il pulsante destro del mouse sul nodo di progetto e scegliere Crea.
Verrà visualizzata automaticamente la finestra di output per visualizzare il processo di compilazione. Se sono presenti errori o avvisi, vengono visualizzati nella finestra di output. In una compilazione completata, l'artefatto di compilazione (file .dacpac) viene creato il relativo percorso è incluso nell'output di compilazione (il valore predefinito è bin\Debug\projectname.dacpac).
Nella visualizzazione Progetti di database di VS Code o Azure Data Studio fare clic con il pulsante destro del mouse sul nodo del progetto e scegliere Compila.
Verrà visualizzata automaticamente la finestra di output per visualizzare il processo di compilazione. Se sono presenti errori o avvisi, vengono visualizzati nella finestra di output. In una compilazione completata, l'artefatto di compilazione (file .dacpac) viene creato il relativo percorso è incluso nell'output di compilazione (il valore predefinito è bin/Debug/projectname.dacpac).
I progetti di database SQL possono essere compilati dalla riga di comando usando il comando dotnet build.
dotnet build
# optionally specify the project file
dotnet build MyDatabaseProject.sqlproj
L'output di compilazione include eventuali errori o avvisi e i file e i numeri di riga specifici in cui si verificano. In una compilazione completata, l'artefatto di compilazione (file .dacpac) viene creato il relativo percorso è incluso nell'output di compilazione (il valore predefinito è bin/Debug/projectname.dacpac).
Passaggio 4: controllare il progetto nel controllo del codice sorgente
Il progetto verrà inizializzato come repository Git ed eseguirà il commit dei file di progetto nel controllo del codice sorgente. Questo passaggio è necessario per consentire la condivisione del progetto con altri utenti e per l'uso in una pipeline di distribuzione continua.
Dal menu Git in Visual Studio selezionare Crea repository Git.
Nella finestra di dialogo Crea un repository Git, in Esegui il push in una nuova sezione remoto scegliere GitHub.
Nella sezione Creare un nuovo repository GitHub della finestra di dialogo Crea un repository Git immettere il nome del repository che si vuole creare. (Se non è ancora stato eseguito l'accesso all'account GitHub, è possibile farlo anche da questa schermata).
In Inizializzare un repository Git locale è consigliabile usare l'opzione del modello .gitignore per specificare eventuali file intenzionalmente non registrati che si vuole ignorare da Git. Per altre informazioni su .gitignore, vedere Esclusione di file. Per altre informazioni sulle licenze, vedere Licenze di un repository.
Dopo aver eseguito l'accesso e immettere le informazioni sul repository, selezionare il pulsante Crea ed esegui push per creare il repository e aggiungere l'app.
In Esplora soluzioni fare clic con il pulsante destro del mouse sul nodo di progetto e scegliere Pubblica….
Verrà visualizzata la finestra di dialogo di pubblicazione, in cui si stabilisce la connessione al database di destinazione. Se non si dispone di un'istanza SQL esistente per la distribuzione, LocalDB ((localdb)\MSSQLLocalDB) viene installato con Visual Studio e può essere usato per il test e lo sviluppo.
Specificare un nome di database e selezionare Pubblica per distribuire il progetto nel database di destinazione o Genera script per generare uno script da rivedere prima dell'esecuzione.
È possibile inizializzare e pubblicare il repository locale direttamente in GitHub da VS Code o Azure Data Studio. Questa azione crea un nuovo repository nell'account GitHub ed esegue il push delle modifiche al codice locale nel repository remoto in un unico passaggio.
Usare il pulsante Pubblica in GitHub nella vista Controllo del codice sorgente in VS Code o Azure Data Studio. Verrà quindi richiesto di specificare un nome e una descrizione per il repository e anche se renderlo pubblico o privato.
In alternativa, è possibile inizializzare un repository locale ed eseguirne il push in GitHub seguendo i passaggi forniti quando si crea un repository vuoto in GitHub.
Inizializzare un nuovo repository Git nella directory del progetto ed eseguire il commit dei file di progetto nel controllo del codice sorgente.
git init
git add .
git commit -m "Initial commit"
Creare un nuovo repository GitHub e inviare il repository locale al repository remoto.
git remote add origin <repository-url>
git push -u origin main
Passaggio 5: aggiungere un passaggio di compilazione del progetto a una pipeline di distribuzione continua
I progetti SQL sono supportati da una libreria .NET e di conseguenza i progetti vengono compilati con il comando dotnet build. Questo comando è un elemento fondamentale anche delle pipeline di integrazione continua e distribuzione continua (CI/CD) più di base. Il passaggio di compilazione può essere aggiunto a una pipeline di distribuzione continua creata in GitHub actions.
Creare una nuova directory denominata
.github/workflowsnella radice del repository. Questa directory conterrà il file del flusso di lavoro che definisce la pipeline di distribuzione continua.Creare un nuovo file denominato
sqlproj-sample.ymlnella directory.github/workflows.Aggiungere il contenuto seguente al file
sqlproj-sample.yml, modificando il nome del progetto in modo che corrisponda al nome e al percorso del progetto:name: sqlproj-sample on: push: branches: [ "main" ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup .NET uses: actions/setup-dotnet@v4 with: dotnet-version: 8.0.x - name: Build run: dotnet build MyDatabaseProject.sqlprojEseguire il commit del file del flusso di lavoro nel repository ed eseguire il push delle modifiche nel repository remoto.
In GitHub.com passare alla pagina principale del repository. Sotto il nome del repository fare clic su Azioni. Nella barra laterale sinistra, selezionare il flusso di lavoro appena creato. Un'esecuzione recente del flusso di lavoro dovrebbe essere visualizzata nell'elenco delle esecuzioni del flusso di lavoro da quando è stato eseguito il push del file del flusso di lavoro nel repository.
Altre informazioni sui concetti fondamentali della creazione del primo flusso di lavoro di GitHub actions sono disponibili nella guida introduttiva di GitHub Actions.
Passaggio 6: aggiungere un passaggio di distribuzione .dacpac a una pipeline di distribuzione continua
Il modello compilato di uno schema di database in un file .dacpac può essere distribuito in un database di destinazione usando lo strumento utilità da riga di comando SqlPackage o altri strumenti di distribuzione. Il processo di distribuzione determina i passaggi necessari per aggiornare il database di destinazione in modo che corrisponda allo schema definito in .dacpac, creando o modificando oggetti in base alle esigenze basandosi sugli oggetti già esistenti nel database. Ad esempio, per distribuire un file .dacpac in un database di destinazione basato su un stringa di connessione:
sqlpackage /Action:Publish /SourceFile:bin/Debug/MyDatabaseProject.dacpac /TargetConnectionString:{yourconnectionstring}
Il processo di distribuzione è idempotente, ovvero può essere eseguito più volte senza causare problemi. La pipeline che si sta creando genererà e distribuirà il progetto SQL ogni volta che viene verificata una modifica nel ramo main del repository. Anziché eseguire il comando SqlPackage direttamente nella pipeline di distribuzione, è possibile usare un'attività di distribuzione che astrae il comando e fornisce funzionalità aggiuntive, ad esempio la registrazione, la gestione degli errori e la configurazione delle attività. L'attività di distribuzione GitHub sql-action può essere aggiunta a una pipeline di distribuzione continua in GitHub actions.
Nota
L'esecuzione di una distribuzione da un ambiente di automazione richiede la configurazione del database e dell'ambiente in modo che la distribuzione possa raggiungere il database ed eseguire l'autenticazione. In database SQL di Azure o SQL Server in una macchina virtuale, potrebbe essere necessario configurare una regola del firewall per consentire all'ambiente di automazione di connettersi al database e fornire un stringa di connessione con le credenziali necessarie. Le indicazioni sono disponibili nella documentazione di GitHub sql-action.
Aprire il file
sqlproj-sample.ymlnella directory.github/workflows.Aggiungere il passaggio seguente al file
sqlproj-sample.ymldopo il passaggio di compilazione:- name: Deploy uses: azure/sql-action@v2 with: connection-string: ${{ secrets.SQL_CONNECTION_STRING }} action: 'publish' path: 'bin/Debug/MyDatabaseProject.dacpac'Prima di eseguire il commit delle modifiche, aggiungere un segreto al repository contenente la stringa di connessione al database di destinazione. Nel repository in GitHub.com passare a Impostazioni e quindi Segreti. Selezionare Nuovo segreto del repository e aggiungere un segreto denominato
SQL_CONNECTION_STRINGcon il valore della stringa di connessione al database di destinazione.
Eseguire il commit delle modifiche da
sqlproj-sample.ymlal repository ed eseguire il push delle modifiche nel repository remoto.Tornare alla cronologia del flusso di lavoro in GitHub.com e selezionare l'esecuzione più recente del flusso di lavoro. Il passaggio di distribuzione deve essere visibile nell'elenco dei passaggi per l'esecuzione del flusso di lavoro e il flusso di lavoro restituisce un codice di operazione riuscita.
Verificare la distribuzione connettendosi al database di destinazione e verificando che gli oggetti nel progetto siano presenti nel database.
Le distribuzioni di GitHub possono essere ulteriormente protette stabilendo una relazione di ambiente in un flusso di lavoro e richiedendo l'approvazione prima dell'esecuzione di una distribuzione. Altre informazioni sulla protezione dell'ambiente e sulla protezione dei segreti sono disponibili nella documentazione di Github Actions.