Komentar dalam SQL

Query yang jelas hari ini bisa jadi teka-teki enam bulan kemudian — dan query yang ditulis orang lain sering mustahil dibaca tanpa penjelasan. SQL menyediakan dua mekanisme dokumentasi untuk dua kebutuhan yang berbeda: komentar dalam kode (-- dan /* ... */) yang menjelaskan isi file query kita, dan COMMENT ON yang menyimpan dokumentasi pada objek database itu sendiri sehingga terbaca oleh siapa pun yang memeriksa strukturnya. Pada chapter penutup section ini kita mempraktikkan keduanya dan membiasakan satu kebiasaan yang membedakan proyek yang sehat: mendokumentasikan mengapa, bukan sekadar apa.

Komentar Satu Baris dengan – #

Dua tanda minus berurutan (--) memulai komentar yang berlaku sampai akhir baris: server membaca teks sesudahnya sebagai angin lalu — bisa berupa catatan, penjelasan, atau perintah yang sengaja dinonaktifkan:

-- File latihan komentar satu baris.
-- Semua baris diawali dua tanda minus, dan semuanya diabaikan server.

SELECT 'belajar SQL' AS pesan;  -- komentar juga bisa menempel di akhir baris

-- Baris di bawah ini tadinya perintah aktif, kini dinonaktifkan:
-- SELECT 'perintah ini tidak dijalankan';

SELECT 'harga -- diskon' AS catatan;

Output yang Dihasilkan:

    pesan    
-------------
 belajar SQL
(1 row)

     catatan     
-----------------
 harga -- diskon
(1 row)

Tiga bentuk sekaligus terlihat di file tersebut: komentar yang mengawali baris (baris-baris pembuka), komentar yang menempel setelah perintah aktif (baris SELECT ... AS pesan;), dan perintah yang “dimatikan” dengan dijadikan komentar (SELECT 'perintah ini tidak dijalankan';). Perhatikan pula hasil terakhir: teks 'harga -- diskon' tetap utuh masuk database karena berada di dalam string literal — parser membaca tanda -- hanya ketika berada di luar kutip satu. Dua tanda minus di dalam teks berkutip bukanlah komentar.

Kebiasaan mematikan perintah dengan -- sangat berguna saat bereksperimen: saat menyelidiki kenapa hasil query janggal, kita menonaktifkan satu baris demi satu baris tanpa menghapusnya, lalu menyalakannya kembali dengan menghapus dua tanda minus itu.

Komentar Blok dengan /* … */ #

Komentar blok dibuka dengan /* dan ditutup */, dan segala sesuatu di antaranya diabaikan — sepanjang beberapa baris sekaligus, atau persis di tengah perintah:

/* Komentar blok bisa mencakup beberapa baris sekaligus,
   termasuk baris kosong dan hampir semua karakter di dalamnya. */

SELECT /* komentar di tengah perintah */ 'Toko Maju Jaya' AS nama_toko;

/* Di PostgreSQL, komentar blok bahkan bisa bersarang:
   /* komentar di dalam komentar */
   dan bagian ini masih milik komentar terluar. */
SELECT 'tes' AS hasil;

Output yang Dihasilkan:

   nama_toko    
----------------
 Toko Maju Jaya
(1 row)

 hasil 
-------
 tes
(1 row)

Dua perintah SELECT berjalan normal seolah komentarnya tidak ada. Satu perilaku di file itu khas PostgreSQL: komentar blok boleh bersarang — /* di dalam komentar blok harus ditutup */-nya sendiri sebelum komentar terluar berakhir. Standar SQL tidak menjanjikan hal ini dan beberapa database lain menolaknya, jadi bersarang berguna di PostgreSQL tapi jangan diandalkan bila script kita harus portabel. Komentar blok paling sering dipakai untuk menonaktifkan sekaligus beberapa baris perintah yang berkaitan — tugas yang melelahkan bila dikerjakan -- satu per satu.

COMMENT ON: Komentar yang Ikut Disimpan #

Kedua jenis komentar di atas hidup hanya di file atau ketikan kita — database tidak menyimpannya. Padahal tabel juga perlu dokumentasi: apa isi kolom nama, kenapa kolom email ada dua kali di dua schema, siapa pemilik data ini. Perintah COMMENT ON menjawabnya dengan menyimpan deskripsi langsung ke catalog database, terpasang pada objek yang didokumentasikan:

CREATE TABLE pelanggan (
    id    integer PRIMARY KEY,
    nama  text NOT NULL,
    email text UNIQUE
);

COMMENT ON TABLE pelanggan IS 'Data pelanggan Toko Maju Jaya';

COMMENT ON COLUMN pelanggan.nama IS 'Nama lengkap pelanggan';

COMMENT ON COLUMN pelanggan.email IS 'Alamat email untuk mengirim struk';

\d+ pelanggan

\dt+

Output yang Dihasilkan:

CREATE TABLE
COMMENT
COMMENT
COMMENT
                                                   Table "public.pelanggan"
 Column |  Type   | Collation | Nullable | Default | Storage  | Compression | Stats target |            Description            
--------+---------+-----------+----------+---------+----------+-------------+--------------+-----------------------------------
 id     | integer |           | not null |         | plain    |             |              | 
 nama   | text    |           | not null |         | extended |             |              | Nama lengkap pelanggan
 email  | text    |           |          |         | extended |             |              | Alamat email untuk mengirim struk
Indexes:
    "pelanggan_pkey" PRIMARY KEY, btree (id)
    "pelanggan_email_key" UNIQUE CONSTRAINT, btree (email)
Access method: heap

                                                List of relations
 Schema |   Name    | Type  |  Owner   | Persistence | Access method |    Size    |          Description          
--------+-----------+-------+----------+-------------+---------------+------------+-------------------------------
 public | pelanggan | table | postgres | permanent   | heap          | 8192 bytes | Data pelanggan Toko Maju Jaya
(1 row)

Mari kita bedah hasilnya:

1. \d+ pelanggan memperlihatkan kolom Description yang kini terisi: nama menjelaskan dirinya sebagai Nama lengkap pelanggan, email sebagai Alamat email untuk mengirim struk. Kolom tanpa COMMENT ON (id) membiarkan barisnya kosong.
2. \dt+ — varian diperluas dari \dt yang kita kenal di chapter Melihat Struktur Tabel — menampilkan kolom Description pada daftar tabel, dan di situ muncul komentar tabelnya: Data pelanggan Toko Maju Jaya.
3. COMMENT ON adalah perintah SQL biasa, bukan meta-command: bisa masuk file script, ikut tereksekusi bersama CREATE TABLE saat setup database baru, dan terlihat oleh rekan satu tim tanpa perlu membuka file asal kita.

Mengganti komentar cukup menjalankan COMMENT ON lagi dengan teks baru, dan COMMENT ON TABLE pelanggan IS NULL menghapusnya.

Dua Jenis Komentar, Dua Rumah #

Keduanya bukan pesaing: script pembuatan tabel yang baik memakai -- untuk menjelaskan langkah-langkahnya dan COMMENT ON untuk meninggalkan dokumentasi yang menempel pada tabel selama tabel itu hidup.

Section Dasar SQL sampai di sini lengkap: kita mengenal tata bahasa SQL, membuat database dan schema, berpindah antar koneksi, mendefinisikan tabel, memeriksa strukturnya, mengubahnya, membersihkannya, dan mendokumentasikannya. Fondasi struktur sudah berdiri. Babak berikutnya masuk ke bahan bangunannya sendiri: tipe data — mulai dari integer yang setia menghitung sampai numeric yang menjaga rupiah kita tetap presisi — dibuka oleh chapter Integer di Section Tipe Data.

Referensi #

• COMMENT Reference
• SQL Syntax: Comments
• psql Reference

CREATE TABLE pelanggan (
    id    integer PRIMARY KEY,
    nama  text NOT NULL,
    email text UNIQUE
);

COMMENT ON TABLE pelanggan IS 'Data pelanggan Toko Maju Jaya';

COMMENT ON COLUMN pelanggan.nama IS 'Nama lengkap pelanggan';

COMMENT ON COLUMN pelanggan.email IS 'Alamat email untuk mengirim struk';

\d+ pelanggan

\dt+

-- File latihan komentar satu baris.
-- Semua baris diawali dua tanda minus, dan semuanya diabaikan server.

SELECT 'belajar SQL' AS pesan;  -- komentar juga bisa menempel di akhir baris

-- Baris di bawah ini tadinya perintah aktif, kini dinonaktifkan:
-- SELECT 'perintah ini tidak dijalankan';

SELECT 'harga -- diskon' AS catatan;

/* Komentar blok bisa mencakup beberapa baris sekaligus,
   termasuk baris kosong dan hampir semua karakter di dalamnya. */

SELECT /* komentar di tengah perintah */ 'Toko Maju Jaya' AS nama_toko;

/* Di PostgreSQL, komentar blok bahkan bisa bersarang:
   /* komentar di dalam komentar */
   dan bagian ini masih milik komentar terluar. */
SELECT 'tes' AS hasil;