SqlPackage

  • Article

SqlPackage est un utilitaire en ligne de commande qui automatise les tâches de développement de bases de données en exposant certaines API DacFx (Data-Tier Application Framework) publiques. Les principaux cas d’usage pour SqlPackage se concentrent sur la portabilité et les déploiements de base de données pour la famille de bases de données SQL Server, Azure SQL et Azure Synapse Analytics. SqlPackage peut être automatisé à l’aide d’Azure Pipelines et GitHub ou d’autres outils CI/CD.

Téléchargez la version la plus récente. Pour plus d’informations sur la dernière version, consultez les notes de publication.

Remarque

Bien que Microsoft Entra ID soit le nouveau nom d’Azure Active Directory (Azure AD) pour empêcher l’interruption des environnements existants, Azure AD reste toujours dans certains éléments codés en dur, tels que les champs d’interface utilisateur, les fournisseurs de connexions, les codes d’erreur et cmdlets. Dans cet article, les deux noms sont interchangeables.

Portabilité

La portabilité de base de données est la possibilité de déplacer un schéma de base de données et des données entre différentes instances de SQL Server, Azure SQL et Azure Synapse Analytics. L’exportation d’une base de données Azure SQL vers une instance SQL Server locale ou de SQL Server vers la base de données Azure SQL est un exemple de portabilité de base de données. SqlPackage prend en charge la portabilité de base de données via les actions Exportation et Importation, qui créent et consomment des fichiers BACPAC. SqlPackage prend également en charge la portabilité de base de données via les actions Extraire et Publier, qui créent et consomment des fichiers DACPAC, qui peuvent contenir les données directement ou les données de référence stockées dans Stockage Blob Azure.

  • Exporter : Exporte une base de données SQL connectée, y compris le schéma de base de données et les données utilisateur, dans un fichier BACPAC (.bacpac).

  • Importer : Importe le schéma et les données des tables à partir d’un fichier BACPAC dans une nouvelle base de données utilisateur.

Déploiements

Les déploiements de base de données sont le processus de mise à jour d’un schéma de base de données pour qu’il corresponde à un état souhaité, comme l’ajout de colonnes à une table ou la modification du contenu d’une procédure stockée. SqlPackage prend en charge les déploiements de base de données via les actions Publier et Extraire. L’action Publier met à jour un schéma de base de données pour qu’il corresponde au contenu d’un fichier .dacpac source, tandis que l’action Extraire crée un fichier d’application de la couche Données (.dacpac) contenant le schéma ou le schéma et les données utilisateur d’une base de données SQL connectée. SqlPackage active les déploiements sur les bases de données nouvelles ou existantes à partir du même artefact (.dacpac) en créant automatiquement un plan de déploiement qui applique les modifications nécessaires à la base de données cible. Le plan de déploiement peut être examiné avant d’appliquer les modifications à la base de données cible avec les actions Script ou DeployReport.

  • Extraire : Crée un fichier d’application de la couche Données (.dacpac) contenant le schéma, ou le schéma et les données utilisateur à partir d’une base de données SQL connectée.

  • Publier : met à jour de manière incrémentielle un schéma de base de données pour qu’il corresponde au schéma d’un fichier .dacpac source. Si la base de données n’existe pas sur le serveur, elle est créée par l’opération de publication. Dans le cas contraire, une base de données existante est mise à jour.

  • DeployReport : crée un rapport XML sur les modifications devant être apportées par une action de publication.

  • DriftReport : crée un rapport XML sur les modifications apportées à une base de données inscrite depuis sa dernière inscription.

  • Script : crée un script de mise à jour incrémentielle Transact-SQL qui met à jour le schéma d’une cible afin qu’il corresponde au schéma d’une source.

Syntaxe de ligne de commande

SqlPackage lance les actions spécifiées en utilisant les paramètres, propriétés et variables SQLCMD spécifiées sur la ligne de commande.

SqlPackage {parameters} {properties} {SQLCMD variables}

Pour plus d’informations sur la syntaxe de ligne de commande SqlPackage, consultez les pages de référence CLI SqlPackage et les pages d’action individuelles.

Commandes utilitaires

Version

Affiche la version sqlpackage comme numéro de build. Peut être utilisé dans les invites interactives et dans les pipelines automatisés.

SqlPackage /Version

Aide

Vous pouvez afficher les informations sur l’utilisation de SqlPackage à l’aide de /? ou de /help:True.

SqlPackage /?

Pour obtenir des informations sur les paramètres et les propriétés spécifiques à une action, utilisez le paramètre help en plus du paramètre de cette action.

SqlPackage /Action:Publish /?

Authentification

SqlPackage s’authentifie à l’aide des méthodes disponibles dans SqlClient. La configuration du type d’authentification peut être effectuée via les paramètres de chaîne de connexion pour chaque action SqlPackage (/SourceConnectionString et /TargetConnectionString) ou via des paramètres individuels pour les propriétés de connexion. Les méthodes d’authentification suivantes sont prises en charge dans une chaîne de connexion :

  • Authentification SQL Server
  • Authentification Active Directory (Windows)
  • Authentification Microsoft Entra
    • Nom d’utilisateur/mot de passe
    • Authentification intégrée
    • Authentification universelle
    • Identité gérée
    • Principal du service

Identité managée

Remarque

Microsoft Entra ID était précédemment connu sous le nom d’Azure Active Directory (Azure AD).

Dans les environnements automatisés, l’identité managée Microsoft Entra renvoie à la méthode d’authentification recommandée. Cette méthode ne nécessite pas de transmettre des identifiants à SqlPackage au moment de l’exécution, car SqlPackage utilise des identités managées pour se connecter aux bases de données qui prennent en charge l’authentification Microsoft Entra et pour obtenir des jetons Microsoft Entra, sans gestion des identifiants. Quand l’identité managée est configurée pour l’environnement dans lequel l’action SqlPackage est exécutée, l’action SqlPackage utilise cette identité pour s’authentifier auprès d’Azure SQL. Pour plus d’informations sur la configuration d’une identité managée pour votre environnement, consultez la documentation relative aux identités managées.

Voici un exemple de chaîne de connexion utilisant une identité managée affectée par le système :

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

Les identités managées sont prises en charge dans les pipelines CI/CD d’actions Azure DevOps et GitHub.

Principal du service

Remarque

Microsoft Entra ID était précédemment connu sous le nom d’Azure Active Directory (Azure AD).

Les principaux de service de l’application Microsoft Entra sont des objets de sécurité au sein d’une application Microsoft Entra qui définissent ce qu’une application peut faire dans un locataire donné. Ils sont configurés dans le Portail Azure pendant le processus d’inscription de l’application et configurés pour accéder aux ressources Azure, telles qu’Azure SQL. Pour plus d’informations sur la configuration d’un principal de service pour votre environnement, consultez la documentation du principal de service.

Lors de l’utilisation de SqlPackage avec un principal de service, il peut être nécessaire de récupérer le jeton d’accès et de le transmettre à SqlPackage. Le jeton d’accès peut être récupéré à l’aide du module Azure PowerShell ou d’Azure CLI. Le jeton d’accès peut être transmis à SqlPackage à l’aide du paramètre /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;"

Les principaux de service sont pris en charge dans les pipelines CI/CD d’actions Azure DevOps et GitHub.

Variables d’environnement

Regroupement de connexions

Le regroupement de connexions peut être activé pour toutes les connexions établies par SqlPackage en définissant la variable d’environnement CONNECTION_POOLING_ENABLED sur True. Ce paramètre est recommandé pour les opérations avec des connexions utilisant un nom d’utilisateur et un mot de passe Microsoft Entra pour éviter la limitation par la bibliothèque d’authentification Microsoft (MSAL).

Fichiers temporaires

Durant les opérations SqlPackage, les données de table sont écrites dans des fichiers temporaires avant la compression ou après la décompression. Pour les bases de données volumineuses, ces fichiers temporaires peuvent utiliser une quantité importante d’espace disque, mais leur emplacement peut être spécifié. Les opérations d’exportation et d’extraction incluent une propriété facultative qui permet de spécifier /p:TempDirectoryForTableData pour remplacer la valeur par défaut de SqlPackage.

L’API .NET GetTempPath est utilisée pour déterminer la valeur par défaut dans SqlPackage.

Pour Windows, les variables d’environnement suivantes sont vérifiées dans l’ordre qui suit et le premier chemin existant est utilisé :

  1. Le chemin d’accès spécifié par la variable d’environnement TMP.
  2. Le chemin d’accès spécifié par la variable d’environnement TEMP.
  3. Le chemin d’accès spécifié par la variable d’environnement USERPROFILE.
  4. Répertoire Windows.

Pour Linux et macOS, si le chemin d’accès n’est pas spécifié dans la variable d’environnement TMPDIR, celui /tmp/ par défaut est utilisé.

Utilisateurs de SqlPackage et de base de données

Les utilisateurs de base de données autonome sont inclus dans les opérations SqlPackage. Toutefois, la partie mot de passe de la définition est définie sur une chaîne générée de manière aléatoire par SqlPackage et la valeur existante n’est pas transférée. Il est recommandé de réinitialiser le mot de passe de l’utilisateur nouveau à une valeur sécurisée après l’importation d’un .bacpac ou le déploiement d’un .dacpac. Dans un environnement automatisé, les valeurs de mot de passe peuvent être récupérées à partir d’un magasin de clés sécurisé, tel qu’Azure Key Vault, à l’étape suivante de SqlPackage.

Collecte des données d’utilisation

SqlPackage contient des fonctionnalités Internet qui permettent de collecter et d’envoyer à Microsoft des données anonymes de diagnostic et d’utilisation des fonctionnalités.

SqlPackage peut collecter des informations standard sur l’ordinateur, l’utilisation et les performances qui peuvent être transmises à Microsoft et analysées pour améliorer la qualité, la sécurité et la fiabilité de SqlPackage.

SqlPackage ne collecte pas d’informations personnelles ou spécifiques à l’utilisateur. Pour estimer la moyenne d’un utilisateur unique à des fins de diagnostic, SqlPackage génère un GUID aléatoire pour chaque ordinateur sur lequel il s’exécute et utilise cette valeur pour tous les événements qu’il envoie.

Pour plus d’informations, consultez la Déclaration de confidentialité Microsoft et l’Avenant à la déclaration de confidentialité de SQL Server.

Désactiver la création de rapports de télémétrie

Pour désactiver la collecte et la création de rapports des données de télémétrie, mettez à jour la variable d’environnement DACFX_TELEMETRY_OPTOUT en la définissant sur true ou 1.

Support

La bibliothèque DacFx et l’outil CLI SqlPackage ont adopté la politique de cycle de vie moderne de Microsoft. Toutes les mises à jour de sécurité, les correctifs et les nouvelles fonctionnalités sont uniquement publiées dans la dernière version ponctuelle de la version principale. Le maintien de vos installations de DacFx ou de SqlPackage au version actuelle permet de garantir que vous recevrez tous les correctifs de bogues applicables en temps voulu.

Obtenez de l’aide sur SqlPackage, envoyez des demandes de fonctionnalités et signalez des problèmes dans le référentiel GitHub DacFx.

Produits SQL pris en charge

SqlPackage et DacFx supportent toutes les versions de SQL prises en charge au moment de la publication de SqlPackage/DacFx. Par exemple, une version SqlPackage du 14 janvier 2022 prend en charge toutes les versions de SQL supportées au 14 janvier 2022. Pour plus d’informations sur les stratégies de prise en charge de SQL, consultez la stratégie de prise en charge de SQL.

En plus de SQL Server, SqlPackage et DacFx prennent en charge Azure SQL Managed Instance, la base de données Azure SQL, Azure Synapse Analytics et Synapse Data Warehouse dans Microsoft Fabric.

Étapes suivantes