Komentar dalam SQL

Query yang kita tulis hari ini sering harus dibaca ulang bulan depan — oleh rekan kerja, atau oleh diri kita sendiri yang sudah lupa konteksnya. Komentar adalah cara menulis catatan di dalam kode SQL tanpa memengaruhi jalannya query: server membaca lalu membuang teks komentar sebelum mengeksekusi statement. Pada Chapter ini kita akan memakai tiga gaya komentar yang didukung MySQL, membongkar satu jebakan penulisan yang bisa mengubah arti perintah, dan melihat bagaimana komentar ikut tersimpan di dalam objek database.

Menyiapkan Tabel Latihan #

Contoh-contoh kita akan mendokumentasikan query nyata, jadi kita siapkan dulu tabel produk di database latihan belajar_sql:

CREATE DATABASE belajar_sql;
USE belajar_sql;
CREATE TABLE produk (
  id INT,
  nama VARCHAR(100),
  harga INT
);
INSERT INTO produk (id, nama, harga) VALUES
  (1, 'Buku Tulis', 4000),
  (2, 'Pulpen Hitam', 15000),
  (3, 'Tip Ex', 8000);

Output yang Dihasilkan:

Query OK, 1 row affected (0.00 sec)

Database changed
Query OK, 0 rows affected (0.00 sec)

Query OK, 3 rows affected (0.00 sec)
Records: 3  Duplicates: 0  Warnings: 0

Komentar Satu Baris dengan – #

Gaya komentar paling umum diawali dua tanda minus -- diikuti satu spasi, lalu teks komentar sampai akhir baris:

-- Mengambil seluruh produk dari tabel produk
SELECT nama, harga FROM produk;

Output yang Dihasilkan:

Query OK, 0 rows affected (0.00 sec)

+--------------+-------+
| nama         | harga |
+--------------+-------+
| Buku Tulis   |  4000 |
| Pulpen Hitam | 15000 |
| Tip Ex       |  8000 |
+--------------+-------+
3 rows in set (0.00 sec)

Baris komentar diabaikan server: hasil yang muncul murni berasal dari statement SELECT. Teks setelah -- boleh berisi apa saja — catatan niat, penjelasan filter, sampai tautan dokumentasi — karena seluruhnya dibuang saat parsing.

Komentar pada Akhir Baris #

Komentar juga bisa menempel pada akhir baris statement. Bentuk ini cocok untuk menjelaskan bagian spesifik dari query yang panjang:

SELECT nama, harga FROM produk; -- kolom yang ditampilkan

Output yang Dihasilkan:

+--------------+-------+
| nama         | harga |
+--------------+-------+
| Buku Tulis   |  4000 |
| Pulpen Hitam | 15000 |
| Tip Ex       |  8000 |
+--------------+-------+
3 rows in set (0.00 sec)

Karena tanda titik koma sudah menutup statement, teks setelahnya sepenuhnya menjadi milik komentar. Server menerima statement yang bersih; catatan kita tetap ikut tersimpan di file skrip. Gaya # bisa dipakai di posisi yang sama dengan cara yang persis identik.

Komentar Gaya MySQL dengan #

MySQL menambahkan gaya khusus: komentar satu baris yang diawali tanda pagar #. Perilakunya sama dengan --, baik sebagai baris tersendiri maupun pada akhir baris. Ada satu perbedaan aturan yang menguntungkan: # tidak mewajibkan spasi setelahnya, sehingga bentuk berikut sah dan bebas dari jebakan --:

#Urutkan produk dari harga termahal
SELECT nama, harga FROM produk ORDER BY harga DESC;

Output yang Dihasilkan:

Query OK, 0 rows affected (0.00 sec)

+--------------+-------+
| nama         | harga |
+--------------+-------+
| Pulpen Hitam | 15000 |
| Tip Ex       |  8000 |
| Buku Tulis   |  4000 |
+--------------+-------+
3 rows in set (0.00 sec)

Karena # adalah ekstensi MySQL, komentar ini tidak dikenal sebagian besar database lain. Untuk skrip yang mungkin dijalankan lintas database — misalnya skrip migrasi yang diuji di MySQL lalu dipindah ke PostgreSQL — kita sebaiknya memilih -- yang menjadi bagian standar SQL.

Komentar Blok dengan /* */ #

Komentar blok dibuka dengan /* dan ditutup dengan */, sehingga teks di antaranya bisa membentang beberapa baris sekaligus:

-- @notest
/* Blok komentar dapat membentang
   ke beberapa baris sekaligus.
   Seluruh teks ini diabaikan server. */
SELECT nama, harga FROM produk ORDER BY harga;

Output yang Dihasilkan:

+--------------+-------+
| nama         | harga |
+--------------+-------+
| Buku Tulis   |  4000 |
| Tip Ex       |  8000 |
| Pulpen Hitam | 15000 |
+--------------+-------+
3 rows in set (0.00 sec)

Bentuk panjangnya berguna untuk kepala dokumen: penjelasan tujuan skrip, riwayat perubahan, atau instruksi pemakaian. Komentar blok juga bisa diletakkan di tengah statement untuk menjelaskan bagian yang tidak biasa:

SELECT /* daftar kolom */ nama, harga FROM produk;

Output yang Dihasilkan:

+--------------+-------+
| nama         | harga |
+--------------+-------+
| Buku Tulis   |  4000 |
| Pulpen Hitam | 15000 |
| Tip Ex       |  8000 |
+--------------+-------+
3 rows in set (0.00 sec)

Posisi komentar di tengah statement membuktikan bahwa parser membuang komentar lebih dulu, lalu membaca statement yang tersisa seolah komentar tidak pernah ada.

Jebakan: – Tanpa Spasi #

Aturan satu spasi setelah -- bukan formalitas. Tanpa spasi, tanda -- tidak dianggap komentar dan justru dibaca sebagai dua operator pengurangan yang berurutan:

SELECT 1 --1;

Output yang Dihasilkan:

+-------+
| 1 --1 |
+-------+
|     2 |
+-------+
1 row in set (0.00 sec)

Statement di atas menghasilkan nilai 2 — server membacanya sebagai 1 - (-1), yaitu satu dikurang minus satu. Query yang kita kira berkomentar ternyata berhitung. Varian --teks berakhir lebih gaduh lagi: server mencoba membaca teks sebagai nama kolom dan membalas dengan galat Unknown column.

Komentar pada Objek yang Disimpan #

Sejauh ini komentar kita hidup di file skrip dan sesi terminal. Bagaimana dengan kode yang disimpan di dalam server — stored procedure, function, dan trigger? MySQL menyimpan body objek tersebut apa adanya, termasuk komentarnya, sehingga komentar yang kita tulis di dalam body tetap terbaca kembali ketika struktur objek diperiksa dengan SHOW CREATE PROCEDURE atau SHOW CREATE FUNCTION.

Ada satu variasi khusus yang perlu kita kenali agar tidak terkejut: komentar blok dengan tanda seru /*! ... */. MySQL mengeksekusi isi komentar ini, sementara database lain mengabaikannya — kelak kita akan menjumpainya pada hasil mysqldump berupa baris seperti /*!40101 SET ... */ yang menjaga dump tetap kompatibel saat dipulihkan di server MySQL lain. Perilaku objek tersimpan ini akan kita praktikkan tuntas pada Section Stored Programs.

Referensi #

• Comments — MySQL 8.4 Reference Manual
• SQL Statements — MySQL 8.4 Reference Manual

Dengan tiga gaya komentar, kita bisa menjaga setiap query tetap terdokumentasi sejak hari pertama. Dasar SQL kita kini lengkap: statement bisa dibuat, dipilih, diinspeksi, dihapus, dan didokumentasikan. Section berikutnya menaikkan ketelitian satu tingkat — kita akan membedah tipe data satu per satu, mulai dari INT hingga DECIMAL, supaya setiap kolom menyimpan data dengan tepat.