KAL
Menu

Postgres plus sebuah extension

Posisi TimescaleDB: SQL lengkap dengan mesin time-series di atasnya.

Daftar isi

TimescaleDB adalah ekstensi Postgres, bukan basis data terpisah atau fork, sehingga pemasangannya tidak menggantikan Postgres melainkan menambah objek baru di dalamnya. Topik ini memperlihatkan mekanisme pemuatan ekstensi Postgres, yaitu control file, shared library, dan skrip instalasi SQL, lalu menunjukkan apa yang berubah dan apa yang tetap setelah perintah CREATE EXTENSION dijalankan. Setelah membaca topik ini, perbedaan antara ekstensi, fork, dan basis data terpisah menjadi jelas, sehingga pemilihan TimescaleDB tidak lagi dilihat sebagai migrasi melainkan sebagai penambahan kapabilitas.

Sebuah ekstensi, bukan fork#

Ekstensi Postgres adalah bundel terdaftar yang berisi tiga lapisan, yaitu control file yang menyatakan metadata, shared library yang berisi kode C, dan satu atau beberapa skrip SQL yang membuat objek baru. Mekanisme ini didefinisikan oleh PostgreSQL sejak versi 9.1, dan banyak ekstensi populer seperti postgis, pg_stat_statements, serta uuid-ossp dipasang dengan cara yang sama. TimescaleDB mengikuti pola yang sama, sehingga pemasangannya tidak mengubah kode sumber Postgres atau mengharuskan binari yang berbeda.

Sebuah fork, sebagai pembanding, adalah salinan kode sumber yang dikembangkan secara terpisah, misalnya Greenplum atau YugabyteDB. Pada fork, fitur baru bisa mengubah perilaku inti, sehingga kompatibilitas dengan Postgres induk tidak selalu terjamin. Sebuah basis data terpisah, misalnya InfluxDB, tidak menggunakan protokol atau binari Postgres sama sekali. Posisi TimescaleDB sebagai ekstensi penting karena dua alasan. Pertama, klien Postgres yang sudah ada, mulai dari psql hingga driver JDBC, tetap berjalan tanpa modifikasi. Kedua, semua fitur Postgres, mulai dari tipe data JSONB hingga window function, tetap tersedia pada hypertable yang diciptakan ekstensi ini.

Memasang ekstensi#

Pemasangan TimescaleDB memerlukan dua langkah pada level server, lalu satu langkah pada level basis data. Pada level server, shared library timescaledb.so harus didaftarkan pada parameter shared_preload_libraries di berkas postgresql.conf agar hook pada planner dan executor dapat dipasang saat Postgres dimulai. Tanpa langkah ini, ekstensi masih bisa dipasang tetapi beberapa fitur, terutama kompresi dan kebijakan berjadwal, tidak akan bekerja. Setelah server dimulai ulang, perintah CREATE EXTENSION timescaledb; dijalankan pada basis data target untuk membuat skema, tabel katalog, dan fungsi SQL yang menyusun hypertable.

Perintah berikut mengilustrasikan urutan itu. Perintah ini tidak dijalankan di sandbox karena membutuhkan Postgres hidup, sehingga hanya ditampilkan sebagai referensi sintaksis.

postgres Pemasangan ekstensi TimescaleDB 
-- di postgresql.conf
-- shared_preload_libraries = 'timescaledb'

-- pada basis data target, setelah server dimulai ulang
CREATE EXTENSION IF NOT EXISTS timescaledb;

-- verifikasi versi ekstensi yang terpasang
SELECT extversion FROM pg_extension WHERE extname = 'timescaledb';
text Keluaran 
extversion
2.19.3

Lapisan-lapisan yang dipasang#

Sebuah ekstensi Postgres modern memetakan tiga lapisan ke dalam direktori data Postgres. Skrip Python berikut tidak menjalankan SQL apa pun, tetapi memetakan struktur direktori dan objek yang dipasang oleh ekstensi TimescaleDB berdasarkan dokumentasi resmi. Skrip hanya mencetak peta tersebut, sehingga dapat dieksekusi tanpa server Postgres.

python peta_ekstensi.py 
"""Memetakan struktur ekstensi Postgres pada contoh TimescaleDB.

Skrip ini tidak menjalankan SQL. Tujuannya menggambarkan lapisan-lapisan
yang dipasang sebuah ekstensi Postgres modern: kontrol file, shared library,
skrip SQL instalasi, dan objek-objek katalog yang dibuat pada CREATE EXTENSION.
"""
from __future__ import annotations

EKSTENSI = {
    "nama": "timescaledb",
    "versi": "2.18.0",
    "control": {
        "direktori": "share/extension/",
        "file": "timescaledb.control",
        "isi": [
            "default_version = '2.18.0'",
            "module_pathname = '$libdir/timescaledb'",
            "relocatable = false",
            "shared_preload_libraries = 'timescaledb'",
        ],
    },
    "shared_library": {
        "direktori": "lib/",
        "file": "timescaledb.so",
        "hook": [
            "planner_hook",
            "executor_run_hook",
            "chunk_dispatch_hook",
        ],
    },
    "skrip_sql": ["timescaledb--2.18.0.sql"],
    "objek_dibuat": [
        "schema _timescaledb_catalog",
        "tabel _timescaledb_catalog.hypertable",
        "tabel _timescaledb_catalog.chunk",
        "fungsi create_hypertable(regclass, name)",
        "fungsi time_bucket(interval, timestamp)",
        "view timescaledb_information.hypertables",
    ],
}


def cetak_peta() -> None:
    print(f"ekstensi: {EKSTENSI['nama']} {EKSTENSI['versi']}")
    print()
    print("lapisan pemuatan:")
    print(f"  - {EKSTENSI['control']['direktori']}{EKSTENSI['control']['file']}")
    for baris in EKSTENSI["control"]["isi"]:
        print(f"      {baris}")
    print(f"  - {EKSTENSI['shared_library']['direktori']}{EKSTENSI['shared_library']['file']}")
    for hk in EKSTENSI["shared_library"]["hook"]:
        print(f"      hook: {hk}")
    print()
    print("skrip SQL instalasi:")
    for s in EKSTENSI["skrip_sql"]:
        print(f"  - {s}")
    print()
    print("objek yang dibuat pada CREATE EXTENSION:")
    for o in EKSTENSI["objek_dibuat"]:
        print(f"  - {o}")


if __name__ == "__main__":
    cetak_peta()
text Keluaran 
ekstensi: timescaledb 2.18.0

lapisan pemuatan:
  - share/extension/timescaledb.control
      default_version = '2.18.0'
      module_pathname = '$libdir/timescaledb'
      relocatable = false
      shared_preload_libraries = 'timescaledb'
  - lib/timescaledb.so
      hook: planner_hook
      hook: executor_run_hook
      hook: chunk_dispatch_hook

skrip SQL instalasi:
  - timescaledb--2.18.0.sql

objek yang dibuat pada CREATE EXTENSION:
  - schema _timescaledb_catalog
  - tabel _timescaledb_catalog.hypertable
  - tabel _timescaledb_catalog.chunk
  - fungsi create_hypertable(regclass, name)
  - fungsi time_bucket(interval, timestamp)
  - view timescaledb_information.hypertables

Peta di atas menunjukkan bahwa sebuah ekstensi tidak hanya berisi kode SQL. Control file adalah titik masuk yang dibaca Postgres saat CREATE EXTENSION dipanggil. Shared library memuat hook C yang dipasang pada planner dan executor, sehingga perintah seperti SELECT * FROM suhu_sensor dapat diarahkan ke chunk yang benar tanpa pengguna menyadarinya. Skrip SQL instalasi adalah deretan perintah CREATE FUNCTION, CREATE TABLE, dan CREATE VIEW yang membuat objek-objek katalog pada skema internal _timescaledb_catalog. Objek-objek inilah yang nantinya mendaftarkan hypertable, chunk, dan kebijakan yang menjadi inti modul ini.

Apa yang tidak berubah#

Sekali ekstensi terpasang, sebagian besar Postgres tetap sama. Driver klien seperti psycopg, JDBC, dan pgx tetap berjalan apa adanya, sebab protokol kawat Postgres tidak diubah. Tipe data standar, termasuk TIMESTAMPTZ, JSONB, UUID, dan array, tetap tersedia, demikian juga tipe data dari ekstensi lain seperti PostGIS. Indeks yang didukung Postgres, yaitu B-tree, GIN, GiST, BRIN, dan hash, dapat dipasang pada kolom hypertable. Window function, common table expression, dan LATERAL JOIN juga tetap berlaku pada hypertable tanpa sintaksis tambahan.

Hal yang sama berlaku pada fitur transaksional. Hypertable mendukung ACID penuh dan MVCC, sehingga BEGIN, COMMIT, serta ROLLBACK bekerja pada baris-baris di chunk. Backup dan restore dengan pg_dump serta point-in-time recovery dengan WAL tetap berfungsi, sebab ekstensi tidak mengganti format WAL. Yang berubah adalah cara penyimpanan di balik layar, yaitu satu tabel logis dipecah menjadi banyak chunk fisik, dan mekanisme pemecahan ini dibahas pada bagian berikutnya.

Versi dan migrasi ekstensi#

Versi ekstensi dinyatakan dalam control file dan dipasang pada system catalog pg_extension. Pemutakhiran versi minor, misalnya dari 2.17 ke 2.18, biasanya hanya memerlukan pemasangan shared library baru dan perintah ALTER EXTENSION timescaledb UPDATE TO '2.18.0'; tanpa memulai ulang server. Perintah itu menjalankan skrip pemutakhiran yang mengubah skema katalog bila perlu, dan biasanya selesai dalam hitungan detik pada basis data berukuran sedang. Pemutakhiran versi mayor, misalnya dari 1.7 ke 2.x, memerlukan penyesuaian shared_preload_libraries dan sering kali memerlukan migrasi data katalog, sehingga dokumentasi resmi menyediakan jalur terpisah dengan langkah pra dan pasca pemutakhiran.

Penurunan versi, atau downgrade, tidak didukung secara resmi, sebab skema katalog bisa berubah di antara versi. Bila downgrade benar-benar diperlukan, jalur yang aman adalah memulihkan basis data dari cadangan yang dibuat sebelum pemutakhiran. Karena itu, kebijakan pemutakhiran pada basis data produksi sebaiknya menyertakan cadangan penuh sebelum dan sesudah pemutakhiran, serta pengujian pada lingkungan staging yang meniru beban produksi. Verifikasi versi yang terpasang dapat dilakukan dengan SELECT extversion FROM pg_extension WHERE extname = 'timescaledb';, sehingga status pemutakhiran dapat dipantau secara otomatis.

Kesalahan umum#

  • Menganggap TimescaleDB adalah fork Postgres. Anggapan ini menyebabkan keputusan migrasi yang sebenarnya tidak perlu, sebab pemasangan hanya menambah ekstensi tanpa menggantikan binari.
  • Lupa mendaftar shared_preload_libraries sebelum menjalankan CREATE EXTENSION. Ekstensi terpasang tetapi fitur yang bergantung pada hook planner tidak aktif, sehingga gejalanya baru muncul saat kompresi atau kebijakan berjadwal diaktifkan.
  • Memasang ekstensi hanya pada basis data default, lalu heran tabel pada basis data lain tidak punya fitur hypertable. Pemasangan bersifat per basis data, bukan per server.

Ringkasan#

  • TimescaleDB adalah ekstensi Postgres yang dipasang dengan tiga lapisan, yaitu control file, shared library, dan skrip SQL instalasi.
  • Pemasangan memerlukan pendaftaran shared_preload_libraries di postgresql.conf sebelum CREATE EXTENSION dijalankan pada basis data target.
  • SQL, tipe data, indeks, dan driver klien Postgres tetap berlaku apa adanya pada hypertable yang diciptakan ekstensi ini.
  • Versi ekstensi diputakhirkan dengan ALTER EXTENSION ... UPDATE TO, sementara penurunan versi tidak didukung secara resmi.

Referensi#