Kembali ke semua panduan
Desain Basis DataยทยทWaktu baca 3 menit

Dokumentasi basis data: jelaskan skema SQL dengan ERD

Dokumentasikan skema basis data dengan ERD, contoh SQL, catatan relasi, dan konteks migrasi agar tim dapat memahami model data lebih cepat.

Diagram pelanggan-ke-pesanan di samping catatan yang menjelaskan kunci asing dan aturan bisnis
Dalam panduan ini
  1. Mengapa Dokumentasi Basis Data Gagal
  2. Apa yang harus disertakan dalam Dokumentasi Skema
  3. Blok Dokumentasi Contoh
  4. Alur Kerja Dokumentasi Praktis
  5. Referensi dan bacaan lebih lanjut

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.

Skema SQL, diagram ERD, catatan relasi, dan konteks migrasi digabungkan ke dalam dokumentasi
Dokumentasi basis data yang kuat memasangkan sumber SQL dengan ERD dan catatan hubungan singkat, sehingga dokumen tetap praktis.

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.

Referensi dan bacaan lebih lanjut

Kiriman Lainnya