Skrip pra-penyebaran dan pasca-penyebaran untuk Fabric Data Warehouse (Pratinjau)

Diterapkan pada:✅ Gudang di Microsoft Fabric

Important

Fitur ini sedang dalam tahap pratinjau.

Skrip pra-penyebaran dan pasca-penyebaran memungkinkan Anda menjalankan perintah Transact-SQL kustom sebagai bagian dari penyebaran gudang di Fabric. Gunakan skrip pra-penyebaran dan pasca-penyebaran untuk membersihkan data, data referensi benih, atau menerapkan keamanan SQL yang tidak dinyatakan dalam skema gudang.

Dalam Fabric Data Warehouse, skrip pra-penyebaran atau pasca-penyebaran adalah kueri SQL yang dibagikan. Anda dapat menulis skrip ini dalam proyek database SQL dan menunjuknya dari portal Fabric. Penetapan tersebut disimpan sebagai metadata pada tingkat warehouse dan dikomitkan ke kontrol sumber sebagai bagian dari file .sqlproj milik warehouse, sehingga tetap terbawa melalui Git dan pipeline deployment tanpa perlu diterapkan ulang secara manual.

Artikel ini menjelaskan apa itu skrip pra-penyebaran dan pasca-penyebaran, cara mengonfigurasinya di portal Fabric, bagaimana perilakunya dengan kontrol sumber dan alur penyebaran, dan cara menulisnya di Visual Studio Code dan SQL Server Management Studio (SSMS).

Important

Selalu tinjau skrip dan pengaturan penyebaran sebelum menerbitkan. Uji di lingkungan pengembangan dan pengujian terlebih dahulu untuk mencegah kehilangan data yang tidak diinginkan.

Apa itu skrip pra-penyebaran dan pasca-penyebaran?

Saat Anda menghubungkan workspace ke kontrol sumber, setiap gudang muncul sebagai proyek basis data SQL: skrip berbasis sumber dari objek SQL yang membentuk skema gudang (tabel, tampilan, prosedur tersimpan, dan fungsi). Setiap objek disimpan sebagai .sql file yang berisi sintaks bahasa definisi data (DDL), seperti CREATE TABLE. Objek menjelaskan status skema yang diinginkan , dan proses penyebaran membandingkan status yang diinginkan dengan gudang target dan menghasilkan skrip T-SQL diferensial yang membuat, mengubah, atau menghilangkan objek sehingga target cocok dengan proyek.

Skrip pra-penyebaran dan pasca-penyebaran memperluas proses ini dengan Transact-SQL yang berjalan di sekitar penyebaran skema:

  • Skrip pra-penyebaran berjalan sebelum rencana penyebaran skema diterapkan.
  • Skrip pasca-penyebaran berjalan setelah rencana penyebaran skema selesai.

Skrip pra-penyebaran atau pasca-penyebaran adalah salah satu kueri bersama yang disimpan di bawah folder Kueri gudang. Gudang mendukung paling banyak satu skrip pra-penyebaran dan satu skrip pasca-penyebaran. Penetapan tersebut disimpan sebagai metadata pada tingkat gudang alih-alih menduplikasi konten skrip, sehingga hampir tidak menambah overhead penyimpanan.

Karena setiap skrip yang ditentukan dijalankan setiap kali data warehouse di-deploy, pastikan Transact-SQL bersifat idempoten (aman untuk dijalankan berulang kali).

Tip

Ketika sebuah skrip bersifat idempotent, Anda bisa menjalankannya beberapa kali tanpa menimbulkan masalah. Anda dapat mendistribusikan ke beberapa basis data tanpa perlu menentukan statusnya terlebih dahulu.

Kasus penggunaan umum

  • Manajemen data referensi dan statis: Menyisipkan, memperbarui, atau menghapus baris dari tabel pencarian, konfigurasi, atau referensi setelah skema disebarkan.
  • Pembersihan data: Hapus data basi atau sementara sebelum atau sesudah perubahan skema diterapkan.
  • Penyiapan lingkungan: Menerapkan pengaturan atau menginisialisasi status yang berbeda antara lingkungan pengembangan, pengujian, dan produksi.
  • Inisialisasi alur berbasis metadata: Siapkan status gudang yang diperlukan oleh langkah-langkah alur hilir.
  • Keamanan SQL: Data tabel gudang dan fitur keamanan SQL seperti peran, pengguna, dan GRANT/DENY izin tidak disertakan dalam proyek database SQL. Gunakan skrip pasca-penyebaran untuk membuat ulang objek ini setelah penyebaran, termasuk perbedaan antara lingkungan pengujian dan produksi. Misalnya, lihat Contoh skrip pasca-penyebaran untuk keamanan SQL.

Struktur dan sintaks file proyek SQL

Proyek SQL gudang data mereferensikan skrip pra-penyebaran dan pasca-penyebaran dalam file proyek (.sqlproj) dengan menggunakan jenis item PostDeploy dan PreDeploy. Setiap entri menunjuk ke satu file kueri bersama dalam proyek.

Contoh berikut menetapkan pre-deployment.sql sebagai skrip pra-penyebaran dan post-deployment.sql sebagai skrip pasca-penyebaran:

<ItemGroup>
  <PreDeploy Include="pre-deployment.sql" />
  <PostDeploy Include="post-deployment.sql" />
</ItemGroup>

Important

Fabric Data Warehouse hanya mendukung satu file untuk skrip pra-penyebaran dan satu file untuk skrip pasca-penyebaran. Membuat skrip dari beberapa file - misalnya, dengan menggunakan perintah SQLCMD :r untuk mereferensikan file lain - tidak didukung. .sqlproj Jika berisi beberapa entri pra-penyebaran atau pasca-penyebaran, pembaruan Git gagal.

Contoh skrip pasca-penyebaran untuk keamanan SQL

Karena fitur keamanan SQL tidak tercakup dalam proyek basis data SQL, skrip pascapenerapan merupakan cara yang umum digunakan untuk membuat ulang fitur tersebut setelah gudang data diterapkan. Tulis skrip agar dapat berjalan pada setiap penerapan.

Sampel berikut membuat peran database kustom bernama DataReaders dan memberikan SELECT izin ke dbo skema.

-- post-deployment.sql
-- Recreate a role and grant permissions after deployment.
IF NOT EXISTS (SELECT 1 FROM sys.database_principals WHERE name = N'DataReaders')
BEGIN
    CREATE ROLE DataReaders;
END;
GO

GRANT SELECT ON SCHEMA::dbo TO DataReaders;
GO

Note

Fabric Data Warehouse tidak mendukung setiap pernyataanTransact-SQL yang tersedia di SQL Server. Pastikan pernyataan dalam skrip Anda didukung di Fabric Data Warehouse.

Mengonfigurasi skrip pra-penyebaran dan pasca-penyebaran di portal Fabric

Di portal Fabric, tetapkan kueri bersama yang ada sebagai skrip pra-penyebaran atau pasca-penyebaran. Anda dapat melakukan ini dari Object Explorer atau dari Pengaturan item gudang.

Anda tidak dapat menunjuk kueri bersama sebagai skrip pra-penyebaran dan pasca-penyebaran secara bersamaan.

Dari Object Explorer

  1. Di editor gudang, perluas folder Kueri di Object Explorer.
  2. Klik kanan kueri bersama yang ingin Anda gunakan.
    • Jika perlu, pindahkan kueri dari Kueri Saya ke kueri bersama.
  3. Pilih Atur skrip penyebaran. Tindakan ini membawa Anda ke panel pengaturan item.
  4. Di kolom skrip Pra-deployment dan skrip Pasca-deployment , pilih Pilih skrip.
  5. Pilih opsi Tetapkan kueri sebagai skrip pra-/pascapenerapan, kemudian pilih kueri bersama untuk masing-masing. Setiap menu tarik-turun mencantumkan semua kueri yang dibagikan di gudang data.

Dari pengaturan item

  1. Buka Pengaturan gudang.
  2. Buka bagian CI/CD .
  3. Di kolom skrip Pra-deployment dan skrip Pasca-deployment , pilih Pilih skrip.
  4. Pilih opsi Tetapkan kueri sebagai skrip pra-/pascapenerapan, kemudian pilih kueri bersama untuk masing-masing. Setiap menu tarik-turun mencantumkan semua kueri yang dibagikan di gudang data.

Pilihan yang Anda buat disimpan sebagai metadata tingkat gudang dan tetap disinkronkan antara Object Explorer dan item Settings.

Bagaimana skrip pra-penyebaran dan pasca-penyebaran bereaksi dengan penyebaran

Dengan integrasi Git

Saat Anda menyambungkan ruang kerja ke repo Git, penetapan pra-deployment dan pasca-deployment diserialisasikan ke dalam file .sqlproj milik warehouse saat commit dilakukan. Saat Anda memperbarui gudang dari Git, Fabric menerapkan perubahan pada gudang langsung dan menjalankan skrip secara berurutan:

  1. Skrip pra-penyebaran berjalan sebelum perubahan skema diterapkan.
  2. Rencana penyebaran skema diterapkan.
  3. Skrip pasca-penyebaran berjalan setelah perubahan skema selesai.

Penentuan round-trip melalui Git: mengonfigurasi skrip di portal dan menerapkannya, atau menulisnya di .sqlproj dan memperbarui ruang kerja, menghasilkan hasil yang konsisten. Penerapan dan pembaruan berulang tidak menduplikasi atau kehilangan konfigurasi. Karena hanya satu skrip pra-deployment dan satu skrip pasca-deployment yang diizinkan, konfigurasi yang dibuat di Git akan menggantikan penetapan yang sudah ada pada warehouse saat diperbarui.

Note

Skrip pra-deployment dan pasca-deployment memerlukan pengalaman kontrol sumber terbaru untuk dukungan alur kerja Git secara penuh. Di workspace yang belum di-upgrade, metadata skrip deployment tidak disinkronkan dengan kontrol sumber, dan skrip deployment tidak akan berpartisipasi dalam alur kerja berbasis Git.

Keterbatasan ini hanya berlaku untuk alur kerja Git dan bukan prasyarat untuk pipeline deployment (ALM).

Dengan alur penyebaran

Alur deployment menggunakan sebutan pra-deployment dan pasca-deployment saat memindahkan warehouse melalui tahap Pengembangan, Pengujian, dan Produksi. Skrip yang ditunjuk dijalankan secara deterministik di setiap lingkungan target, sehingga Anda dapat menggunakannya untuk menerapkan penyiapan lingkungan atau menerapkan kembali keamanan SQL saat konten berpindah antar tahap.

Di ruang kerja tanpa kontrol sumber

Definisi item gudang mencakup penentuan pra-penyebaran dan pasca-penyebaran bahkan ketika ruang kerja tidak terhubung ke kontrol sumber. Mengekspor gudang mencakup konfigurasi, dan mengimpornya akan memulihkan konfigurasi tersebut secara utuh.

Penulis pra-penyebaran dan skrip pasca-penyebaran dalam proyek database SQL

Alih-alih portal Fabric, Anda dapat menulis skrip pra-penyebaran dan pasca-penyebaran langsung di proyek database SQL gudang dengan menggunakan ekstensi Proyek SQL Database di Visual Studio Code atau pengalaman proyek SQL terintegrasi di SQL Server Management Studio. Konfigurasi akan muncul di portal Fabric—baik di Object Explorer maupun di item Pengaturan—setelah pembaruan Git berikutnya.

Visual Studio Code

  1. Instal ekstensi Proyek SQL Database di Visual Studio Code.
  2. Buka proyek database SQL untuk gudang Anda. Jika ruang kerja Anda terhubung ke Git, kloning repositori, lalu buka folder proyek gudang.
  3. Dalam tampilan Proyek Database , klik kanan simpul proyek dan pilih Tambahkan Skrip Pra-Penyebaran atau Tambahkan Skrip Pasca-Penyebaran.
  4. Berikan nama skrip tanpa ekstensi file. File skrip ditambahkan ke proyek dan dibuka di editor.
  5. Tambahkan Transact-SQL Anda ke skrip dan simpan file. Pastikan file disimpan di .sharedqueries folder untuk pembaruan Git berikutnya.
  6. Terapkan dan dorong perubahan ke repositori Git Anda, lalu perbarui ruang kerja dari kontrol sumber untuk menerapkan konfigurasi.

SQL Server Management Studio

  1. Gunakan SQL Server Management Studio 22 atau yang lebih baru, yang mencakup pengalaman Proyek Database SQL.
  2. Buka proyek database SQL untuk gudang Anda.
  3. Di Penjelajah Solusi, klik kanan simpul proyek dan pilih Tambahkan>Skrip. Pilih Skrip Pra-Penyebaran atau Skrip Pasca-Penyebaran.
  4. File skrip ditambahkan ke proyek dan dibuka di editor kueri.
  5. Tambahkan Transact-SQL Anda ke skrip dan simpan file. Pastikan Anda menyimpan file tersebut di folder untuk .sharedqueries pembaruan Git berikutnya.
  6. Terapkan dan dorong perubahan ke repositori Git Anda, lalu perbarui ruang kerja dari kontrol sumber untuk menerapkan konfigurasi.

Mengedit file proyek secara langsung

Dalam alat apa pun, Anda dapat menunjuk skrip dengan mengedit .sqlproj file dan menambahkan satu PreDeploy atau PostDeploy item ke ItemGroup:

<ItemGroup>
  <PreDeploy Include="./sharedqueries/pre-deployment.sql" />
  <PostDeploy Include="./sharedqueries/post-deployment.sql" />
</ItemGroup>

Migrasi dari proyek SQL yang ada

Jika Anda memigrasikan .sqlproj dari SQL Server Data Tools (SSDT) atau Visual Studio yang sudah berisi <PreDeploy> dan <PostDeploy> entri, proses impor akan mengenali dan memetakan entri tersebut ke konfigurasi Fabric sebelum dan pasca-deployment. Karena Fabric hanya mendukung satu pra-penyebaran dan satu skrip pasca-penyebaran, pastikan proyek berisi paling banyak satu entri dari setiap jenis sebelum mengimpor.

Pertimbangan dan keterbatasan

  • Gudang hanya mendukung satu skrip pra-penyebaran dan satu skrip pasca-penyebaran. Ini tidak mendukung beberapa file per skrip.
  • Anda tidak dapat menetapkan kueri bersama yang sama sebagai skrip pra-penyebaran dan pasca-penyebaran sekaligus.
  • Jika Anda menghapus kueri bersama yang ditetapkan sebagai skrip pra-penyebaran atau pascapenyebaran, penetapan terkait akan dihapus secara otomatis.
  • Jika Anda mengubah kueri bersama yang ditetapkan sebagai skrip pra-penyebaran atau pasca-penyebaran ke dalam kueri pengguna, penugasan yang sesuai akan dihapus secara otomatis.
  • Skrip pra-dan pasca-penyebaran berjalan pada setiap penyebaran gudang. Skrip Transact-SQL harus idempogen, sehingga eksekusi berulang tidak gagal atau membuat objek duplikat.
  • Skrip pra-penyebaran dan pasca-penyebaran tidak divalidasi terhadap model database pada waktu build. Kesalahan dalam skrip muncul saat deployment, dan kegagalan skrip menghentikan deployment.
  • Anda hanya dapat menggunakan Transact-SQL yang didukung di Fabric Data Warehouse.
  • Identitas yang menjalankan penyebaran harus memiliki izin yang diperlukan untuk menjalankan konten skrip.

Konten terkait

  • Terakhir diperbarui pada