Bagikan melalui

SqlPackage

SqlPackage adalah utilitas baris perintah yang mengotomatiskan tugas pengembangan database dengan mengekspos beberapa API Application Framework (DacFx) Data-Tier publik. Kasus penggunaan utama untuk SqlPackage berfokus pada portabilitas dan penyebaran database untuk keluarga database SQL Server, Azure SQL, dan Azure Synapse Analytics. SqlPackage dapat diotomatisasi menggunakan Azure Pipelines dan tindakan GitHub atau alat CI/CD lainnya.

Unduh versi terbaru. Untuk detail tentang rilis terbaru, lihat catatan rilis.

Nota

Meskipun MICROSOFT Entra ID adalah nama baru untuk Azure Active Directory (Azure AD), untuk mencegah mengganggu lingkungan yang ada, Azure AD masih tetap berada di beberapa elemen yang dikodekan secara permanen seperti bidang UI, penyedia koneksi, kode kesalahan, dan cmdlet. Dalam artikel ini, dua nama tersebut dapat dipertukarkan.

Portabilitas

Portabilitas database adalah kemampuan untuk memindahkan skema database dan data antara instans SQL Server, Azure SQL, dan Azure Synapse Analytics yang berbeda. Mengekspor database dari Azure SQL Database ke instans SQL Server lokal, atau dari SQL Server ke Azure SQL Database, adalah contoh portabilitas database. SqlPackage mendukung portabilitas database melalui tindakan Ekspor dan Impor , yang membuat dan menggunakan file BACPAC. SqlPackage juga mendukung portabilitas database melalui tindakan Ekstrak dan Terbitkan , yang membuat dan menggunakan file DACPAC, yang dapat berisi data secara langsung atau mereferensikan data yang disimpan di Azure Blob Storage.

  • Ekspor: Mengekspor database SQL yang terhubung - termasuk skema database dan data pengguna - ke file BACPAC (.bacpac).

  • Impor: Mengimpor data skema dan tabel dari file BACPAC ke database pengguna baru.

Penyebaran

Penyebaran database adalah proses memperbarui skema database agar sesuai dengan status yang diinginkan, seperti menambahkan kolom ke tabel atau mengubah konten prosedur tersimpan. SqlPackage mendukung penyebaran database melalui tindakan Terbitkan dan Ekstrak . Aksi Publikasi memperbarui skema basis data agar sesuai dengan konten file .dacpac sumber, sementara Aksi Ekstrak membuat file aplikasi tingkatan data (.dacpac) yang berisi skema atau skema dan data pengguna dari basis data SQL yang terhubung. SqlPackage memungkinkan penyebaran terhadap database baru atau yang sudah ada dari artefak yang sama (.dacpac) dengan secara otomatis membuat rencana penyebaran yang menerapkan perubahan yang diperlukan pada database target. Rencana penyebaran dapat ditinjau sebelum menerapkan perubahan ke database target dengan tindakan Skrip atau DeployReport .

  • Ekstrak: Membuat file aplikasi lapisan data (.dacpac) yang berisi skema atau skema dan data pengguna dari database SQL yang tersambung.

  • Terbitkan: Memperbarui skema database secara bertahap agar sesuai dengan skema file .dacpac sumber. Jika database tidak ada di server, operasi penerbitan membuatnya. Jika tidak, database yang ada diperbarui.

  • DeployReport: Membuat laporan XML yang mewakili perubahan yang akan dilakukan tindakan penerbitan.

  • DriftReport: Membuat laporan XML yang mewakili perubahan yang diterapkan pada database terdaftar sejak terakhir didaftarkan.

  • Skrip: Membuat skrip pembaruan Transact-SQL inkremental yang memperbarui skema target agar sesuai dengan skema sumber.

Sintaks Command Line

SqlPackage memulai tindakan yang ditentukan menggunakan parameter, properti, dan variabel SQLCMD yang ditentukan pada baris perintah.

SqlPackage {parameters} {properties} {SQLCMD variables}

Informasi selengkapnya tentang sintaks baris perintah SqlPackage dirinci dalam referensi SqlPackage CLI dan halaman tindakan individual.

Perintah utilitas

Versi

Menampilkan versi dari sqlpackage sebagai nomor build. Dapat digunakan dalam perintah interaktif dan dalam alur otomatis .

SqlPackage /Version

Bantuan

Anda dapat menampilkan informasi penggunaan SqlPackage dengan menggunakan /? atau /help:True.

SqlPackage /?

Untuk parameter dan informasi properti khusus untuk tindakan tertentu, gunakan parameter bantuan selain parameter tindakan tersebut.

SqlPackage /Action:Publish /?

Otentikasi

SqlPackage mengautentikasi menggunakan metode yang tersedia di SqlClient. Mengonfigurasi jenis autentikasi dapat dicapai melalui parameter string koneksi untuk setiap tindakan SqlPackage (/SourceConnectionString dan /TargetConnectionString) atau melalui parameter individual untuk properti koneksi. Metode autentikasi berikut didukung dalam string koneksi:

  • Autentikasi SQL Server
  • Autentikasi Direktori Aktif (Windows)
  • Autentikasi Microsoft Entra
    • Nama pengguna/kata sandi
    • Autentikasi terintegrasi
    • Autentikasi universal
    • Identitas yang dikelola
    • Prinsipal layanan

Identitas yang dikelola

Nota

MICROSOFT Entra ID sebelumnya dikenal sebagai Azure Active Directory (Azure AD).

Di lingkungan otomatis, identitas terkelola Microsoft Entra adalah metode autentikasi yang direkomendasikan. Metode ini tidak memerlukan meneruskan kredensial ke SqlPackage saat runtime karena SqlPackage menggunakan identitas terkelola untuk menyambungkan ke database yang mendukung autentikasi Microsoft Entra, dan untuk mendapatkan token Microsoft Entra, tanpa manajemen kredensial. Saat identitas terkelola dikonfigurasi untuk lingkungan tempat tindakan SqlPackage dijalankan, tindakan SqlPackage dapat menggunakan identitas tersebut untuk mengautentikasi ke Azure SQL. Untuk informasi selengkapnya tentang mengonfigurasi identitas terkelola untuk lingkungan Anda, lihat dokumentasi Identitas terkelola.

Contoh string koneksi menggunakan identitas terkelola yang ditetapkan sistem adalah:

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

Identitas terkelola didukung dalam alur CI/CD di Azure DevOps dan aksi GitHub.

Prinsipal layanan

Nota

MICROSOFT Entra ID sebelumnya dikenal sebagai Azure Active Directory (Azure AD).

Perwakilan layanan aplikasi Microsoft Entra adalah objek keamanan dalam aplikasi Microsoft Entra yang menentukan apa yang dapat dilakukan aplikasi di penyewa tertentu. Mereka disiapkan di portal Microsoft Azure selama proses pendaftaran aplikasi dan dikonfigurasi untuk mengakses sumber daya Azure, seperti Azure SQL. Untuk informasi selengkapnya tentang mengonfigurasi perwakilan layanan untuk lingkungan Anda, lihat dokumentasi Perwakilan layanan.

Saat menggunakan SqlPackage dengan perwakilan layanan, Anda dapat mengambil token akses dan meneruskannya ke SqlPackage. Token akses dapat diambil menggunakan modul Azure PowerShell atau Azure CLI. Dalam proses ini, sistem pemanggilan mempertahankan kontrol atas refresh atau pembatalan token. Token akses dapat diteruskan ke SqlPackage menggunakan /at parameter .

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

Atau, Anda dapat meneruskan ID klien utama layanan dan rahasia ke SqlPackage dalam string koneksi. Format string koneksi mencakup Authentication=Active Directory Service Principal; dan User Id=AppId; Password=<password>. Ketika kredensial prinsipal layanan diteruskan dalam string koneksi, parameter /at tidak diperlukan dan SqlPackage menyegarkan autentikasi sesuai kebutuhan selama operasi.

Prinsipal layanan didukung dalam alur CI/CD di Azure DevOps dan GitHub Actions.

Variabel lingkungan

Pengumpulan koneksi

Pengumpulan koneksi dapat diaktifkan untuk semua koneksi yang dibuat oleh SqlPackage dengan mengatur CONNECTION_POOLING_ENABLED variabel lingkungan ke True. Pengaturan ini direkomendasikan untuk operasi dengan nama pengguna Microsoft Entra dan koneksi kata sandi untuk menghindari pembatasan oleh Microsoft Authentication Library (MSAL).

File sementara

Selama operasi SqlPackage, data tabel ditulis ke file sementara sebelum pemadatan atau setelah dekompresi. Untuk database besar, file sementara ini dapat memakan sejumlah besar ruang disk tetapi lokasinya dapat ditentukan. Operasi ekspor dan ekstrak menyertakan properti opsional untuk menentukan /p:TempDirectoryForTableData untuk mengambil alih nilai default SqlPackage.

.NET API GetTempPath digunakan untuk menentukan nilai default dalam SqlPackage.

Untuk Windows, variabel lingkungan berikut diperiksa dalam urutan berikut dan jalur pertama yang ada digunakan:

  1. Jalur yang ditentukan oleh TMP variabel lingkungan.
  2. Jalur yang ditentukan oleh TEMP variabel lingkungan.
  3. Jalur yang ditentukan oleh USERPROFILE variabel lingkungan.
  4. Direktori Windows.

Untuk Linux dan macOS, jika jalur tidak ditentukan dalam TMPDIR variabel lingkungan, jalur /tmp/ default digunakan.

Pengguna SqlPackage dan database

Pengguna basis data yang tercakup disertakan dalam operasi SqlPackage. Namun, bagian kata sandi dari definisi diatur ke string yang dihasilkan secara acak oleh SqlPackage, nilai yang ada tidak ditransfer. Disarankan agar kata sandi pengguna baru diatur ulang ke nilai aman setelah impor .bacpac atau penyebaran .dacpac. Di lingkungan otomatis, nilai kata sandi dapat diambil dari keystore aman, seperti Azure Key Vault, dalam langkah berikut SqlPackage.

Ekstensibilitas

SqlPackage mendukung ekstensibilitas melalui Managed Extensibility Framework (MEF), memungkinkan skenario tingkat lanjut melalui komponen kustom yang disebut kontributor. Ekstensi ini dapat menyesuaikan cara SqlPackage menerbitkan .dacpac file, memungkinkan tim untuk menerapkan standar atau mengotomatiskan logika khusus proyek. Kontributor penerapan dijalankan sebagai bagian dari proses penerbitan, setelah rencana penerapan dihasilkan tetapi sebelum dieksekusi. Kontributor ini dapat mengakses dan mengubah rencana penyebaran menggunakan DeploymentPlanModifier objek kelas untuk menambahkan, menghapus, atau menyusun ulang langkah-langkah. Untuk mulai menggunakan ekstensibilitas penyebaran, lihat Menggunakan kontributor penyebaran untuk menyesuaikan build dan penyebaran database.

SqlPackage menemukan dan memuat rakitan kontributor dengan memindai pustaka tautan dinamis (.dll file) di direktori yang sama dengan SqlPackage yang dapat dieksekusi serta lokasi yang ditentukan melalui properti /p:AdditionalDeploymentContributorPathsbaris perintah opsional . Meskipun ini memungkinkan penyesuaian yang fleksibel, ini juga memperkenalkan pertimbangan keamanan penting.

Penting

Karena SqlPackage menggunakan MEF untuk memuat pustaka tautan dinamis (.dll file) secara dinamis saat runtime, rakitan apa pun yang ditempatkan bersama SqlPackage yang dapat dieksekusi dapat dijalankan sebagai bagian dari proses penyebaran. Aktor jahat dapat mengeksploitasi perilaku ini dengan memperkenalkan ekstensi yang diubah atau tidak sah yang menjalankan kode sewenang-wenang.

Anda bertanggung jawab untuk memastikan bahwa file ekstensi yang dikompilasi yang digunakan dengan SqlPackage aman dan berasal dari sumber tepercaya. Sebaiknya kontrol akses ke folder SqlPackage dan validasi integritas semua komponen kustom atau pihak ketiga.

Pengumpulan data penggunaan

SqlPackage berisi fitur berkemampuan Internet yang dapat mengumpulkan dan mengirim penggunaan fitur anonim dan data diagnostik ke Microsoft.

SqlPackage dapat mengumpulkan informasi komputer, penggunaan, dan performa standar yang dapat ditransmisikan ke Microsoft dan dianalisis untuk meningkatkan kualitas, keamanan, dan keandalan SqlPackage.

SqlPackage tidak mengumpulkan informasi spesifik atau pribadi pengguna. Untuk membantu memperkirakan satu pengguna untuk tujuan diagnostik, SqlPackage menghasilkan GUID acak untuk setiap komputer yang dijalankannya dan menggunakan nilai tersebut untuk semua peristiwa yang dikirimnya.

Untuk detailnya, lihat Pernyataan Privasi Microsoft dan suplemen Privasi SQL Server.

Menonaktifkan pelaporan telemetri

Untuk menonaktifkan pengumpulan dan pelaporan telemetri, perbarui variabel DACFX_TELEMETRY_OPTOUT lingkungan ke true atau 1.

Dukungan

Pustaka DacFx dan alat SqlPackage CLI mengikuti Kebijakan Siklus Hidup Modern Microsoft. Semua pembaruan keamanan, perbaikan, dan fitur baru hanya dirilis dalam versi titik terbaru dari versi utama. Mempertahankan penginstalan DacFx atau SqlPackage Anda ke versi saat ini membantu memastikan bahwa Anda menerima semua perbaikan bug yang berlaku secara tepat waktu.

Dapatkan bantuan dengan SqlPackage, kirim permintaan fitur, dan laporkan masalah di repositori GitHub DacFx.

Penawaran SQL yang didukung

SqlPackage dan DacFx mendukung semua versi SQL yang didukung pada saat rilis SqlPackage/DacFx. Misalnya, rilis SqlPackage pada 14 Januari 2022 mendukung semua versi SQL yang didukung pada 14 Januari 2022. Untuk informasi selengkapnya tentang kebijakan dukungan SQL, lihat kebijakan dukungan SQL.

Selain SQL Server, SqlPackage dan DacFx mendukung Azure SQL Managed Instance, Azure SQL Database, Azure Synapse Analytics, dan Fabric Data Warehouse.

Langkah berikutnya

  • Last updated on