SqlPackage

  • Articolo

SqlPackage è un'utilità della riga di comando che consente di automatizzare le attività di sviluppo del database esponendo alcune delle API pubbliche DacFx (Data-Tier Application Framework). I casi d'uso principali per SqlPackage riguardano la portabilità e le distribuzioni del database per la famiglia di database SQL Server, Azure SQL e Azure Synapse Analytics. SqlPackage può essere automatizzato usando Azure Pipelines e GitHub Actions o altri strumenti CI/CD.

Scaricare la versione più recente. Per informazioni dettagliate sulla versione più recente, vedere le note sulla versione.

Nota

Anche se Microsoft Entra ID è il nuovo nome per Azure Active Directory (Azure AD), per evitare l'interruzione degli ambienti esistenti, la denominazione Azure AD è tuttora mantenuta in alcuni elementi hardcoded, ad esempio campi dell'interfaccia utente, provider di connessioni, codici errore e cmdlet. All’interno di questo articolo i due nomi vengono utilizzati in modo intercambiabile.

Portabilità

La portabilità del database è la possibilità di spostare uno schema e dati di database tra istanze diverse di SQL Server, AZURE SQL e Azure Synapse Analytics. L'esportazione di un database dal database SQL di Azure a un'istanza di SQL Server locale o da SQL Server al database SQL di Azure sono esempi di portabilità del database. SqlPackage supporta la portabilità del database tramite le azioni Esporta e Importa, che creano e utilizzano file BACPAC. SqlPackage supporta anche la portabilità del database tramite le azioni Estrai e Pubblica, che creano e utilizzano file DACPAC, che possono contenere i dati direttamente o i dati di riferimento archiviati in Archiviazione BLOB di Azure.

  • Esportazione: esporta un database SQL connesso, inclusi lo schema del database e i dati utente, in un file BACPAC (con estensione bacpac).

  • Importazione: importa lo schema e i dati della tabella da un file BACPAC in un nuovo database utente.

Deployments

Le distribuzioni di database sono il processo di aggiornamento di uno schema di database in modo che corrisponda a uno stato desiderato, ad esempio l'aggiunta di colonne a una tabella o la modifica del contenuto di una stored procedure. SqlPackage supporta le distribuzioni di database tramite le azioni Pubblica ed Estrai. L'azione Pubblica aggiorna uno schema del database in modo che corrisponda al contenuto di un file .dacpac di origine, mentre l'azione Estrai crea un file di applicazione livello dati (.dacpac) contenente lo schema o lo schema e i dati utente da un database SQL connesso. SqlPackage abilita le distribuzioni su database nuovi o esistenti dallo stesso artefatto (.dacpac) creando automaticamente un piano di distribuzione che applicherà le modifiche necessarie al database di destinazione. È possibile esaminare il piano di distribuzione prima di applicare le modifiche al database di destinazione con le azioni Script o DeployReport.

  • Estrazione: crea un file dell'applicazione livello dati (con estensione dacpac) contenente lo schema o lo schema e i dati utente da un database SQL connesso.

  • Publish: aggiorna in modo incrementale uno schema di database affinché corrisponda allo schema di un file di origine con estensione dacpac. Se il database non esiste nel server, viene creato durante l'operazione di pubblicazione. In caso contrario, verrà aggiornato un database esistente.

  • DeployReport: crea un report XML delle modifiche che verrebbero effettuate da un'azione di pubblicazione.

  • DriftReport: crea un report XML delle modifiche apportate a un database registrato dall'ultima registrazione.

  • Script: crea uno script di aggiornamento incrementale Transact-SQL che aggiorna lo schema di una destinazione affinché corrisponda allo schema di un'origine.

Sintassi della riga di comando

SqlPackage avvia le azioni specificate usando i parametri, le proprietà e le variabili SQLCMD indicati nella riga di comando.

SqlPackage {parameters} {properties} {SQLCMD variables}

Altre informazioni sulla sintassi della riga di comando di SqlPackage sono descritte in dettaglio nelle pagine di riferimento dell'interfaccia della riga di comando di SqlPackage e nelle pagine delle singole azioni.

Comandi di utilità

Versione

Visualizza la versione di sqlpackage come numero di build. Può essere usato nei prompt interattivi, nonché nelle pipeline automatizzate.

SqlPackage /Version

Help

È possibile visualizzare le informazioni sull'utilizzo di SqlPackage usando /? o /help:True.

SqlPackage /?

Per informazioni sui parametri e sulle proprietà specifici di una determinata azione, usare il parametro della Guida oltre al parametro dell'azione.

SqlPackage /Action:Publish /?

Autenticazione

SqlPackage esegue l'autenticazione usando i metodi disponibili in SqlClient. La configurazione del tipo di autenticazione può essere eseguita tramite i parametri stringa di connessione per ogni azione SqlPackage (/SourceConnectionString e /TargetConnectionString) o tramite singoli parametri per le proprietà di connessione. In un stringa di connessione sono supportati i metodi di autenticazione seguenti:

  • Autenticazione di SQL Server
  • Autenticazione di Active Directory (Windows)
  • Autenticazione Microsoft Entra
    • Nome utente e password
    • Autenticazione integrata
    • Autenticazione universale
    • Identità gestita
    • Entità servizio

Identità gestita

Nota

Microsoft Entra ID era precedentemente conosciuto come Azure Active Directory (Azure AD).

Negli ambienti automatizzati, l'identità gestita di Microsoft Entra è il metodo di autenticazione consigliato. Questo metodo non richiede il passaggio di credenziali a SqlPackage in fase di esecuzione perché SqlPackage usa le identità gestite per connettersi ai database che supportano l'autenticazione di Microsoft Entra e per ottenere i token di Microsoft Entra, senza gestione delle credenziali. Quando l'identità gestita è configurata per l'ambiente in cui viene eseguita l'azione SqlPackage, l'azione SqlPackage può usare tale identità per l'autenticazione in Azure SQL. Per altre informazioni sulla configurazione di un'identità gestita per l'ambiente, vedere la documentazione sull'identità gestita.

Una stringa di connessione di esempio l'uso dell'identità gestita assegnata dal sistema è:

Server=sampleserver.database.windows.net; Authentication=Active Directory Managed Identity; Database=sampledatabase;

Le identità gestite sono supportate nelle pipeline CI/CD di Azure DevOps e GitHub Actions.

Entità servizio

Nota

Microsoft Entra ID era precedentemente conosciuto come Azure Active Directory (Azure AD).

Le entità servizio dell'applicazione Microsoft Entra sono oggetti di sicurezza all'interno di un'applicazione Microsoft Entra che definiscono le operazioni che un'applicazione può eseguire in un determinato tenant. Vengono impostate nel portale di Azure durante il processo di registrazione dell'applicazione e configurate per accedere alle risorse di Azure, ad esempio Azure SQL. Per altre informazioni sulla configurazione di un'entità servizio per l'ambiente, vedere la documentazione dell'entità servizio.

Quando si usa SqlPackage con un'entità servizio, potrebbe essere necessario recuperare il token di accesso e passarlo a SqlPackage. Il token di accesso può essere recuperato usando il modulo Azure PowerShell o l'interfaccia della riga di comando di Azure. Il token di accesso può essere passato a SqlPackage usando il parametro /at.

# example export connecting using an access token associated with a service principal
$Account = Connect-AzAccount -ServicePrincipal -Tenant $Tenant -Credential $Credential
$AccessToken_Object = (Get-AzAccessToken -Account $Account -ResourceUrl "https://database.windows.net/")
$AccessToken = $AccessToken_Object.Token

SqlPackage /at:$AccessToken /Action:Export /TargetFile:"C:\AdventureWorksLT.bacpac" \
    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
# OR
SqlPackage /at:$($AccessToken_Object.Token) /Action:Export /TargetFile:"C:\AdventureWorksLT.bacpac" \
    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"

Le entità servizio sono supportate nelle pipeline CI/CD di Azure DevOps e GitHub Actions.

Variabili di ambiente

Pool di connessioni

Il pooling di connessioni può essere abilitato per tutte le connessioni effettuate da SqlPackage impostando la variabile di ambiente CONNECTION_POOLING_ENABLED su True. Questa impostazione è consigliata per le operazioni con le connessioni con nome utente e password di Microsoft Entra per evitare la limitazione da parte di Microsoft Authentication Library (MSAL).

File temporanei

Durante le operazioni di SqlPackage, i dati della tabella vengono scritti in file temporanei prima della compressione o dopo la decompressione. Per i database di grandi dimensioni, questi file temporanei possono richiedere una quantità significativa di spazio su disco, ma è possibile specificarne la posizione. Le operazioni di esportazione ed estrazione includono una proprietà facoltativa per specificare /p:TempDirectoryForTableData per eseguire la sostituzione del valore predefinito di SqlPackage.

L'API .NET GetTempPath viene usata per determinare il valore predefinito all'interno di SqlPackage.

Per Windows, le variabili di ambiente seguenti vengono controllate nell'ordine seguente e viene usato il primo percorso esistente:

  1. Il percorso specificato dalla variabile di ambiente TMP.
  2. Il percorso specificato dalla variabile di ambiente TEMP.
  3. Il percorso specificato dalla variabile di ambiente USERPROFILE.
  4. La directory di Windows.

Per Linux e macOS, se il percorso non è specificato nella variabile di ambiente TMPDIR, viene usato il percorso predefinito /tmp/.

SqlPackage e utenti di database

Gli utenti di database indipendenti sono inclusi nelle operazioni SqlPackage. Tuttavia, la parte della password della definizione viene impostata su una stringa generata in modo casuale da SqlPackage e il valore esistente non viene trasferito. È consigliabile reimpostare la password del nuovo utente su un valore sicuro dopo l'importazione di un file .bacpac o la distribuzione di un file .dacpac. In un ambiente automatizzato i valori delle password possono essere recuperati da un archivio chiavi sicuro, ad esempio Azure Key Vault, in un passaggio successivo all'esecuzione di SqlPackage.

Raccolta dati di utilizzo

SqlPackage contiene funzionalità abilitate per Internet che consentono di raccogliere e inviare a Microsoft dati anonimi di diagnostica e di utilizzo delle funzionalità.

SqlPackage può raccogliere informazioni standard sul computer, sull'uso e sulle prestazioni che possono essere trasmesse a Microsoft e analizzate per migliorare la qualità, la sicurezza e l'affidabilità di SqlPackage.

SqlPackage non raccoglie informazioni personali o specifiche dell'utente. Per semplificare l'approssimazione di un singolo utente a scopo di diagnostica, SqlPackage genera un GUID casuale per ogni computer in cui viene eseguito e usa tale valore per tutti gli eventi inviati.

Per informazioni dettagliate, vedere l'Informativa sulla privacy di Microsoft e Supplemento alla privacy di SQL Server.

Disabilitare la creazione di report di telemetria

Per disabilitare la raccolta e la creazione di report di telemetria, aggiornare la variabile di ambiente DACFX_TELEMETRY_OPTOUT a true o 1.

Supporto tecnico

La libreria DacFx e lo strumento dell'interfaccia della riga di comando SqlPackage hanno adottato i criteri del ciclo di vita moderni Microsoft. Gli aggiornamenti di sicurezza, le correzioni e le nuove funzionalità verranno tutti rilasciati nella versione con punto più recente della versione principale. Mantenere aggiornate le installazioni DacFx o SqlPackage con la versione corrente consente di assicurarsi di ricevere tutte le correzioni di bug applicabili in modo tempestivo.

Ottenere assistenza con SqlPackage, inviare richieste di funzionalità e segnalare i problemi nel repository GitHub di DacFx.

Offerte di SQL supportate

SqlPackage e DacFx supportano tutte le versioni di SQL supportate al momento del rilascio di SqlPackage/DacFx. Ad esempio, una versione di SqlPackage del 14 gennaio 2022 supporta tutte le versioni supportate di SQL al 14 gennaio 2022. Per altre informazioni sui criteri di supporto per SQL, vedere i criteri di supporto per SQL.

Oltre a SQL Server, SqlPackage e DacFx supportano Istanza gestita di SQL di Azure, database SQL di Azure, Azure Synapse Analytics e Synapse Data Warehouse in Microsoft Fabric.

Passaggi successivi