SqlPackage

  • Artículo

SqlPackage es una utilidad de la línea de comandos que automatiza las tareas de desarrollo de bases de datos exponiendo algunas de las API públicas del marco de trabajo de la aplicación de capa de datos (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 GitHub y Azure Pipelines u otras herramientas de CI/CD.

Descargar la última versión . 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 la 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 de SQL Server en el entorno local 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.

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

  • Import: importa el esquema y los datos de 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 la 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 la 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 los datos de usuario y del esquema 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 aplicará 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.

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

  • Publicar: actualiza de forma incremental un esquema de la base de datos para coincidir 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 creará. 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 que se han aplicado en una base de datos registrada desde que se registró por última vez.

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

Sintaxis de línea de comandos

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

SqlPackage {parameters} {properties} {SQLCMD variables}

En las páginas de acciones individuales y referencia de la CLI de SqlPackage se detalla más información sobre la sintaxis de línea de comandos de SqlPackage.

Comandos de utilidad

Versión

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

SqlPackage /Version

Ayuda

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

SqlPackage /?

Para obtener información acerca de propiedades y parámetros específicos de una acción determinada, use el parámetro de ayuda 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 lograr 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:

  • Los inicios de sesión de autenticación
  • Autenticación de Active Directory (Windows)
  • Autenticación de Microsoft Entra
    • Nombre de usuario y 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 el entorno de ejecución, ya que SqlPackage utiliza 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 se configura para el entorno donde se ejecuta la acción SqlPackage, esta acción puede usar esa identidad a fin de autenticarse en Azure SQL. Para más información sobre cómo configurar la 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 se admiten en canalizaciones de CI/CD de Azure DevOps y acciones de GitHub.

Entidad de servicio

Nota:

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

Las entidades de servicio del servicio de aplicación 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 aplicación 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 ser necesario recuperar el 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. El token de acceso se puede pasar a SqlPackage mediante el parámetro /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;"

Las entidades de servicio se admiten en canalizaciones de CI/CD de Azure DevOps y acciones de GitHub.

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 en 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 va a especificar /p:TempDirectoryForTableData para invalidar el valor predeterminado de SqlPackage.

La API de .NET GetTempPath se usa para determinar el valor predeterminado en 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 que especifica la variable de entorno TMP.
  2. Ruta de acceso que especifica la variable de entorno TEMP.
  3. Ruta de acceso que especifica la variable de entorno USERPROFILE.
  4. El directorio de Windows.

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

Usuarios de SqlPackage y de base de datos

Los usuarios de bases de datos independientes se incluyen en las operaciones de SqlPackage. Pero la parte de contraseña de la definición se establece en una cadena que genera aleatoriamente SqlPackage; el valor existente no se transfiere. Se recomienda restablecer la nueva contraseña del usuario a un valor seguro después de la importación de .bacpac o la implementación de .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 posterior a SqlPackage.

Recopilación de datos de uso

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

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

SqlPackage no recopila información personal o específica del usuario. Como ayuda para aproximarse a un único usuario con fines de diagnóstico, SqlPackage genera un identificador único 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 datos y los informes de telemetría, actualice la variable de entorno DACFX_TELEMETRY_OPTOUT a true o 1.

Soporte técnico

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

Obtén ayuda con SqlPackage, envía solicitudes de características y notifica problemas en el repositorio DacFx de GitHub.

Ofertas de SQL admitidas

SqlPackage y DacFx admiten todas las versiones de SQL admitidas en el momento de publicación de SqlPackage/DacFx. Por ejemplo, una versión de SqlPackage del 14 de enero de 2022 es compatible con todas las versiones de SQL admitidas el 14 de enero de 2022. Para obtener más información sobre las directivas de compatibilidad de SQL, vea la directiva de compatibilidad de SQL.

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

Pasos siguientes