Partager via

SqlPackage

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é en utilisant des actions Azure Pipelines et GitHub ou d’autres outils CI/CD.

Téléchargez la dernière version. 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 d’Azure SQL Database vers une instance SQL Server locale ou de SQL Server vers Azure SQL Database est un exemple de portabilité de base de données. SqlPackage prend en charge la portabilité de base de données via les actions d’exportation et d’importation, qui créent et consomment des fichiers BACPAC. SqlPackage prend également en charge la portabilité de la base de données via les actions d’extraction et de publication, qui créent et consomment des fichiers DACPAC, qui peuvent contenir les données directement ou référencer les données stockées dans stockage Blob Azure.

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

  • Importation : importe le schéma et les données de table à 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 Extract 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, l’opération de publication la crée. Dans le cas contraire, une base de données existante est mise à jour.

  • DeployReport : crée un rapport XML représentant les modifications qu’une action de publication effectuerait.

  • DriftReport : crée un rapport XML représentant les modifications appliqué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 de l’interface 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 de SQL Server
  • Authentification Active Directory (Windows)
  • Authentification Microsoft Entra
    • Nom d'utilisateur/mot de passe
    • Authentification intégrée
    • Authentification universelle
    • Identité managée
    • Service Principal

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 est la méthode d’authentification recommandée. Cette méthode ne nécessite pas de transmettre des informations d’identification à 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 informations d’identification. Lorsque l’identité managée est configurée pour l’environnement dans lequel l’action SqlPackage est exécutée, l’action SqlPackage peut utiliser cette identité pour s’authentifier auprès d’Azure SQL. Pour plus d’informations sur la configuration de l’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 Azure DevOps et GitHub Actions.

Service Principal

Remarque

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

Les principaux de service d’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 d’application et configurés pour accéder aux ressources Azure, comme Azure SQL. Pour plus d’informations sur la configuration d’un principal de service pour votre environnement, consultez la documentation du principal de service.

Lorsque vous utilisez SqlPackage avec un principal de service, vous pouvez récupérer un jeton d’accès et le transmettre à SqlPackage. Le jeton d’accès peut être récupéré à l’aide du module Azure PowerShell ou d’Azure CLI. Dans ce processus, le système appelant conserve le contrôle sur l’actualisation ou l’invalidation du jeton. 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;"

Vous pouvez également transmettre l’ID client et le secret du principal de service à SqlPackage dans la chaîne de connexion. Le format de chaîne de connexion inclut Authentication=Active Directory Service Principal; et User Id=AppId; Password=<password>. Lorsque les informations d’identification du principal de service sont transmises dans la chaîne de connexion, le paramètre /at n’est pas obligatoire et SqlPackage actualise l’authentification selon les besoins pendant l’opération.

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

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 les connexions de nom d’utilisateur et de mot de passe Microsoft Entra pour éviter la limitation par la bibliothèque d’authentification Microsoft (MSAL).

Fichiers temporaires

Lors des 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. Chemin spécifié par la variable d’environnement TMP.
  2. Chemin spécifié par la variable d’environnement TEMP.
  3. Chemin spécifié par la variable d’environnement USERPROFILE.
  4. Répertoire Windows.

Pour Linux et macOS, si le chemin n’est pas spécifié dans la variable d’environnement TMPDIR, le chemin par défaut /tmp/ 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é que le mot de passe du nouvel utilisateur soit réinitialisé à 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.

Extensibilité

SqlPackage prend en charge l’extensibilité par le biais de l’infrastructure d’extensibilité managée (MEF), ce qui permet des scénarios avancés via des composants personnalisés appelés contributeurs. Ces extensions peuvent personnaliser la façon dont SqlPackage publie des fichiers .dacpac, ce qui permet aux équipes d’appliquer des normes ou d’automatiser une logique spécifique au projet. Les contributeurs de déploiement sont exécutés dans le cadre du processus de publication, une fois le plan de déploiement généré, mais avant son exécution. Ces contributeurs peuvent accéder au plan de déploiement et le modifier à l’aide d’un objet de classe DeploymentPlanModifier pour ajouter, supprimer ou réorganiser des étapes. Pour commencer à utiliser l’extensibilité du déploiement, consultez Utiliser les contributeurs de déploiement pour personnaliser la génération et le déploiement de la base de données.

SqlPackage découvre et charge les assemblys contributeurs en analysant les bibliothèques de liens dynamiques (fichiers .dll) dans le même répertoire que l’exécutable SqlPackage, ainsi que les emplacements spécifiés via la propriété de ligne de commande /p:AdditionalDeploymentContributorPaths facultative. Bien que cela permet une personnalisation flexible, il introduit également des considérations de sécurité importantes.

Important

Étant donné que SqlPackage utilise MEF pour charger dynamiquement des bibliothèques de liens dynamiques (fichiers .dll) au moment de l’exécution, tous les assemblys placés en même temps que l’exécutable SqlPackage peuvent être exécutés dans le cadre du processus de déploiement. Un acteur malveillant peut exploiter ce comportement en introduisant des extensions falsifiées ou non autorisées qui exécutent du code arbitraire.

Il vous incombe de vous assurer que tous les fichiers d’extension compilés utilisés avec SqlPackage sont sécurisés et proviennent de sources approuvées. Nous vous recommandons de contrôler l’accès au dossier SqlPackage et de valider l’intégrité de tous les composants personnalisés ou tiers.

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. Afin d’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.

Soutien

La bibliothèque DacFx et l’outil CLI SqlPackage suivent la politique de cycle de vie moderne de Microsoft. Toutes les mises à jour de sécurité, correctifs et nouvelles fonctionnalités sont publiés uniquement dans la dernière version de point de la version principale. Conserver à jour vos installations de DacFx ou de SqlPackage permet de garantir que vous recevez 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 dépôt GitHub DacFx.

Produits SQL pris en charge

SqlPackage et DacFx prennent en charge toutes les versions de SQL prises en charge au moment de la publication de SqlPackage/DacFx. Par exemple, une version SqlPackage du 14 janvier 14 2022 prend en charge toutes les versions de SQL prises en charge au 14 janvier 14 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.

Outre SQL Server, SqlPackage et DacFx prennent en charge Azure SQL Managed Instance, Azure SQL Database, Azure Synapse Analytics et Fabric Data Warehouse.

Étapes suivantes

  • Last updated on