Compartir a través de

SqlPackage

SqlPackage es una utilidad de línea de comandos que automatiza las tareas de desarrollo de bases de datos mediante la exposición de algunas de las API públicas Data-Tier Application Framework (DacFx). Los casos de uso principales de SqlPackage se centran en la portabilidad y las implementaciones de bases de datos para la familia de bases de datos de SQL Server, Azure SQL y Azure Synapse Analytics. SqlPackage se puede automatizar mediante acciones de Azure Pipelines y GitHub u otras herramientas de CI/CD.

Descargue la versión más reciente. Para más información sobre la última versión, consulte las notas de la versión.

Nota:

Aunque Microsoft Entra ID es el nuevo nombre de Azure Active Directory (Azure AD), para evitar interrumpir los entornos existentes, Azure AD sigue estando en algunos elementos codificados de forma rígida como campos de interfaz de usuario, proveedores de conexiones, códigos de error y cmdlets. En este artículo, los dos nombres son intercambiables.

Portabilidad

La portabilidad de la base de datos es la capacidad de mover un esquema de base de datos y datos entre distintas instancias de SQL Server, Azure SQL y Azure Synapse Analytics. La exportación de una base de datos de Azure SQL Database a una instancia local de SQL Server o de SQL Server a Azure SQL Database son ejemplos de portabilidad de base de datos. SqlPackage admite la portabilidad de la base de datos a través de las acciones Exportar e Importar , que crean y consumen archivos BACPAC. SqlPackage también admite la portabilidad de la base de datos mediante las acciones Extraer y publicar , que crean y consumen archivos DACPAC, que pueden contener los datos directamente o los datos de referencia almacenados en Azure Blob Storage.

  • Exportar: exporta una base de datos SQL conectada ( incluidos el esquema de base de datos y los datos de usuario) a un archivo BACPAC (.bacpac).

  • Importar: importa los datos de esquema y tabla de un archivo BACPAC en una nueva base de datos de usuario.

Implementaciones

Las implementaciones de base de datos son el proceso de actualizar un esquema de base de datos para que coincida con un estado deseado, como agregar columnas a una tabla o cambiar el contenido de un procedimiento almacenado. SqlPackage admite implementaciones de base de datos a través de las acciones Publicar y Extraer . La acción Publicar actualiza un esquema de base de datos para que coincida con el contenido de un archivo .dacpac de origen, mientras que la acción Extraer crea un archivo de aplicación de capa de datos (.dacpac) que contiene el esquema o esquema y los datos de usuario de una base de datos SQL conectada. SqlPackage permite implementaciones en bases de datos nuevas o existentes desde el mismo artefacto (.dacpac) mediante la creación automática de un plan de implementación que aplique los cambios necesarios a la base de datos de destino. El plan de implementación se puede revisar antes de aplicar los cambios a la base de datos de destino con las acciones Script o DeployReport .

  • Extraer: crea un archivo de aplicación de capa de datos (.dacpac) que contiene el esquema o esquema y los datos de usuario de una base de datos SQL conectada.

  • Publicar: actualiza incrementalmente un esquema de base de datos para que coincida con el esquema de un archivo .dacpac de origen. Si la base de datos no existe en el servidor, la operación de publicación la crea. De lo contrario, se actualiza una base de datos existente.

  • DeployReport: crea un informe XML que representa los cambios que realizaría una acción de publicación.

  • DriftReport: crea un informe XML que representa los cambios aplicados a una base de datos registrada desde que se registró por última vez.

  • script: crea un script de actualización incremental Transact-SQL que actualiza el esquema de un destino para que coincida con el esquema de un origen.

Sintaxis de Command-Line

SqlPackage inicia las acciones especificadas mediante los parámetros, las propiedades y las variables SQLCMD especificadas en la línea de comandos.

SqlPackage {parameters} {properties} {SQLCMD variables}

Más información sobre la sintaxis de la línea de comandos de SqlPackage se detalla en la referencia del CLI de SqlPackage y en las páginas dedicadas a acciones específicas.

Comandos de utilidad

Versión

Muestra la versión de sqlpackage como un número de compilación. Se puede usar en mensajes interactivos y en canalizaciones automatizadas.

SqlPackage /Version

Ayuda

Puede mostrar información de uso de SqlPackage mediante /? o /help:True.

SqlPackage /?

Para obtener información de parámetros y propiedades específica de una acción determinada, use el parámetro help además del parámetro de esa acción.

SqlPackage /Action:Publish /?

Autenticación

SqlPackage se autentica mediante métodos disponibles en SqlClient. La configuración del tipo de autenticación se puede realizar a través de los parámetros de cadena de conexión para cada acción sqlPackage (/SourceConnectionString y /TargetConnectionString) o a través de parámetros individuales para las propiedades de conexión. Los métodos de autenticación siguientes se admiten en una cadena de conexión:

  • Autenticación de SQL Server
  • Autenticación de Active Directory (Windows)
  • Autenticación de Microsoft Entra
    • Nombre de usuario/contraseña
    • Autenticación integrada
    • Autenticación universal
    • Identidad administrada
    • Entidad de servicio

Identidad administrada

Nota:

Microsoft Entra ID era conocido anteriormente como Azure Active Directory (Azure AD).

En entornos automatizados, la identidad administrada de Microsoft Entra es el método de autenticación recomendado. Este método no requiere pasar credenciales a SqlPackage en tiempo de ejecución, ya que SqlPackage usa identidades administradas para conectarse a bases de datos que admiten la autenticación de Microsoft Entra y para obtener tokens de Microsoft Entra, sin administración de credenciales. Cuando la identidad administrada está configurada para el entorno donde se ejecuta la acción SqlPackage, la acción SqlPackage puede usar esa identidad para autenticarse en Azure SQL. Para obtener más información sobre cómo configurar una identidad administrada para su entorno, consulte la documentación de identidad administrada.

Una cadena de conexión de ejemplo mediante la identidad administrada asignada por el sistema es:

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

Las identidades administradas son compatibles con las canalizaciones de CI/CD de acciones de GitHub y Azure DevOps.

Entidad de servicio

Nota:

Microsoft Entra ID era conocido anteriormente como Azure Active Directory (Azure AD).

Las entidades de servicio de aplicaciones de Microsoft Entra son objetos de seguridad dentro de una aplicación de Microsoft Entra que definen lo que una aplicación puede hacer en un inquilino determinado. Se configuran en Azure Portal durante el proceso de registro de aplicaciones y se configuran para acceder a los recursos de Azure, como Azure SQL. Para obtener más información sobre cómo configurar una entidad de servicio para su entorno, consulte la documentación de la entidad de servicio.

Al usar SqlPackage con una entidad de servicio, puede recuperar un token de acceso y pasarlo a SqlPackage. El token de acceso se puede recuperar mediante el módulo de Azure PowerShell o la CLI de Azure. En este proceso, el sistema de invocación mantiene el control sobre la actualización o invalidación del token. El token de acceso se puede pasar a SqlPackage mediante el /at parámetro .

# 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;"

Como alternativa, puede pasar el identificador de cliente de la entidad de servicio y el secreto a SqlPackage en la cadena de conexión. El formato de cadena de conexión incluye Authentication=Active Directory Service Principal; y .User Id=AppId; Password=<password> Cuando se pasan las credenciales de la entidad de servicio en la cadena de conexión, el parámetro /at no es necesario y SqlPackage actualiza la autenticación según sea necesario durante la operación.

Las entidades de servicio son compatibles con las canalizaciones de CI/CD de acciones de GitHub y Azure DevOps.

Variables de entorno

Agrupación de conexiones

La agrupación de conexiones se puede habilitar para todas las conexiones realizadas por SqlPackage estableciendo la variable de entorno CONNECTION_POOLING_ENABLED a True. Esta configuración se recomienda para las operaciones con conexiones de nombre de usuario y contraseña de Microsoft Entra para evitar la limitación por parte de la Biblioteca de autenticación de Microsoft (MSAL).

Archivos temporales

Durante las operaciones de SqlPackage, los datos de la tabla se escriben en archivos temporales antes de la compresión o después de la descompresión. En el caso de las bases de datos grandes, estos archivos temporales pueden ocupar una cantidad significativa de espacio en disco, pero se puede especificar su ubicación. Las operaciones de exportación y extracción incluyen una propiedad opcional que se debe especificar /p:TempDirectoryForTableData para invalidar el valor predeterminado de SqlPackage.

La API de .NET GetTempPath se usa para determinar el valor predeterminado dentro de SqlPackage.

Para Windows, se comprueban las siguientes variables de entorno en el orden siguiente y se usa la primera ruta de acceso que existe:

  1. Ruta de acceso especificada por la variable de entorno TMP.
  2. Ruta de acceso especificada por la variable de entorno TEMP.
  3. Ruta de acceso especificada por la variable de entorno USERPROFILE.
  4. Directorio de Windows.

Para Linux y macOS, si la ruta de acceso no se especifica en la TMPDIR variable de entorno, se usa la ruta de acceso /tmp/ predeterminada.

SqlPackage y usuarios de base de datos

Los usuarios de bases de datos contenidas se incluyen en las operaciones de SqlPackage. Sin embargo, la parte de contraseña de la definición se establece en una cadena generada aleatoriamente por SqlPackage, el valor existente no se transfiere. Se recomienda restablecer la contraseña del nuevo usuario a un valor seguro después de la importación de un .bacpac o la implementación de un .dacpac. En un entorno automatizado, los valores de contraseña se pueden recuperar de un almacén de claves seguro, como Azure Key Vault, en un paso siguiente a SqlPackage.

Extensibilidad

SqlPackage admite la extensibilidad a través de Managed Extensibility Framework (MEF), lo que permite escenarios avanzados a través de componentes personalizados denominados colaboradores. Estas extensiones pueden personalizar cómo SqlPackage publica archivos .dacpac, lo que permite a los equipos aplicar estándares o automatizar la lógica específica del proyecto. Los colaboradores de implementación se ejecutan como parte del proceso de publicación, después de generar el plan de implementación, pero antes de que se ejecute. Estos colaboradores pueden acceder y modificar el plan de implementación mediante un objeto de clase DeploymentPlanModifier para agregar, quitar o reordenar pasos. Para empezar a trabajar con la extensibilidad de la implementación, consulte Uso de colaboradores de implementación para personalizar la compilación e implementación de la base de datos.

SqlPackage detecta y carga ensamblados de colaborador mediante el examen de bibliotecas de vínculos dinámicos (archivos .dll) en el mismo directorio que el ejecutable SqlPackage, así como las ubicaciones especificadas a través de la propiedad opcional de línea de comandos /p:AdditionalDeploymentContributorPaths. Aunque esto permite una personalización flexible, también presenta consideraciones de seguridad importantes.

Importante

Dado que SqlPackage usa MEF para cargar dinámicamente bibliotecas de vínculos dinámicos (archivos .dll) en tiempo de ejecución, los ensamblados colocados junto con el ejecutable SqlPackage se pueden ejecutar como parte del proceso de implementación. Un actor malintencionado podría aprovechar este comportamiento introduciendo extensiones manipuladas o no autorizadas que ejecutan código arbitrario.

Es su responsabilidad asegurarse de que los archivos de extensión compilados usados con SqlPackage sean seguros y procedan de orígenes de confianza. Se recomienda controlar el acceso a la carpeta SqlPackage y validar la integridad de todos los componentes personalizados o de terceros.

Recopilación de datos de uso

SqlPackage contiene características habilitadas para Internet que pueden recopilar y enviar datos de diagnóstico y uso de características anónimos a Microsoft.

SqlPackage puede recopilar información estándar sobre el equipo, el uso y el rendimiento que se pueden transmitir a Microsoft y analizar para mejorar la calidad, la seguridad y la confiabilidad de SqlPackage.

SqlPackage no recopila información personal o específica del usuario. Para ayudar a aproximarse a un único usuario con fines de diagnóstico, SqlPackage genera un GUID aleatorio para cada equipo en el que se ejecuta y usa ese valor para todos los eventos que envía.

Para más información, consulte Declaración de privacidad de Microsoft y Complemento de privacidad de SQL Server.

Deshabilitación de los informes de telemetría

Para deshabilitar la recopilación de telemetría y los informes, actualice la variable DACFX_TELEMETRY_OPTOUT de entorno a true o 1.

Apoyo

La biblioteca DacFx y la herramienta de la CLI de SqlPackage siguen la directiva de ciclo de vida moderno de Microsoft. Todas las actualizaciones de seguridad, las correcciones y las nuevas características solo se publican en la versión más reciente de la versión principal. Mantener las instalaciones de DacFx o SqlPackage en la versión actual le ayuda a garantizar que recibe todas las correcciones de errores aplicables de forma oportuna.

Obtenga ayuda con SqlPackage, envíe solicitudes de características e informe de problemas en el repositorio de GitHub de DacFx.

Ofertas de SQL compatibles

SqlPackage y DacFx admiten todas las versiones sql admitidas en el momento de la versión de SqlPackage/DacFx. Por ejemplo, una versión de SqlPackage el 14 de enero de 2022 admite todas las versiones compatibles de SQL el 14 de enero de 2022. Para más información sobre las directivas de soporte técnico de SQL, consulte la directiva de soporte técnico de SQL.

Además de SQL Server, SqlPackage y DacFx admite Azure SQL Managed Instance, Azure SQL Database, Azure Synapse Analytics y Fabric Data Warehouse.

Pasos siguientes

  • Last updated on