Membuat, membangun, dan memvalidasi Proyek SQL Database

Sebelum Anda dapat mengotomatiskan penyebaran, menjalankan pengujian, atau mendeteksi penyimpangan skema, Anda perlu sesuatu yang benar-benar dapat dibangun oleh pipeline. Sesuatu itu adalah proyek database SQL.

Memahami proyek database SQL

Pikirkan proyek database SQL sebagai database Anda dalam bentuk file. Setiap tabel, prosedur tersimpan, tampilan, dan fungsi berada dalam filenya sendiri .sql . Anda mendeklarasikan setiap objek sekali, dan saat Anda perlu menambahkan kolom atau mengubah jenis data, Anda mengedit satu file tersebut.

Jika Anda bekerja dengan skrip migrasi sebelumnya, perbedaannya signifikan. Skrip migrasi berurutan. Anda menulis ALTER pernyataan, berharap itu berjalan dalam urutan yang tepat, dan mengakumulasi rantai perubahan yang berkembang dari waktu ke waktu. Proyek database SQL mengambil pendekatan yang berlawanan: Anda mempertahankan status akhir yang diinginkan dari setiap objek, dan alat menghitung perbedaan antara proyek dan database target pada waktu penyebaran.

Saat Anda membangun proyek, outputnya adalah .dacpac file, model yang dikompilasi dari seluruh skema database Anda. Anda menerbitkannya .dacpac untuk membuat database baru atau memperbarui database yang sudah ada. Proses build memberikan Anda dua hal yang penting untuk CI/CD:

• Validasi: referensi objek dan sintaks T-SQL diperiksa terhadap versi SQL tertentu sebelum apa pun disebarkan.
• Artefak yang dapat disebarkan: .dacpac menjadi paket tunggal yang mengalir melalui pipeline Anda ke setiap lingkungan.

Pilih antara proyek asli dan gaya SDK

Proyek database SQL hadir dalam dua format. Format asli dibangun di MSBuild (.NET Framework) dan dikirim dengan SQL Server Data Tools (SSDT) di Visual Studio. Format SDK-style berdasarkan Microsoft.Build.Sql proyek SDK dan merupakan format yang digunakan oleh ekstensi Proyek SQL Database untuk Visual Studio Code.

Untuk proyek baru, pilih gaya SDK. Ini membawa kemampuan yang tidak memiliki format asli:

• Dukungan .NET 8+, sehingga Anda dapat membangun lintas platform di Windows, Linux, dan macOS. Dukungan ini penting ketika runner CI Anda bukan mesin Windows.
• Referensi paket NuGet untuk referensi database, sehingga manajemen dependensi mengikuti pola yang sama dengan ekosistem .NET lainnya.
• Globbing default untuk .sql file. Letakkan file di folder proyek dan secara otomatis disertakan dalam build. Tidak diperlukan entri file manual.

Jika Anda memiliki proyek asli yang sudah ada, Anda dapat mengonversinya ke gaya SDK dengan memodifikasi .sqlproj file. Sebelum Anda mengonversi proyek, buat cadangan file proyek dan arsipkan .dacpac dari proyek saat ini. Bandingkan .dacpac "sebelum" dan "sesudah" untuk memastikan bahwa semua elemen berhasil dipertahankan dalam konversi.

Membuat dan mengisi proyek

Anda dapat membuat proyek database SQL dari Visual Studio Code, Visual Studio, atau baris perintah. Baris perintah sangat berguna untuk skenario CI/CD di mana tidak ada lingkungan grafis yang tersedia.

Untuk membuat proyek gaya SDK baru:

dotnet new sqlproj -n MyDatabaseProject

📝 Ini menghasilkan .sqlproj file dengan format gaya SDK. Dari sini, Anda menambahkan objek database dengan menjatuhkan .sql file ke folder proyek. Pola pencocokan default mendeteksinya secara otomatis.

Misalnya, untuk menentukan tabel, buat 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
);

Dimulai dengan database yang sudah ada? Alat perbandingan skema memungkinkan Anda membandingkan database langsung dengan proyek kosong dan mengimpor perbedaannya, sehingga Anda tidak perlu membuat ulang setiap objek dengan tangan.

Membangun dan memvalidasi proyek

Bangunan adalah tempat jaring pengaman mulai berfungsi. Proses build memvalidasi setiap referensi objek dan memeriksa sintaks T-SQL terhadap platform target. Jika tampilan mereferensikan kolom yang tidak ada, build gagal. Jika Anda menggunakan fungsi vektor yang ditambahkan di SQL Server 2025 tetapi proyek Anda menargetkan SQL Server 2017 (Sql140), sistem pengembangan akan mendeteksinya.

Untuk membangun dari baris perintah:

dotnet build MyDatabaseProject.sqlproj

📝 Build menghasilkan .dacpac file di bin/Debug folder secara default.

Output build mencakup kesalahan (yang menghentikan proses build) dan peringatan (seperti ketidakkonsistenan penulisan huruf besar-kecil dalam nama objek). Peringatan tidak menghentikan membangun, namun tetap perlu diperhatikan. Anda juga dapat mengaktifkan aturan analisis kode SQL untuk mendeteksi pelanggaran praktik terbaik selama proses build, mengidentifikasi masalah seperti sintaks join yang telah ditinggalkan, SELECT * dalam tampilan, atau kolom yang tidak diindeks dalam IN predicate.

Platform target diatur dalam .sqlproj file dan kontrol fitur T-SQL mana yang lulus validasi. Atur agar sesuai dengan target penyebaran Anda, apakah itu SQL Server 2025 atau Azure SQL Database.

Meluncurkan proyek

Setelah Anda memiliki .dacpac, SqlPackage akan mengelola proses penyebaran. Pasang sebagai alat global .NET:

dotnet tool install --global microsoft.sqlpackage

Kemudian terbitkan ke database target:

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

📝 SqlPackage adalah lintas platform dan berjalan di Windows, Linux, dan macOS.

Apa yang terjadi selama penyebaran tergantung pada target. Untuk database baru, SqlPackage menavigasi grafik dependensi objek dan membuat setiap objek dalam urutan yang benar, seperti tabel yang direferensikan sebelum kunci asing. Untuk database yang ada, sistem menghitung selisih antara .dacpac dan skema saat ini, lalu hanya menghasilkan pernyataan yang ALTER dibutuhkan untuk menutup kesenjangan. Apakah ada dua kolom yang hilang? Anda mendapatkan satu ALTER TABLE beserta kedua tambahan tersebut. Prosesnya idempotensi. Terapkan hal yang sama .dacpac lima kali dan pada eksekusi kelima tidak ada yang berubah. Anda juga dapat menyebarkan satu .dacpac ke seluruh sekumpulan database saat melakukan peningkatan beberapa tenant.

Sebelum menyebarkan secara langsung, Anda dapat mempratinjau perubahan yang direncanakan:

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

Tindakan ini Script menghasilkan T-SQL tepat yang dapat dijalankan. Tindakan DeployReport menghasilkan ringkasan XML dari setiap CREATE, ALTER, dan DROP. Tinjau salah satu sebelum mendorong perubahan ke produksi.

Poin-poin Penting

Proyek database SQL menyimpan setiap objek database sebagai file deklaratif .sql , dan build mengkompilasinya menjadi satu .dacpac artefak. Proyek gaya SDK (Microsoft.Build.Sql) mendukung .NET 8+, kompilasi lintas platform, referensi paket NuGet, dan globbing bawaan untuk file .sql. Proses build memvalidasi referensi objek dan sintaks T-SQL terhadap platform target sebelum apa pun mencapai database. SqlPackage menghitung perbedaan antara database sumber .dacpac dan database target, hanya menghasilkan perintah SQL yang diperlukan untuk menutup kesenjangan. Gunakan tindakan Script dan DeployReport untuk mempratinjau perubahan yang direncanakan sebelum mengimplementasikan ke produksi. Proyek database SQL, artefaknya .dacpac , dan SqlPackage membentuk fondasi untuk segala sesuatu di depan, termasuk kontrol sumber, alur CI/CD, deteksi penyimpangan skema, dan pengujian.