SqlPackage

  • Article

SqlPackage est un utilitaire en ligne de commande qui automatise les tâches de développement de bases de données suivantes en exposant certaines API DacFx (Data-Tier Application Framework) publiques :

  • Version : retourne le numéro de build de l’application SqlPackage.

  • 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.

  • 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.

  • 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.

L’outil en ligne de commande de SqlPackage vous permet de spécifier ces actions à l’aide de paramètres et de propriétés spécifiques aux actions.

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.

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}

Codes de sortie

Les commandes SqlPackage retournent les codes de sortie suivants :

  • 0 = réussite
  • nonzero = échec

Exemple d’utilisation

D’autres exemples sont disponibles dans les pages d’action individuelles.

Création d’un fichier .dacpac du schéma de base de données actuel :

SqlPackage /TargetFile:"C:\sqlpackageoutput\output_current_version.dacpac" /Action:Extract /SourceServerName:"." /SourceDatabaseName:"Contoso.Database"

Paramètres

Certains paramètres sont partagés entre les actions SqlPackage. Voici un tableau résumant les paramètres : pour plus d’informations, cliquez sur les pages d’actions spécifiques.

Paramètre Forme abrégée Extraction Publier Export Importer DeployReport DriftReport Script
/AccessToken: /at x x x x x x x
/ClientId: /cid x
/DeployScriptPath: /dsp x x
/DeployReportPath: /drp x x
/Diagnostics: /d x x x x x x x
/DiagnosticsFile : /df x x x x x x x
/MaxParallelism: /mp x x x x x x x
/OutputPath: /op x x x
/OverwriteFiles: /of x x x x x x
/Profile: /pr x x x
/Properties: /p x x x x x x
/Quiet: /q x x x x x x x
/Secret: /secr x
/SourceConnectionString: /scs x x x x x
/SourceDatabaseName: /sdn x x x x x
/SourceEncryptConnection: /sec x x x x x
/SourceFile: /sf x x x x
/SourcePassword: /sp x x x x x
/SourceServerName: /ssn x x x x x
/SourceTimeout : /st x x x x x
/SourceTrustServerCertificate: /stsc x x x x x
/SourceUser: /su x x x x x
/TargetConnectionString: /tcs x x x x
/TargetDatabaseName: /tdn x x x x x
/TargetEncryptConnection: /tec x x x x x
/TargetFile : /tf x x x x
/TargetPassword: /tp x x x x x
/TargetServerName: /tsn x x x x x
/TargetTimeout: /tt x x x x x
/TargetTrustServerCertificate: /ttsc x x x x x
/TargetUser: /tu x x x x x
/TenantId: /tid x x x x x x x
/UniversalAuthentication: /ua x x x x x x x
/Variables: /v x x

Propriétés

Les actions SqlPackage prennent en charge un grand nombre de propriétés pour modifier le comportement par défaut d’une action. Pour plus d’informations, cliquez sur les pages des actions spécifiques.

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 transmission d’informations d’identification à SqlPackage au moment de l’exécution. 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;

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.

Étapes suivantes