ApsaraDB RDS：Pembatasan SQL (rds_ccl)

Skenario

Anda hanya dapat memanggil fungsi ini pada instans utama untuk membuat aturan pembatasan SQL.

Sintaksis

• Sintaksis 1: Lakukan pembatasan pada pernyataan SQL tertentu.

  SELECT rds_add_ccl_rule(
  	query_string varchar,
  	node_tag int,
  	max_concurrency int,
  	max_waiting int,
  	is_enabled boolean,
  	comment varchar,		-- Opsional
  	search_path varchar		-- Opsional
  );

• Sintaksis 2: Lakukan pembatasan berdasarkan query_id tertentu.

  SELECT rds_add_ccl_rule_with_query_id(
    query_id		bigint,
    node_tag		int,
    max_concurrency	int,
    max_waiting		int,
    is_enabled		boolean,
    query_string		varchar,	-- Opsional
    comment		varchar,	-- Opsional
    search_path           varchar		-- Opsional (Didukung di versi 1.2 dan lebih baru)
  );

Parameter

-- Gunakan $$ untuk membungkus pernyataan SQL.
$$SELECT * FROM my_table;$$

-- Jika pernyataan SQL sudah mengandung $$, gunakan $ccl$ untuk membungkus pernyataan SQL.
$ccl$SELECT * FROM my_table WHERE my_column = $$hello$$;$ccl$

Catatan Penggunaan

• Dalam Sintaksis 1, jika Anda tidak mengonfigurasi parameter comment dan search_path, Anda dapat menyetelnya ke string kosong (''). Jika Anda menyetelnya ke NULL, fungsi tidak melakukan operasi apa pun dan langsung kembali.

• Dalam Sintaksis 2:

  • Jika Anda tidak mengonfigurasi parameter query_string dan comment, Anda dapat menyetelnya ke string kosong (''). Jika Anda menyetelnya ke NULL, fungsi tidak melakukan operasi apa pun dan langsung kembali.

  • Jika Anda mengonfigurasi baik query_id maupun query_string, kernel AliPG melakukan pembatasan SQL berdasarkan query_id.

• Fungsi ini mengembalikan ccl_id, yang merupakan pengenal unik untuk aturan pembatasan di database saat ini.

Contoh SQL

Asumsikan bahwa tabel data bernama `ccl_tbl` ada di database `ccl_test` dari instans utama. Buat aturan pembatasan SQL yang memenuhi persyaratan berikut:

1. Batasi semua pernyataan SELECT * FROM ccl_tbl. Asumsikan bahwa query_id mereka adalah `1`.

2. Izinkan maksimal tiga pernyataan SQL seperti itu dieksekusi secara bersamaan.

3. Izinkan maksimal dua pernyataan SQL semacam itu untuk menunggu.

4. Aturan harus langsung berlaku setelah dibuat.

• Sintaksis 1:

  SELECT rds_add_ccl_rule(
    $$SELECT * FROM ccl_tbl;$$,		-- Pernyataan SQL yang akan dibatasi, dibungkus dalam $$.
    1,					-- Membatasi instans utama saja.
    3,					-- Mengizinkan maksimal 3 pernyataan SQL semacam itu untuk dieksekusi secara bersamaan.
    2,					-- Mengizinkan maksimal 2 pernyataan SQL semacam itu untuk menunggu.
    true,					-- Aturan berlaku segera.
    'limit constant select',		-- Deskripsi aturan.
    ''					-- Menggunakan search_path default.
  );

• Sintaksis 2:

  SELECT rds_add_ccl_rule_with_query_id(
    1,					-- query_id dari pernyataan SQL yang akan dibatasi.
    1,					-- Membatasi instans utama saja.
    3,					-- Mengizinkan maksimal 3 pernyataan SQL semacam itu untuk dieksekusi secara bersamaan.
    2,					-- Mengizinkan maksimal 2 pernyataan SQL semacam itu untuk menunggu.
    true,					-- Aturan berlaku segera.
    '',					-- Teks dari pernyataan SQL. Ini tidak ditentukan dalam contoh ini.
    'limit constant select',		-- Deskripsi aturan.
    'public'                              -- search_path.
  );

Skenario

Anda dapat menjalankan perintah ini pada instans utama atau instansi hanya baca untuk menanyakan aturan pembatasan SQL yang telah dibuat.

Sintaksis

• Untuk melihat semua aturan pembatasan SQL di semua database dari instans saat ini:

  SELECT * FROM rds_enabled_ccl_rule;

  Catatan

  • Dalam hasil kueri perintah ini, nilai untuk query_string dan comment dipotong menjadi 200 karakter karena keterbatasan tampilan. Untuk melihat informasi lengkap, jalankan perintah SELECT * FROM rds_show_current_db_ccl_rule();.

  • Versi 1.2 dan yang lebih baru dari rds_ccl mendukung pengembalian search_path.

• Untuk menanyakan semua aturan pembatasan SQL di database saat ini:

  SELECT * FROM rds_show_current_db_ccl_rule();

Skenario

Anda hanya dapat memanggil fungsi ini pada instans utama. Fungsi ini berlaku untuk skenario berikut:

• Jika Anda mengatur parameter is_enabled ke false saat membuat aturan pembatasan SQL, Anda dapat menggunakan fungsi ini untuk mengaktifkan aturan tersebut.

• Anda juga dapat menggunakan fungsi ini untuk mengaktifkan aturan yang sebelumnya dinonaktifkan.

Sintaksis

SELECT rds_enable_ccl_rule(ccl_id int);

Parameter

Catatan Penggunaan

Tidak ada.

Contoh SQL

SELECT rds_enable_ccl_rule(1);

Skenario

Anda dapat memanggil fungsi ini pada instans utama atau instansi hanya baca untuk memuat aturan pembatasan SQL. Hanya aturan yang dimuat yang dapat digunakan untuk pembatasan SQL.

Fungsi ini berlaku untuk skenario berikut:

• Instans utama:

  • Saat Anda membuat aturan pembatasan SQL, jika is_enabled diatur ke true, aturan tersebut secara otomatis dimuat pada instans utama. Dalam hal ini, Anda tidak perlu memanggil fungsi ini.

  • Saat Anda membuat aturan pembatasan SQL, jika is_enabled diatur ke false, aturan tersebut secara otomatis dimuat pada instans utama saat Anda memanggil fungsi rds_enable_ccl_rule untuk mengaktifkannya. Dalam hal ini, Anda tidak perlu memanggil fungsi ini.

  • Jika instans utama di-restart, Anda harus secara manual memanggil fungsi ini untuk memuat aturan.

• Instans hanya baca:

  Jika suatu aturan perlu berlaku pada instansi hanya baca, Anda harus membuat aturan tersebut pada instans utama dan mengatur parameter node_tag ke 2 atau 3. Kemudian, Anda harus memanggil fungsi ini pada instansi hanya baca untuk secara manual memuat aturan.

Sintaksis

SELECT rds_load_ccl_rule(ccl_id int);

Parameter

Catatan Penggunaan

• Anda dapat memuat aturan pada instansi hanya baca hanya setelah aturan pembatasan SQL dibuat pada instans utama dengan memanggil fungsi rds_add_ccl_rule dengan parameter node_tag diatur ke 2 atau 3.

• Aturan yang dinonaktifkan tidak dapat dimuat. Untuk memuat aturan yang dinonaktifkan pada instansi hanya baca, Anda harus terlebih dahulu mengaktifkan aturan tersebut pada instans utama. Untuk informasi lebih lanjut, lihat Aktifkan aturan pembatasan SQL.

Contoh SQL

SELECT rds_load_ccl_rule(1);

Skenario

Fungsi ini hanya dapat dipanggil pada instans utama untuk mengubah konkurensi maksimum dan jumlah tunggu maksimum dalam aturan pembatasan SQL.

Sintaksis

SELECT rds_update_ccl_rule(
	ccl_id int,
	new_max_concurrency int,
	new_max_waiting int
);

Parameter

Catatan Penggunaan

• Pembaruan ke aturan pembatasan SQL berlaku segera.

• Anda hanya dapat mengubah konkurensi maksimum dan jumlah tunggu maksimum dalam aturan pembatasan SQL.

Contoh SQL

SELECT rds_update_ccl_rule(
 2,     -- ccl_id
 4,     -- Konkurensi maksimum baru adalah 4.
 5      -- Jumlah tunggu maksimum baru adalah 5.
);

Skenario

Anda hanya dapat memanggil fungsi ini pada instans utama untuk menonaktifkan aturan pembatasan SQL. Setelah aturan dinonaktifkan, aturan tersebut tidak lagi membatasi pernyataan SQL.

Sintaksis

• Untuk menonaktifkan aturan pembatasan SQL tertentu:

  SELECT rds_disable_ccl_rule(ccl_id int);

• Untuk menonaktifkan semua aturan pembatasan SQL di database saat ini:

  SELECT rds_disable_all();

Parameter

Catatan Penggunaan

• Aturan yang dinonaktifkan tidak dapat dimuat. Untuk memuat aturan yang dinonaktifkan pada instansi hanya baca, Anda harus terlebih dahulu mengaktifkan aturan tersebut pada instans utama. Untuk informasi lebih lanjut, lihat Aktifkan aturan pembatasan SQL.

• Saat Anda menonaktifkan aturan pembatasan SQL, aturan tersebut secara otomatis dilepas dari instans utama dan tidak lagi membatasi pernyataan SQL.

Contoh SQL

SELECT rds_disable_ccl_rule(1);

Skenario

Anda dapat memanggil fungsi ini pada instans utama atau instansi hanya baca untuk melepas aturan pembatasan SQL. Aturan yang dilepas tidak lagi membatasi pernyataan SQL.

Fungsi ini berlaku untuk skenario berikut:

• Instans Utama:

  • Jika Anda memanggil fungsi rds_disable_ccl_rule atau rds_disable_all pada instans utama untuk menonaktifkan aturan, aturan tersebut secara otomatis dilepas dari instans utama. Dalam hal ini, Anda tidak perlu memanggil fungsi ini.

  • Jika Anda memanggil fungsi rds_del_ccl_rule pada instans utama untuk menghapus aturan, aturan tersebut secara otomatis dilepas dari instans utama. Dalam hal ini, Anda tidak perlu memanggil fungsi ini.

  • Anda juga dapat memanggil fungsi ini untuk melepaskan aturan secara manual dari instans utama.

• Instans hanya baca:

  Jika Anda tidak ingin aturan membatasi pernyataan SQL pada instansi hanya baca, Anda dapat memanggil fungsi ini untuk melepasnya secara manual dari instansi hanya baca.

Sintaksis

SELECT rds_unload_ccl_rule(ccl_id int, db_name varchar default '');

Parameter

Catatan Penggunaan

Setelah aturan dilepas, aturan tersebut tidak lagi membatasi pernyataan SQL. Untuk menggunakan kembali aturan tersebut, Anda harus memuat ulang aturan tersebut. Untuk informasi lebih lanjut, lihat Muat aturan pembatasan SQL.

Contoh SQL

SELECT rds_unload_ccl_rule(1,'');

Skenario

Anda dapat memanggil fungsi ini hanya pada instans utama untuk menghapus aturan pembatasan SQL. Saat aturan dihapus, aturan tersebut secara otomatis dilepas dari instans utama.

Sintaksis

SELECT rds_del_ccl_rule(ccl_id int);

Parameter

Catatan Penggunaan

Tidak ada.

Contoh SQL

SELECT rds_del_ccl_rule(1);

Hasil contoh:

   rds_del_ccl_rule   
----------------------
 -7851264404688445170
(1 baris)

• Sebuah query_id adalah pengenal khusus untuk pernyataan SQL di PostgreSQL. Pernyataan SQL yang serupa berbagi query_id yang sama.

  Contoh:

  -- Dua pernyataan SQL berikut memiliki query_id yang sama.
  SELECT * FROM tbl WHERE a = 1;
  SELECT * FROM tbl WHERE a = 2;

• Sebuah query_id berisi informasi tentang objek dalam pernyataan SQL, yang didasarkan pada pengenal objek (oid). Tabel dengan nama yang sama dianggap sebagai objek yang berbeda jika mereka berada di database atau skema yang berbeda. Oleh karena itu, pernyataan SQL yang identik memiliki nilai query_id yang berbeda jika mereka merujuk ke objek yang berbeda.

• Jika objek yang diakses dalam pernyataan SQL adalah tabel global atau fungsi global, query_id akan tetap sama terlepas dari database tempat pernyataan tersebut dijalankan.

  • Contoh 1: pg_database adalah tabel global. query_id tetap sama ketika tabel ini di-query dari database yang berbeda.

    • Jalankan pernyataan berikut di database `ccl_test`:

      SELECT rds_get_query_id($$SELECT * FROM pg_database;$$);

      Hasil contoh:

         rds_get_query_id   
      ----------------------
       -8733244708994363681
      (1 baris)

    • Jalankan pernyataan berikut di database `ccl_test2`:

      SELECT rds_get_query_id($$SELECT * FROM pg_database;$$);

      Hasil contoh:

         rds_get_query_id   
      ----------------------
       -8733244708994363681
      (1 baris)

  • Contoh 2: pg_sleep adalah fungsi global. query_id tetap sama ketika fungsi ini dipanggil dari database yang berbeda.

    • Jalankan pernyataan berikut di database `ccl_test`:

      SELECT rds_get_query_id($$SELECT pg_sleep(1);$$);

      Hasil contoh:

        rds_get_query_id  
      --------------------
       440101247839410938
      (1 baris)

    • Jalankan pernyataan berikut di database `ccl_test2`:

      SELECT rds_get_query_id($$SELECT pg_sleep(1);$$);

      Hasil contoh:

        rds_get_query_id  
      --------------------
       440101247839410938
      (1 baris)

• Saat Anda memanggil fungsi, query_id berubah jika tipe parameter berubah atau jika klausa FROM ditambahkan atau dihapus.

  Sebagai contoh, saat Anda memanggil fungsi pg_sleep, query_id yang dikembalikan berbeda berdasarkan konteksnya.

  • Tanpa klausa `FROM`:

    SELECT rds_get_query_id($$SELECT pg_sleep(1);$$);

    Hasil contoh:

      rds_get_query_id  
    --------------------
     440101247839410938
    (1 baris)

  • Dengan klausa `FROM`:

    SELECT rds_get_query_id($$SELECT * FROM pg_sleep(1);$$);

    Hasil contoh:

       rds_get_query_id   
    ----------------------
     -3404018605099167039
    (1 baris)

  • Jika tipe parameter berubah:

    select rds_get_query_id($$SELECT * FROM pg_sleep(1.0);$$);

    Hasil contoh:

      rds_get_query_id   
    ---------------------
     3073869725037049158
    (1 baris)