SqlPackage

  • Artículo

SqlPackage es una utilidad de línea de comandos que automatiza las siguientes tareas de desarrollo de bases de datos exponiendo algunas de las API públicas Data-Tier Application Framework (DacFx):

  • Versión: devuelve el número de compilación de la aplicación SqlPackage.

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

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

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

La herramienta de línea de comandos SqlPackage permite especificar estas acciones junto con parámetros y propiedades específicos de cada acción.

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.

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}

Códigos de salida

Los comandos de SqlPackage devuelven los siguientes códigos de salida:

  • 0 = success
  • distinto de cero = error

Ejemplo de uso

Hay más ejemplos disponibles en las páginas de acciones individuales.

Crear un archivo .dacpac del esquema de base de datos actual:

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

Parámetros

Algunos parámetros se comparten entre las acciones de SqlPackage. A continuación se muestra una tabla que resume los parámetros. Para más información, haz clic en las páginas de acción específicas.

Parámetro Forma corta Extracción Publicar Exportar Importar 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

Propiedades

Las acciones sqlPackage admiten un gran número de propiedades para modificar el comportamiento predeterminado de una acción. Para más información haga clic en las páginas de acción específicas.

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 runtime. 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;

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.

Pasos siguientes