Contoh SQL menggunakan PostgreSQL kecuali dialek lain disebutkan. Cuplikan singkat mengasumsikan tabel yang direferensikan sudah ada. Validasi DDL di basis data target Anda sebelum menerapkannya.
Mengapa Dokumentasi Basis Data Gagal
Dokumentasi database seringkali menjadi usang karena ditulis terpisah dari skema. Seseorang membuat diagram selama sprint desain pertama, database berubah selama enam bulan, dan dokumentasi diam-diam menjadi menyesatkan.
Pendekatan yang lebih baik adalah menjaga dokumentasi tetap dekat dengan sumber SQL. Hasilkan diagram dari DDL, tambahkan penjelasan singkat untuk tabel dan relasi, dan perbarui dokumentasi setiap kali skema berubah.
Apa yang harus disertakan dalam Dokumentasi Skema
Dokumentasi database yang berguna menjawab pertanyaan yang benar-benar ditanyakan oleh pengembang saat membangun fitur dan men-debug data produksi.
- Sebuah ERD. Tampilkan tabel, kunci utama, kunci asing, dan jalur hubungan utama.
- Catatan tujuan tabel. Jelaskan mengapa setiap tabel utama ada dan fitur mana yang memilikinya.
- Aturan relasi. Sebutkan kardinalitas, relasi opsional, dan aksi cascading.
- Batasan penting. Dokumentasikan kunci unik, pemeriksaan, nilai enum, dan aturan bisnis yang diberlakukan oleh SQL.
- Konteks migrasi. Tautkan perubahan skema ke fitur, perbaikan bug, atau alasan operasional di baliknya.
Blok Dokumentasi Contoh
Entri dokumentasi yang ringan dapat memasangkan SQL dengan catatan bahasa biasa:
CREATE TABLE accounts (
id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
name TEXT NOT NULL
);
CREATE TABLE invoices (
id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
account_id BIGINT NOT NULL REFERENCES accounts (id),
status VARCHAR(30) NOT NULL DEFAULT 'draft',
total NUMERIC(12, 2) NOT NULL CHECK (total >= 0),
due_date DATE,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE invoice_payments (
id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
invoice_id BIGINT NOT NULL REFERENCES invoices (id) ON DELETE CASCADE,
amount NUMERIC(12, 2) NOT NULL CHECK (amount > 0),
paid_at TIMESTAMPTZ NOT NULL DEFAULT now()
);Catatan dokumentasi mungkin menyatakan: sebuah akun memiliki banyak faktur, faktur memiliki banyak catatan pembayaran, dan baris pembayaran dihapus jika faktur uji dihapus. Dalam sistem produksi dengan persyaratan audit, Anda mungkin mengganti penghapusan berjenjang dengan penghapusan terbatas dan catatan pengarsipan.
Alur Kerja Dokumentasi Praktis
Berikut adalah alur kerja yang menjaga dokumen tetap berguna tanpa mengubah dokumentasi menjadi pekerjaan penuh waktu.
- Mulai dengan skema SQL dan buat ERD di Editor Erd Go.
- Ekspor diagram atau masuk, simpan, dan bagikan tautan publik hanya-baca ketika skema sesuai untuk akses publik. Gunakan ekspor gambar untuk dokumentasi pribadi.
- Tambahkan satu paragraf pendek untuk setiap kluster tabel penting: auth, penagihan (billing), pesanan (orders), konten, audit, atau pelaporan (reporting).
- Buat ulang ERD dari SQL yang diperbarui selama migrasi agar dokumentasi mencerminkan apa yang berubah.
- Jaga agar contoh sintaks tetap sinkron dengan Dokumentasi DDL Erd Go sehingga kontributor di masa mendatang dapat mereproduksi diagram tersebut.
Tujuannya bukanlah ensiklopedia yang sempurna. Tujuannya adalah peta hidup yang membantu orang memahami basis data dengan cepat dan memercayai apa yang mereka baca.



