Solución de problemas y rendimiento con SqlPackage

En algunos escenarios, las operaciones de SqlPackage tardan más de lo esperado o no se completan. En este artículo se describen algunas tácticas sugeridas con frecuencia para solucionar problemas o mejorar el rendimiento de estas operaciones. Aunque se recomienda leer la página de documentación específica de cada acción para entender los parámetros y las propiedades disponibles, este artículo sirve como punto de partida para investigar las operaciones de SqlPackage.

Estrategia general

Como guía general, se puede obtener un mejor rendimiento a través de la versión de .NET de SqlPackage en lugar de la versión de .NET Framework instalada a través del DacFramework.msi.

Si no puedes instalar SqlPackage como herramienta de dotnet, que te permite ejecutar comandos de SqlPackage desde el símbolo del sistema en cualquier directorio:

  1. Descargue el archivo ZIP de SqlPackage en .NET 8 para el sistema operativo (Windows, macOS o Linux).
  2. Descomprime el archivo según las indicaciones indicadas en la página de descarga.
  3. Abra una terminal y cambie el directorio (cd) a la carpeta SqlPackage.

Utiliza la última versión disponible de SqlPackage, ya que se publican regularmente mejoras de rendimiento y correcciones de errores.

Sustitución de SqlPackage para el servicio Import/Export

Si ha intentado usar el servicio Import/Export para importar o exportar la base de datos, puede usar SqlPackage para realizar la misma operación con más control sobre parámetros y propiedades opcionales. La entrada de blog Optimización de importaciones BACPAC - SqlPackage Done Right! le guía por los pasos para usar SqlPackage en lugar del servicio Import/Export para una .bacpac importación.

Para la importación, un comando de ejemplo es:

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

Para la exportación, un comando de ejemplo es:

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

Utiliza la autenticación multifactor como alternativa al nombre de usuario y la contraseña, para autenticarte con la autenticación Microsoft Entra. Sustituya los parámetros de nombre de usuario y contraseña por /ua:true y /tid:"contoso.onmicrosoft.com".

Diagnostics

Los registros de diagnóstico y un paquete de diagnóstico admiten el diagnóstico de errores y un comportamiento inesperado en SqlPackage. Los registros de diagnóstico son esenciales para solucionar problemas y se capturan en un archivo con el parámetro /DiagnosticsFile:<filename>.

Controla el nivel de detalle en la salida de diagnóstico a través del /DiagnosticsLevel parámetro. Utiliza los Information valores y Verbose para obtener más detalles.

Registra los datos de traza relacionados con el rendimiento estableciendo la DACFX_PERF_TRACE=true variable de entorno antes de ejecutar SqlPackage. Los datos de traza aumentan la salida de log, así que solo indíctelos al diagnosticar problemas de rendimiento. Para establecer esta variable de entorno en PowerShell, use el siguiente comando:

Set-Item -Path Env:DACFX_PERF_TRACE -Value true

En SqlPackage 162.5 y posteriores, puedes generar un paquete de diagnóstico para ayudar con la resolución de problemas. El paquete de diagnóstico contiene la versión de SqlPackage, el comando ejecutado, información sobre los modelos de base de datos de origen y de destino y la salida del comando. Para generar un paquete de diagnóstico, use el parámetro /DiagnosticsPackageFile:<filename>.

Problemas comunes

Errores de tiempo de espera

Para problemas de tiempo de espera, utiliza las siguientes propiedades para ajustar la conexión entre SqlPackage y la instancia SQL:

  • /p:CommandTimeout=: Especifica el tiempo de espera del comando en segundos cuando se ejecuta una consulta. Valor predeterminado: 60
  • /p:DatabaseLockTimeout=: especifica el tiempo de expiración de bloqueo de la base de datos en segundos. Use -1 para esperar indefinidamente. Valor predeterminado: 60
  • /p:LongRunningCommandTimeout=: especifica el tiempo de expiración del comando de larga duración en segundos. El valor por defecto, 0, espera indefinidamente.

Consumo de recursos de cliente

Para los comandos de exportación y extracción, SqlPackage pasa los datos de la tabla a un directorio temporal para almacenarlos antes de escribirlos en el archivo BACPAC o DACPAC. Este requisito de almacenamiento puede ser grande y es relativo al tamaño total de los datos a exportar. Especifique un directorio temporal alternativo con la propiedad /p:TempDirectoryForTableData=<path>.

SqlPackage compila el modelo de esquema en memoria. Para esquemas de bases de datos grandes, el requerimiento de memoria en la máquina cliente que ejecuta SqlPackage puede ser significativo.

Consumo bajo de recursos del servidor

De forma predeterminada, SqlPackage establece el paralelismo máximo del servidor en 8. Si notas un bajo consumo de recursos del servidor, aumentar el valor del MaxParallelism parámetro puede mejorar el rendimiento.

Token de acceso

Usar el parámetro /AccessToken: o /at: permite la autenticación basada en tokens para SqlPackage, pero pasar el token al comando puede ser complicado. Si estás analizando un objeto de token de acceso en PowerShell, pasa explícitamente el valor de la cadena o envuelve la referencia a la propiedad del token en $(). Por ejemplo:

$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

Si SqlPackage no se puede conectar, es posible que el servidor no tenga habilitado el cifrado o que el certificado configurado no se emita desde una entidad de certificación de confianza (como un certificado autofirmado). Puede cambiar el comando SqlPackage para conectarse sin cifrado o para confiar en el certificado de servidor. El procedimiento recomendado consiste en asegurarse de que se puede establecer una conexión cifrada de confianza al servidor.

  • Conexión sin cifrado: /SourceEncryptConnection:False o /TargetEncryptConnection:False
  • Certificado de servidor de confianza: /SourceTrustServerCertificate:True o /TargetTrustServerCertificate:True

Podrías ver uno o más de los siguientes mensajes de advertencia al conectarte a una instancia SQL, lo que indica que los parámetros de la línea de comandos podrían requerir cambios para conectarse al servidor:

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.

Puede encontrar más información sobre los cambios de seguridad de conexión en SqlPackage en Mejoras de conexión de seguridad en SqlPackage 161.

Error en la acción de importación 2714 debido a la restricción

Cuando realizas una acción de importación, podrías recibir el error 2714 si un objeto ya existe:

*** 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];

Estas son las causas y soluciones para resolver este error:

  1. Comprueba que el destino en el que vas a importar es una base de datos vacía.
  2. Si tu base de datos tiene restricciones que usan el DEFAULT atributo (donde SQL Server asigna un nombre aleatorio a la restricción) y una restricción con nombre explícito, una restricción con el mismo nombre podría crearse dos veces. Utiliza todas las restricciones explícitamente nombradas (no uses DEFAULT), o utiliza todos los nombres definidos por el sistema (usa DEFAULT).
  3. Edita manualmente el model.xml archivo y renombra la restricción con el nombre que causa el error a un nombre único. Esta opción solo debe realizarse si lo indica el soporte técnico de Microsoft y supone un riesgo de daños en .bacpac.

Excepción de desbordamiento de pila

Los scripts T-SQL grandes con muchas sentencias anidadas pueden causar excepciones intermitentes o persistentes por desbordamiento de pila. Cuando ocurre esta condición, el mensaje de error incluye el texto Stack overflow y una traza de pila:

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 parámetro para SqlPackage está disponible en todos los comandos, /ThreadMaxStackSize:, que especifica el tamaño máximo de pila para el subproceso que ejecuta el proceso SqlPackage. El valor predeterminado viene determinado por la versión de .NET que ejecuta SqlPackage. Establecer un valor elevado puede afectar al rendimiento general de SqlPackage. Sin embargo, aumentar este valor podría resolver la excepción de desbordamiento de pila causada por sentencias anidadas. Refactoriza el código T-SQL para evitar excepciones de desbordamiento de pila siempre que sea posible. Si no puedes refactorizar, usa el /ThreadMaxStackSize: parámetro como solución alternativa.

Cuando uses el parámetro /ThreadMaxStackSize:, ajusta las operaciones repetidas al valor mínimo que resuelva la excepción de desbordamiento de pila si notas un impacto en el rendimiento. El valor del parámetro está en megabytes (MB). Por ejemplo, puedes probar valores como 10 y 100.

Sugerencias de acción de importación

Para importaciones que contienen tablas grandes o con muchos índices, usar /p:RebuildIndexesOfflineForDataPhase=True o /p:DisableIndexesForDataPhase=False puede mejorar el rendimiento. Estas propiedades modifican la operación de recompilación de índices para que se produzca sin conexión o no se produzca, respectivamente. Puedes usar estas propiedades y otras para ajustar la operación de importación de SqlPaket .

Los índices se desactivan tras una importación

Para cargar los datos de forma eficiente, una importación desactiva los índices no agrupados antes de la fase de datos y los reconstruye después (el comportamiento por defecto /p:DisableIndexesForDataPhase=True ). Si la importación se interrumpe o falla tras la carga de los datos pero antes de que termine la reconstrucción, uno o más índices no agrupados pueden permanecer deshabilitados. Un índice deshabilitado permanece en los metadatos, pero el optimizador de consultas lo ignora, lo que puede causar consultas lentas tras una importación que de otro modo parece tener éxito.

Para encontrar índices deshabilitados, consulte la columna is_disabled en la vista de catálogo sys.indexes:

SELECT OBJECT_SCHEMA_NAME(object_id) AS schema_name,
       OBJECT_NAME(object_id) AS table_name,
       name AS index_name
FROM sys.indexes
WHERE is_disabled = 1;

Para volver a activar un índice deshabilitado, reconstruyéndolo con ALTER INDEX. Usar ALTER INDEX ALL ... REBUILD para habilitar todos los índices deshabilitados en una tabla:

ALTER INDEX ALL ON <schema>.<table> REBUILD;

Para más información, consulte Habilitar índices y restricciones.

Sugerencias de acción de exportación

Para que una exportación sea transaccionalmente consistente, asegúrate de que no haya actividad de escritura durante la exportación, o que exportes desde una copia transaccionalmente consistente de tu base de datos. Si recibes errores sobre restricciones de clave extranjera durante una importación, la exportación podría no ser transaccionalmente consistente debido a registros insertados o actualizados durante el proceso de exportación.

Rendimiento durante la exportación

Una causa común de degradación del rendimiento durante la exportación son las referencias de objetos no resueltas. Este problema hace que SqlPackage intente resolver el objeto varias veces. Por ejemplo, se define una vista que hace referencia a una tabla pero la tabla ya no existe en la base de datos. Si las referencias sin resolver aparecen en el registro de exportación, considere la posibilidad de corregir el esquema de la base de datos para mejorar el rendimiento de la exportación.

Durante un proceso de exportación, los datos de la tabla se comprimen en el archivo bacpac. Configurar /p:CompressionOption a Fast, SuperFast, o NotCompressed podría mejorar la velocidad del proceso de exportación mientras se comprime menos el archivo bacpac de salida.

Para obtener el esquema y los datos de la base de datos mientras se omite la validación del esquema, realice una exportación con la propiedad /p:VerifyExtraction=False. Se puede producir una exportación no válida que no se pueda importar.

Espacio en disco durante la exportación

En escenarios donde el espacio en disco del sistema operativo es limitado y se agota durante la exportación, úsalo /p:TempDirectoryForTableData para almacenar en búfer los datos para exportar en un disco alternativo. El espacio necesario para esta acción puede ser grande y depende del tamaño completo de la base de datos. Puedes ajustar la operación de exportación de SqlPackage configurando esta y otras propiedades.

Azure SQL Database

Las siguientes sugerencias son específicas para ejecutar la importación o exportación en Azure SQL Database desde una máquina virtual (VM) de Azure:

  • Utilice la base de datos de nivel Crítico para el negocio o Premium para obtener el mejor rendimiento.
  • Use el almacenamiento SSD en la máquina virtual.
  • Asegúrese de que hay suficiente espacio para descomprimir el bacpac.
  • Ejecute SqlPackage desde una máquina virtual en la misma región que la base de datos.
  • Habilite redes aceleradas en la máquina virtual.

Para más información sobre el uso de un script PowerShell para recopilar detalles sobre una operación de importación, véase Lección Aprendida #211: Monitorización del proceso de importación de SQLPackage.

Más recursos

El blog de soporte técnico de Azure Database contiene muchos artículos sobre la solución de problemas y el ajuste del rendimiento de Azure SQL Database, incluidos varios artículos sobre SqlPackage.

Algunos de los artículos más relevantes incluyen:

Contenido relacionado

  • Last updated on