Creación, compilación y validación de proyectos de SQL Database

Completados

Para poder automatizar implementaciones, ejecutar pruebas o detectar desfases de esquema, necesita algo que una canalización pueda compilar realmente. Esto es un proyecto de base de datos SQL.

Descripción de los proyectos de base de datos SQL

Piense en un proyecto de base de datos SQL como base de datos en formato de archivo. Cada tabla, procedimiento almacenado, vista y función reside en su propio .sql archivo. Declara cada objeto una vez y, cuando necesite agregar una columna o cambiar un tipo de datos, edite ese único archivo.

Si ha trabajado con scripts de migración antes, la diferencia es significativa. Los scripts de migración son secuenciales. Escribes una ALTER instrucción, esperas que se ejecute en el orden correcto y acumulas una secuencia creciente de cambios con el tiempo. Un proyecto de base de datos SQL adopta el enfoque opuesto: mantiene el estado final deseado de cada objeto y las herramientas calculan la diferencia entre el proyecto y la base de datos de destino en el momento de la implementación.

Al compilar el proyecto, la salida es un .dacpac archivo, un modelo compilado de todo el esquema de la base de datos. Debe publicar ese .dacpac debe crear una nueva base de datos o actualizar una existente. El proceso de compilación proporciona dos cosas importantes para CI/CD:

  • Validación: las referencias de objeto y la sintaxis de T-SQL se comprueban con una versión específica de SQL antes de que se implemente nada.
  • Un artefacto que se puede implementar: .dacpac se convierte en el único paquete que fluye a través de la canalización a todos los entornos.

Elección entre proyectos originales y de estilo SDK

Los proyectos de base de datos SQL tienen dos formatos. El formato original se basa en MSBuild (.NET Framework) y se incluye con SQL Server Data Tools (SSDT) en Visual Studio. El formato de estilo SDK está basado en el SDK del proyecto Microsoft.Build.Sql y es el formato utilizado por la extensión "SQL Database Projects" para Visual Studio Code.

Para nuevos proyectos, use el estilo SDK. Aporta funcionalidades que el formato original no tiene:

  • Compatibilidad con .NET 8+, por lo que puede compilar plataformas multiplataforma en Windows, Linux y macOS. Esta compatibilidad es importante cuando los ejecutores de CI no son máquinas Windows.
  • Las referencias de paquetes NuGet para las referencias de base de datos, por lo que la administración de dependencias sigue los mismos patrones que el resto del ecosistema de .NET.
  • Comodines predeterminados para archivos .sql. Coloque un archivo en la carpeta del proyecto y se incluye automáticamente en la compilación. No se necesitan entradas de archivo manuales.

Si tiene un proyecto original existente, puede convertirlo en estilo SDK modificando el .sqlproj archivo. Antes de convertir el proyecto, realice una copia de seguridad del archivo del proyecto y archive un .dacpac elemento del proyecto actual. Compare un "antes" y "después" .dacpac para confirmar que la conversión ha conservado todo.

Nota:

Los proyectos sql de estilo SDK están disponibles con carácter general en Visual Studio Code y en versión preliminar en Visual Studio 2022. Visual Studio 2026 solo admite el formato del proyecto SQL original.

Crear y rellenar un proyecto

Puede crear un proyecto de base de datos SQL desde Visual Studio Code, Visual Studio o la línea de comandos. La línea de comandos es especialmente útil para escenarios de CI/CD en los que no hay ningún entorno gráfico disponible.

Para crear un nuevo proyecto de estilo SDK:

dotnet new sqlproj -n MyDatabaseProject

📝 Esto genera un .sqlproj archivo con el formato de estilo SDK. Desde aquí, puede añadir objetos de base de datos arrastrando archivos .sql a la carpeta del proyecto. El patrón de comodines predeterminado los selecciona automáticamente.

Por ejemplo, para definir una tabla, cree Tables/Customers.sql:

CREATE TABLE [dbo].[Customers]
(
    [CustomerID] INT NOT NULL PRIMARY KEY,
    [FirstName] NVARCHAR(50) NOT NULL,
    [LastName] NVARCHAR(50) NOT NULL,
    [Email] NVARCHAR(100) NULL
);

¿A partir de una base de datos existente? Las herramientas de comparación de esquemas permiten comparar una base de datos activa con un proyecto vacío e importar las diferencias, por lo que no es necesario volver a crear todos los objetos a mano.

Compilación y validación del proyecto

La construcción es el momento en que la red de seguridad empieza a hacer efecto. El proceso de compilación valida todas las referencias de objetos y comprueba la sintaxis de T-SQL en la plataforma de destino. Si una vista hace referencia a una columna que no existe, se produce un error en la compilación. Si usa una función vectorial agregada en SQL Server 2025, pero el proyecto tiene como destino SQL Server 2017 (Sql140), la compilación la captura.

Para compilar desde la línea de comandos:

dotnet build MyDatabaseProject.sqlproj

📝 La compilación genera un .dacpac archivo en la bin/Debug carpeta de forma predeterminada.

La salida de compilación incluye errores (que bloquean la compilación) y advertencias (como el uso incoherente de mayúsculas y minúsculas en los nombres de objeto). Las advertencias no detienen la compilación, pero es importante prestarles atención. También puede habilitar reglas de análisis de código SQL para marcar infracciones de procedimientos recomendados durante la compilación, señalando problemas como una sintaxis de unión en desuso, SELECT * en vistas, o columnas sin indexar en predicados IN.

La plataforma de destino se establece en el .sqlproj archivo y controla qué características de T-SQL pasan la validación. Establézcalo para que coincida con el destino de implementación, ya sea SQL Server 2025 o Azure SQL Database.

Implementación del proyecto

Una vez que tenga un .dacpac, SqlPackage controla la implementación. Instálelo como una herramienta global de .NET:

dotnet tool install --global microsoft.sqlpackage

A continuación, publique en una base de datos de destino:

sqlpackage /Action:Publish /SourceFile:bin/Debug/MyDatabaseProject.dacpac /TargetConnectionString:"Server=myserver.database.windows.net;Database=mydb;Authentication=Active Directory Default"

📝 SqlPackage es multiplataforma y se ejecuta en Windows, Linux y macOS.

Lo que sucede durante la implementación depende del destino. Para una nueva base de datos, SqlPackage navega por el gráfico de dependencias de objetos y crea cada objeto en el orden correcto, como las tablas a las que se hace referencia antes de las claves externas. Para una base de datos existente, calcula la diferencia entre y .dacpac el esquema activo y, a continuación, genera solo las ALTER instrucciones necesarias para cerrar la brecha. ¿Faltan dos columnas? Se obtiene una ALTER TABLE con ambas adiciones. El proceso es idempotente. Implemente las mismas .dacpac cinco veces y la quinta ejecución no cambia nada. También puede efectuar una distribución ramificada de un .dacpac en un conjunto de bases de datos al actualizar varios inquilinos.

Antes de implementar directamente, puede obtener una vista previa de los cambios planeados:

sqlpackage /Action:Script /SourceFile:bin/Debug/MyDatabaseProject.dacpac /TargetConnectionString:"..." /OutputPath:deploy-script.sql
sqlpackage /Action:DeployReport /SourceFile:bin/Debug/MyDatabaseProject.dacpac /TargetConnectionString:"..." /OutputPath:report.xml

La Script acción genera el T-SQL exacto que se ejecutaría. La DeployReport acción genera un resumen XML de cada CREATE, ALTERy DROP. Revisa cualquiera antes de implementar cambios en producción.

Conclusiones clave

Un proyecto de base de datos SQL almacena todos los objetos de base de datos como un archivo declarativo .sql y la compilación los compila en un único .dacpac artefacto. Los proyectos de estilo SDK (Microsoft.Build.Sql) admiten .NET 8+, compilaciones multiplataforma, referencias de paquetes NuGet y comodines predeterminados para archivos .sql. El proceso de compilación valida las referencias de objeto y la sintaxis de T-SQL en la plataforma de destino antes de que todo llegue a una base de datos. SqlPackage calcula la diferencia entre .dacpac y la base de datos de destino, generando solo las instrucciones necesarias para cerrar la brecha. Utilice las acciones Script y DeployReport para previsualizar los cambios planeados antes de implementar en producción. El proyecto de base de datos SQL, su .dacpac artefacto y SqlPackage forman la base de todo lo que sigue, incluidos el control de código fuente, las canalizaciones de CI/CD, la detección de desviación del esquema y las pruebas.