Condividi tramite

SqlPackage

  • Articolo

SqlPackage è un'utilità della riga di comando che automatizza le attività di sviluppo del database esponendo alcune delle API di Application Framework (DacFx) pubbliche Data-Tier. 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.

Annotazioni

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 Extract and Publish , che creano e usano file DACPAC, che possono contenere i dati direttamente o i dati di riferimento archiviati in Archiviazione BLOB di Azure.

  • Esporta: esegue l'esportazione di un database SQL connesso, compreso lo schema del database e i dati degli utenti, in un file BACPAC (.bacpac).

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

Implementazioni

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 con estensione dacpac di origine, mentre l'azione Estrai crea un file di applicazione livello dati (con estensione dacpac) contenente lo schema o lo schema e i dati utente da un database SQL connesso. SqlPackage consente la distribuzione su database nuovi o esistenti dallo stesso artefatto (.dacpac) creando automaticamente un piano di distribuzione che effettuerà le modifiche necessarie sul database di destinazione. È possibile esaminare il piano di distribuzione prima di applicare le modifiche al database di destinazione con le azioni Script o DeployReport .

  • Estrarre: crea un file .dacpac di applicazione al livello dati contenente lo schema, oppure lo schema insieme ai dati utente, da un database SQL connesso.

  • Publish: aggiorna in modo incrementale uno schema del database in modo che corrisponda allo schema di un file con estensione dacpac di origine. Se il database non esiste nel server, l'operazione di pubblicazione lo crea. In caso contrario, viene aggiornato un database esistente.

  • DeployReport: crea un report XML che rappresenta le modifiche che verrà eseguita da un'azione di pubblicazione.

  • DriftReport: crea un report XML che rappresenta le modifiche applicate a un database registrato dall'ultima registrazione.

  • Script: crea uno script di aggiornamento incrementale Transact-SQL che aggiorna lo schema di una destinazione in modo che 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 specificati 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 singole azioni.

Comandi di utilità

Versione

Visualizza la versione di sqlpackage come numero di build. Può essere usato nei prompt interattivi e in pipeline automatizzate.

SqlPackage /Version

Aiuto

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

SqlPackage /?

Per informazioni sui parametri e sulle proprietà specifiche di una determinata azione, utilizzare il parametro di aiuto oltre al parametro di quell'azione.

SqlPackage /Action:Publish /?

Autenticazione

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

  • Autenticazione di SQL Server
  • Autenticazione di Active Directory (Windows)
  • Autenticazione Microsoft Entra
    • Nome utente/password
    • Autenticazione integrata
    • Autenticazione universale
    • Identità gestita
    • Service Principal

Identità gestita

Annotazioni

Microsoft Entra ID era noto in precedenza 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 la 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 che usa l'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 .

Service Principal

Annotazioni

Microsoft Entra ID era noto in precedenza 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 configurati nel portale di Azure durante il processo di registrazione dell'applicazione e configurati per accedere alle risorse di Azure, ad esempio Azure SQL. Per ulteriori informazioni sulla configurazione di un principale del servizio per il tuo ambiente, consulta la documentazione del principale del servizio.

Quando si usa SqlPackage con un'entità servizio, è possibile recuperare un 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. In questo processo, il sistema di richiamo mantiene il controllo sull'aggiornamento del token o sull'invalidazione. Il token di accesso può essere passato a SqlPackage usando il /at parametro .

# 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;"

In alternativa, è possibile passare il client ID e il segreto principale del servizio a SqlPackage nella stringa di connessione. Il formato della stringa di connessione include Authentication=Active Directory Service Principal; e User Id=AppId; Password=<password>. Quando si passano le credenziali dell'entità servizio nella stringa di connessione, il /at parametro non è obbligatorio e SqlPackage aggiornerà l'autenticazione in base alle esigenze durante l'operazione.

I principali del servizio sono supportati nelle pipeline CI/CD di Azure DevOps e GitHub Actions.

Variabili di ambiente

Pool di connessioni

Il pool di connessioni può essere abilitato per tutte le connessioni effettuate da SqlPackage impostando la CONNECTION_POOLING_ENABLED variabile di ambiente 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 da specificare /p:TempDirectoryForTableData per eseguire l'override 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. Percorso specificato dalla variabile di TMP ambiente.
  2. Percorso specificato dalla variabile di TEMP ambiente.
  3. Percorso specificato dalla variabile di USERPROFILE ambiente.
  4. Directory di Windows.

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

SqlPackage e utenti del database

Utenti del database contenuto sono inclusi nelle operazioni di SqlPackage. Tuttavia, la parte della password della definizione viene impostata su una stringa generata in modo casuale da SqlPackage, il valore esistente non viene trasferito. È consigliabile reimpostare la password del nuovo utente in un valore sicuro dopo l'importazione di un .bacpac oggetto o la distribuzione di un oggetto .dacpac. In un ambiente automatizzato è possibile recuperare i valori delle password da un archivio chiavi sicuro, ad esempio Azure Key Vault, in un passaggio che segue SqlPackage.

Raccolta dati di utilizzo

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

SqlPackage può raccogliere informazioni standard su computer, uso e 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 DACFX_TELEMETRY_OPTOUT di ambiente a true o 1.

Assistenza

La libreria DacFx e lo strumento dell'interfaccia della riga di comando di SqlPackage hanno adottato i criteri moderni relativi al ciclo di vita di Microsoft. Tutti gli aggiornamenti, le correzioni e le nuove funzionalità di sicurezza vengono rilasciati solo nella versione più recente della versione principale. La gestione delle installazioni dacFx o SqlPackage nella 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 SQL supportate al momento della versione SqlPackage/DacFx. Ad esempio, una versione di SqlPackage il 14 gennaio 2022 supporta tutte le versioni supportate di SQL nel 14 gennaio 2022. Per altre informazioni sui criteri di supporto SQL, vedere i criteri di supporto sql.

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

Passaggi successivi