PolarDB：pg_cron

Informasi Latar Belakang

Tugas terjadwal dijalankan secara otomatis pada waktu atau interval tertentu. Penjadwal bertugas mengeksekusi tugas berdasarkan aturan waktu yang telah ditentukan. Anda dapat mengonfigurasi penjadwal untuk menjalankan tugas harian, mingguan, bulanan, atau sesuai kebutuhan dengan interval tertentu.

Berikut adalah beberapa skenario penggunaan tugas terjadwal:

• Di sisi server, tugas terjadwal sering digunakan untuk menjalankan tugas latar belakang, menghasilkan laporan, dan membersihkan data sampah.

• Di sisi klien, tugas terjadwal dapat digunakan untuk memperbarui data, mengirimkan peringatan kepada pengguna, dan melakukan operasi otomatis.

Dengan menggunakan tugas terjadwal di kedua sisi, Anda dapat mengurangi operasi manual dan meningkatkan efisiensi kerja.

Ekstensi pg_cron memiliki keunggulan berikut:

• Kemudahan penggunaan: Anda dapat membuat, menjadwalkan, dan mengelola tugas hanya dengan Pernyataan SQL tanpa konfigurasi tambahan.

• Fleksibilitas penjadwalan: Anda dapat menjadwalkan tugas berdasarkan menit, jam, tanggal, minggu, bulan, atau kombinasi waktu apa pun.

• Manajemen tugas tingkat database: Tugas disimpan dalam database dan dapat dibagi serta dikelola di beberapa database.

• Eksekusi bersamaan: Beberapa tugas dapat dieksekusi secara bersamaan untuk meningkatkan efisiensi.

• Keandalan dan toleransi kesalahan: Mekanisme penanganan kesalahan memastikan tugas dieksekusi dengan benar dan log yang sesuai dihasilkan.

Ekstensi pg_cron adalah alat yang sederhana namun kuat bagi administrator basis data dan pengembang untuk mengotomatiskan tugas-tugas berulang. Sebagai contoh, Anda dapat menggunakan pg_cron untuk mencadangkan data, menghasilkan laporan, dan melakukan pembersihan rutin, sehingga meningkatkan efisiensi manajemen dan pengembangan basis data.

Catatan Penggunaan

Jika Anda me-restart kluster PolarDB for PostgreSQL dengan versi mesin minor 14.10.16.0 atau lebih lama, port kluster akan berubah dan tugas yang dibuat menggunakan ekstensi pg_cron mungkin gagal. Masalah ini telah diperbaiki pada versi mesin minor 14.10.16.1 atau lebih baru.

Cara Kerja

Pemeliharaan Informasi Tugas Terjadwal

Semua tugas terjadwal disimpan dalam tabel cron.job. Anda dapat membuat atau menghapus tugas terjadwal dengan memanggil fungsi SQL.

Ekstensi pg_cron memelihara daftar JOB LIST dan TASK LIST untuk penjadwalan latar belakang dan eksekusi tugas. Saat basis data dimulai, JOB LIST dan TASK LIST dibuat berdasarkan daftar tugas dalam tabel cron.job. Jika daftar tugas diperbarui kemudian, pemicu cron.job_cache_invalidate memperbarui daftar untuk menjaga JOB LIST dan TASK LIST tetap sinkron dengan tabel cron.job secara real-time. Ini memastikan bahwa tugas dapat dijadwalkan dan dieksekusi dengan benar.

Penjadwalan dan Eksekusi Tugas Terjadwal

• WAITING: Status default. Jika kondisi tidak terpenuhi, misalnya tugas belum diaktifkan atau waktu yang dijadwalkan belum tercapai, penjadwalan dilewati. Jika kondisi terpenuhi, tugas masuk ke status START.

• START: Menetapkan informasi koneksi tugas dan melakukan tes koneksi. Jika koneksi berhasil, tugas masuk ke status CONNECTING. Jika tidak, tugas masuk ke status ERROR.

• CONNECTING: Memeriksa apakah tugas diaktifkan dan koneksi normal. Jika semua kondisi terpenuhi, tugas masuk ke status SENDING. Jika tidak, tugas masuk ke status ERROR.

• SENDING: Memeriksa apakah tugas diaktifkan dan apakah koneksi normal. Jika semua kondisi terpenuhi, tugas terjadwal dikirim ke server PolarDB for PostgreSQL dan masuk ke status RUNNING. Jika tidak, tugas masuk ke status ERROR.

• RUNNING: Memeriksa apakah tugas diaktifkan dan koneksi normal. Jika semua kondisi terpenuhi, sistem menerima hasil tugas dan tugas masuk ke status DONE. Jika tidak, sistem berhenti menunggu dan tugas masuk ke status ERROR.

• ERROR: Tugas gagal. Sistem mereset informasi koneksi dan tugas masuk ke status DONE.

• DONE: Tugas selesai. Sistem mereset informasi tugas dan tugas kembali ke status WAITING.

Fungsi

Buat Tugas Terjadwal

Sintaks

cron.schedule (
    job_name TEXT,
    schedule TEXT,
    command TEXT
);

Parameter

Buat Tugas Terjadwal di Basis Data Tertentu

Sintaks

cron.schedule_in_database (
    job_name TEXT,
    schedule TEXT,
    command TEXT,
    db_name TEXT
);

Parameter

Ubah Tugas Terjadwal

Sintaks

cron.alter_job (
    job_id BIGINT,
    schedule TEXT DEFAULT NULL,
    command TEXT DEFAULT NULL,
    db_name TEXT DEFAULT NULL,
    active BOOLEAN DEFAULT NULL
);

Parameter

Hapus Tugas Terjadwal

Sintaks

cron.unschedule(job_id BIGINT);

cron.unschedule(job_name TEXT);

Parameter

Penggunaan

Buat Ekstensi pg_cron

Hubungkan ke basis data dan jalankan perintah berikut untuk membuat ekstensi pg_cron:

CREATE EXTENSION pg_cron;

Buat Tugas Terjadwal

Jalankan perintah berikut untuk membuat tugas bernama task1 untuk basis data db01. ID tugas dikembalikan.

SELECT cron.schedule_in_database('task1', '* * * * *', 'SELECT 1', 'db01');

Contoh hasil:

 schedule_in_database
----------------------
                    1
(1 row)

Lihat Tugas Terjadwal

Jalankan perintah berikut untuk melihat tugas terjadwal:

SELECT * FROM cron.job;

Contoh hasil:

jobid | schedule  | command  | nodename | nodeport | database | username | active | jobname
-------+-----------+----------+----------+----------+----------+----------+--------+---------
     1 | * * * * * | SELECT 1 | /tmp     |    39361 | db01     | u1       | t      | task1
(1 row)

Lihat Riwayat Eksekusi Tugas Terjadwal

Jalankan perintah berikut untuk melihat riwayat eksekusi tugas terjadwal:

SELECT * FROM cron.job_run_details;

Contoh hasil:

 jobid | runid | job_pid | database | username | command  |  status   | return_message |          start_time           |           end_time
-------+-------+---------+----------+----------+----------+-----------+----------------+-------------------------------+-------------------------------
     1 |     1 | 4152316 | db01     | u1       | SELECT 1 | succeeded | 1 row          | 2023-10-19 03:55:00.020442+00 | 2023-10-19 03:55:00.021512+00
     1 |     2 | 4152438 | db01     | u1       | SELECT 1 | succeeded | 1 row          | 2023-10-19 03:56:00.006468+00 | 2023-10-19 03:56:00.006822+00
(2 rows)

Hapus Tugas Terjadwal

Jalankan perintah berikut untuk menghapus tugas terjadwal:

SELECT cron.unschedule('task1');

Contoh hasil:

 unschedule
------------
 t
(1 row)

Hapus Ekstensi pg_cron

Jalankan perintah berikut untuk menghapus ekstensi pg_cron:

DROP EXTENSION pg_cron;

Contoh Aturan Waktu

Ekstensi pg_cron menggunakan sintaks cron standar. * menunjukkan bahwa tugas dijalankan pada interval waktu tertentu. Angka-angka yang ditentukan menunjukkan periode waktu antara dua eksekusi berturut-turut.

┌───────────── Menit (0 hingga 59)
 │ ┌────────────── Jam (0 hingga 23)
 │ │ ┌─────────────── Tanggal (1 hingga 31)
 │ │ │ ┌──────────────── Bulan (1 hingga 12)
 │ │ │ │ ┌───────────────── Hari dalam seminggu (0 hingga 6). Nilai 0 menunjukkan Minggu. Nilai 6 menunjukkan Sabtu berikutnya. 
 │ │ │ │ │                  Nilai 7 juga menunjukkan Minggu.
 * * * * *

• Hapus data kedaluwarsa pada GMT 03:30 setiap hari Sabtu.

  SELECT cron.schedule('30 3 * * 6', $$DELETE FROM events WHERE event_time < now() - interval '1 week'$$);

• Eksekusi VACUUM pada GMT 10:00 setiap hari.

  SELECT cron.schedule('0 10 * * *', 'VACUUM;');

• Eksekusi Pernyataan SQL tertentu setiap menit.

  SELECT cron.schedule('* * * * *', 'SELECT 1;');

• Eksekusi Pernyataan SQL tertentu pada menit ke-23 setiap jam.

  SELECT cron.schedule('23 * * * *', 'SELECT 1;');

• Eksekusi Pernyataan SQL tertentu pada hari keempat setiap bulan.

  SELECT cron.schedule('* * 4 * *', 'SELECT 1;');