Share via

SQLPackage

  • Artikel

SqlPackage adalah utilitas baris perintah yang mengotomatiskan tugas pengembangan database dengan mengekspos beberapa API Kerangka Kerja Aplikasi Tingkat Data (DacFx) 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.

Catatan

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 tersambung - termasuk struktur 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 . Tindakan Terbitkan memperbarui skema database agar sesuai dengan konten file .dacpac sumber, sementara tindakan Ekstrak membuat file aplikasi tingkat data (.dacpac) yang berisi skema atau skema dan data pengguna dari database SQL yang tersambung. SqlPackage memungkinkan penyebaran terhadap database baru atau yang sudah ada dari artefak yang sama (.dacpac) dengan secara otomatis membuat rencana penyebaran yang akan 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 tingkat 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 bertahap Transact-SQL yang memperbarui skema target agar sesuai dengan skema sumber.

SintaksIs Baris Perintah

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 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 /?

Autentikasi

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 terkelola
    • Perwakilan layanan

Identitas terkelola

Catatan

ID Microsoft Entra 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 di alur CI/CD tindakan Azure DevOps dan GitHub.

Perwakilan layanan

Catatan

ID Microsoft Entra 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 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, mungkin diperlukan untuk mengambil token akses dan meneruskannya ke SqlPackage. Token akses dapat diambil menggunakan modul Azure PowerShell atau Azure CLI. 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;"

Perwakilan layanan didukung di alur CI/CD tindakan Azure DevOps dan GitHub.

Variabel lingkungan

Pengumpulan koneksi

Koneksi ion pooling 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 database yang terkandung 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.

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 suplemen Pernyataan Privasi Microsoft, dan 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 telah mengadopsi 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 Synapse Data Warehouse di Microsoft Fabric.

Langkah berikutnya