Partager via

Résoudre les problèmes et le niveau de performance avec SqlPackage

  • Article

Dans certains scénarios, les opérations SqlPackage prennent plus de temps que prévu ou échouent. Cet article décrit certaines tactiques fréquemment suggérées pour résoudre ou améliorer le niveau de performance de ces opérations. Tout en étudiant la page de documentation spécifique pour chaque action afin de comprendre les paramètres et propriétés disponibles, cet article sert de point de départ pour enquêter sur des opérations SqlPackage.

Stratégie globale

En règle générale, de meilleures performances peuvent être obtenues via la version .NET de SqlPackage au lieu de la version .NET Framework installée via le DacFramework.msi.

Si vous ne parvenez pas à installer l’outil Dotnet SqlPackage, qui active l’exécution de commandes SqlPackage à partir de l’invite de commandes dans n’importe quel annuaire :

  1. Téléchargez le fichier zip pour SqlPackage sur .NET 8 pour votre système d’exploitation (Windows, macOS ou Linux).
  2. Décompressez l’archive comme indiqué dans la page de téléchargement.
  3. Ouvrez une invite de commandes, puis accédez au répertoire SqlPackage à l’aide de la commande cd.

Il est important d’utiliser la dernière version disponible de SqlPackage en tant qu’améliorations du niveau de performance et des correctifs de bogues sont publiés régulièrement.

Remplacer SqlPackage pour le service Import/Export

Si vous avez tenté d’utiliser le service Import/Export pour importer ou exporter votre base de données, vous pouvez utiliser SqlPackage pour effectuer la même opération avec plus de contrôle sur les paramètres et les propriétés facultatifs.

Voici un exemple de commande pour l’importation :

./SqlPackage /Action:Import /sf:<source-bacpac-file-path> /tsn:<full-target-server-name> /tdn:<a new or empty database> /tu:<target-server-username> /tp:<target-server-password> /df:<log-file>

Voici un exemple de commande pour l’exportation :

./SqlPackage /Action:Export /tf:<target-bacpac-file-path> /ssn:<full-source-server-name> /sdn:<source-database-name> /su:<source-server-username> /sp:<source-server-password> /df:<log-file>

Solution remplaçant l’utilisation du nom d'utilisateur et du mot de passe, l'authentification multifacteur peut être utilisée pour s'authentifier par le biais de l'authentification Microsoft Entra (ancien Azure Active Directory). Remplacez les paramètres de nom d’utilisateur et de mot de passe pour /ua:true et /tid:"yourdomain.onmicrosoft.com".

Problèmes courants

Erreurs de délai d’expiration

Pour les problèmes liés aux délais d’expiration, les propriétés suivantes peuvent être utilisées pour paramétrer la connexion entre SqlPackage et l’instance SQL :

  • /p:CommandTimeout= : spécifie le délai d’expiration de la commande en secondes lorsqu’une requête est exécutée. Valeur par défaut : 60
  • /p:DatabaseLockTimeout= : spécifie le dépassement de délai d'attente de verrou de la base de données en secondes. -1 peut être utilisé pour attendre indéfiniment, par défaut : 60
  • /p:LongRunningCommandTimeout= : spécifie le délai d’expiration de la commande durable en secondes. La valeur par défaut, 0, est utilisée pour attendre indéfiniment.

Consommation de ressources client

Pour les commandes d’exportation et d’extraction, les données de table sont transmises à un répertoire temporaire à la mémoire tampon avant d’être écrites dans le fichier bacpac/dacpac. Cette exigence de stockage peut être volumineuse et est relative à la taille complète des données à exporter. Spécifiez un autre répertoire temporaire avec la propriété /p:TempDirectoryForTableData=<path>.

Le modèle de schéma est compilé en mémoire, de sorte que pour les schémas de base de données volumineux, les besoins en mémoire sur l’ordinateur client exécutant SqlPackage peuvent être significatifs.

Faible consommation des ressources du serveur

Par défaut, SqlPackage définit le parallélisme de serveur maximal sur 8. Si vous notez une faible consommation de ressources serveur, l’augmentation de la valeur du paramètre MaxParallelism peut améliorer le niveau de performance.

Access token (Jeton d’accès)

L’utilisation du paramètre /AccessToken: ou /at: active l’authentification basée sur les jetons pour SqlPackage, mais la transmission du jeton à la commande peut être délicat. Si vous analysez un objet de jeton d’accès dans PowerShell, transmettez explicitement la valeur de chaîne ou incluez dans un wrapper la référence à la propriété de jeton dans $(). Par exemple :

$Account = Connect-AzAccount -ServicePrincipal -Tenant $Tenant -Credential $Credential
$AccessToken_Object = (Get-AzAccessToken -Account $Account -Resource "https://database.windows.net/")
$AccessToken = $AccessToken_Object.Token

SqlPackage /at:$AccessToken
# OR
SqlPackage /at:$($AccessToken_Object.Token)

Connection

En cas d’échec de la connexion de SqlPackage, le chiffrement du serveur n’est peut-être pas activé ou le certificat configuré peut ne pas être émis à partir d’une autorité de certification approuvée (par exemple un certificat auto-signé). Vous pouvez modifier la commande SqlPackage pour vous connecter sans chiffrement ou pour faire confiance au certificat du serveur. La meilleure pratique consiste à s’assurer qu’une connexion chiffrée de confiance au serveur peut être établie.

  • Se connecter sans chiffrement : /SourceEncryptConnection:False ou /TargetEncryptConnection:False
  • Faire confiance au certificat de serveur : /SourceTrustServerCertificate:True ou /TargetTrustServerCertificate:True

L’un des messages d’avertissement suivants peut s’afficher lors de la connexion à une instance SQL, indiquant que les paramètres de ligne de commande peuvent nécessiter des modifications pour se connecter au serveur :

The settings for connection encryption or server certificate trust may lead to connection failure if the server is not properly configured.
The connection string provided contains encryption settings which may lead to connection failure if the server is not properly configured.

Pour en savoir plus sur les modifications apportées à la sécurité des connexions dans SqlPackage, reportez-vous à Améliorations de la sécurité des connexions dans SqlPackage 161.

Erreur d’action d’importation 2714 pour contrainte

Lorsque vous effectuez une action d’importation, vous pouvez recevoir l’erreur 2714 si un objet existe déjà :

*** Error importing database:Could not import package.
Error SQL72014: Core Microsoft SqlClient Data Provider: Msg 2714, Level 16, State 5, Line 1 There is already an object named 'DF_Department_ModifiedDate_0FF0B724' in the database.
Error SQL72045: Script execution error. The executed script:
ALTER TABLE [HumanResources].[Department]
    ADD CONSTRAINT [DF_Department_ModifiedDate_] DEFAULT ('') FOR [ModifiedDate];

Les causes et solutions pour contourner cette erreur sont les suivantes :

  1. Vérifiez que la destination dans laquelle vous importez est une base de données vide.
  2. Si votre base de données a des contraintes qui utilisent l’attribut DEFAULT (où SQL Server attribue un nom aléatoire à la contrainte) ainsi qu’une contrainte explicitement nommée, il se peut qu’une contrainte portant le même nom soit créée deux fois. Il est recommandé d’utiliser toutes les contraintes explicitement nommées (sans utiliser l’attribut DEFAULT) ou tous les noms définis par le système (en utilisant l’attribut DEFAULT).
  3. Modifiez manuellement le fichier model.xml et renommez la contrainte portant le nom à l’origine de l’erreur en un nom unique. Cette option ne doit être entreprise que sur instruction du support Microsoft et présente un risque de corruption du .bacpac.

Exception de Stack Overflow

Les scripts T-SQL volumineux avec de nombreuses instructions imbriquées sont souvent la cause d’exceptions de stack Overflow intermittentes ou persistantes. Lorsque c’est le cas, le message d’erreur comprend le texte Stack overflow et un rapport des appels de procédure :

Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor.Visit(Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression)
Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor.ExplicitVisit(Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression)
Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression.Accept(Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor)
Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression.AcceptChildren(Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor)
Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression.Accept(Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor)
Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression.AcceptChildren(Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor)

Un paramètre pour SqlPackage est disponible sur toutes les commandes, /ThreadMaxStackSize:qui spécifie la taille de pile maximale pour le thread exécutant le processus SqlPackage. La valeur par défaut est déterminée par la version .NET exécutant SqlPackage. La définition d’une valeur importante peut avoir un impact sur les performances globales de SqlPackage, mais l’augmentation de cette valeur pourrait résoudre l’exception de stack overflow provoquée par des instructions imbriquées. La refactorisation du code T-SQL est recommandée pour éviter les exceptions de stack overflow dans la mesure du possible, mais le /ThreadMaxStackSize: paramètre peut être utilisé comme solution de contournement.

Lorsque vous utilisez le paramètre /ThreadMaxStackSize:, il est recommandé d’ajuster les opérations répétées à la valeur la plus basse qui résout l’exception de stack overflow si l’impact sur les performances est noté. La valeur du paramètre est en mégaoctets (Mo), par exemple les valeurs de test comme solution de contournement comprennent 10 et 100.

Diagnostics

Les journaux sont essentiels à la résolution des problèmes. Capturez les journaux de diagnostic dans un fichier avec le paramètre /DiagnosticsFile:<filename>.

Il est possible d’enregistrer davantage de données de trace liées aux performances en définissant la variable d’environnement DACFX_PERF_TRACE=true avant d’exécuter SqlPackage. Pour définir cette variable d’environnement dans PowerShell, utilisez la commande suivante :

Set-Item -Path Env:DACFX_PERF_TRACE -Value true

Conseils sur les actions d’importation

Pour les importations qui contiennent des tables volumineuses ou des tables dotées de nombreux index, l’utilisation de /p:RebuildIndexesOfflineForDataPhase=True ou de /p:DisableIndexesForDataPhase=False peut améliorer les performances. Ces propriétés modifient l’opération de reconstruction d’index pour qu’elle se produise hors connexion ou qu’elle ne se produise pas, respectivement. Ces propriétés et d’autres sont disponibles pour paramétrer l’opération Import de SqlPackage.

Conseils sur les actions d’exportation

Une cause courante de détérioration des performances lors de l’exportation est des références d’objet non résolues, ce qui entraîne la tentative par SqlPackage de résolution de l’objet plusieurs fois. Par exemple, un affichage est défini référençant une table et la table n’existe plus dans la base de données. Si des références non résolues apparaissent dans le journal d’exportation, envisagez de corriger le schéma de la base de données pour améliorer les performances d’exportation.

Dans les scénarios où l’espace disque du système d’exploitation est limité et vient à manquer pendant l’exportation, l’utilisation de /p:TempDirectoryForTableData permet aux données à exporter d’être mises en mémoire tampon sur un autre disque. L’espace requis pour cette action peut être important et dépend de la taille totale de la base de données. Ces propriétés et d’autres sont disponibles pour paramétrer l’opération Export de SqlPackage.

Pendant un processus d’exportation, les données de table sont compressées dans le fichier bacpac. L’utilisation de /p:CompressionOption défini sur Fast, SuperFast ou NotCompressed peut améliorer la vitesse du processus d’exportation tout en compressant moins le fichier bacpac de sortie.

Pour obtenir le schéma et les données de la base de données tout en passant la validation du schéma, effectuez une exportation avec /p:VerifyExtraction=False. Une exportation non valide peut être produite qui ne peut pas être importée.

Azure SQL Database

Les conseils suivants sont spécifiques à l’exécution de l’importation ou de l’exportation sur Azure SQL Database à partir d’une machine virtuelle Azure :

  • Utilisez la base de données critique pour l'entreprise ou de niveau Premium pour des performances optimales.
  • Utilisez le stockage SSD sur l’ordinateur virtuel.
  • Assurez-vous qu’il y a suffisamment de place pour décompresser le bacpac.
  • Exécutez SqlPackage à partir d’une machine virtuelle dans la même région que la base de données.
  • Activez les performances réseau accélérées pour la machine virtuelle.

Pour en savoir plus sur l’utilisation d’un script PowerShell pour collecter plus d’informations sur une opération d’importation, reportez-vous à Leçon apprise #211 : surveillance du processus d’importation SQLPackage.

Plus de ressources

Le blog du support de la base de données Azure SQL contient de nombreux articles sur le dépannage et le réglage des performances pour la base de données Azure SQL, y compris plusieurs articles sur SqlPackage.

Quelques-uns des articles les plus pertinents :

Contenu connexe