Tüm kılavuzlara geri dön
Veritabanı Tasarımı··3 dakikalık okuma

Veritabanı belgeleme: SQL şemanızı ERD ile açıklama

Ekiplerin veri modellerini daha hızlı anlayabilmesi için veritabanı şemalarını ERD'ler, SQL örnekleri, ilişki notları ve geçiş bağlamı ile belgeleyin.

Yabancı anahtarı ve iş kuralını açıklayan notların yanında bir müşteri-sipariş diyagramı
Bu kılavuzda
  1. Veritabanı Dokümantasyonu Neden Başarısız Olur
  2. Şema Dokümantasyonuna Neler Dahil Edilmeli
  3. Örnek Dokümantasyon Bloğu
  4. Pratik Bir Dokümantasyon İş Akışı
  5. Referanslar ve daha fazla okuma

SQL örnekleri, başka bir lehçe belirtilmedikçe PostgreSQL kullanır. Kısa kod parçacıkları, referans verilen tabloların zaten var olduğunu varsayar. DDL'yi uygulamadan önce hedef veritabanınızda doğrulayın.

Veritabanı Dokümantasyonu Neden Başarısız Olur

Veritabanı belgeleri genellikle şemadan ayrı yazıldığı için güncelliğini yitirir. Birisi ilk tasarım sprinti sırasında bir diyagram oluşturur, veritabanı altı ay boyunca değişir ve belgeler sessizce yanıltıcı hale gelir.

Daha iyi bir yaklaşım, dokümantasyonu SQL kaynağına yakın tutmaktır. DDL'den diyagramlar oluşturun, tablolar ve ilişkiler için kısa açıklamalar ekleyin ve şema her değiştiğinde belgeleri güncelleyin.

Belgelendirme içinde birleştirilmiş SQL şeması, ERD diyagramı, ilişki notları ve geçiş bağlamı
Güçlü veritabanı dokümantasyonu, SQL kaynağını bir ERD ve kısa ilişki notlarıyla eşleştirir, böylece belgeler pratik kalır.

Şema Dokümantasyonuna Neler Dahil Edilmeli

Faydalı veritabanı belgeleri, geliştiricilerin özellikler oluştururken ve üretim verilerinde hata ayıklarken gerçekten sordukları soruları yanıtlar.

  • Bir ERD. Tabloları, birincil anahtarları, yabancı anahtarları ve ana ilişki yollarını gösterin.
  • Tablo amaç notları. Her ana tablonun neden var olduğunu ve hangi özelliğin ona sahip olduğunu açıklayın.
  • İlişki kuralları. Kardinaliteyi, isteğe bağlı ilişkileri ve basamaklı eylemleri belirtin.
  • Önemli kısıtlamalar. Benzersiz anahtarları, kontrolleri, enum değerlerini ve SQL tarafından uygulanan iş kurallarını belgeleyin.
  • Geçiş bağlamı. Şema değişikliklerini, arkalarındaki özellik, hata düzeltme veya operasyonel nedenlerle ilişkilendirin.

Örnek Dokümantasyon Bloğu

Hafif bir dokümantasyon girişi, SQL'i sade dildeki notlarla eşleştirebilir:

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()
);

Dokümantasyon notları şöyle olabilir: bir hesabın birçok faturası vardır, faturaların birçok ödeme kaydı vardır ve bir test faturası silinirse ödeme satırları silinir. Denetim gereksinimleri olan üretim sistemlerinde, kademeli silmeleri kısıtlı silmeler ve arşiv kayıtları ile değiştirebilirsiniz.

Pratik Bir Dokümantasyon İş Akışı

İşte belgeleri tam zamanlı bir işe dönüştürmeden yararlı tutan bir iş akışı.

  • SQL şemasıyla başlayın ve şurada bir ERD oluşturun: Erd Go düzenleyici.
  • Diyagramı dışa aktarın veya oturum açın, kaydedin ve şema genel erişim için uygun olduğunda salt okunur bir genel bağlantı paylaşın. Özel dokümantasyon için resim dışa aktarmalarını kullanın.
  • Her önemli tablo kümesi için bir kısa paragraf ekleyin: auth, billing, orders, content, audit veya reporting.
  • Belgelerin değişenleri yansıtması için migrasyonlar sırasında güncellenmiş SQL'den ERD'yi yeniden oluşturun.
  • Sözdizimi örneklerini şununla senkronize tutun: Erd Go DDL dokümantasyonu böylece gelecekteki katkıda bulunanlar diyagramı yeniden oluşturabilir.

Amaç mükemmel bir ansiklopedi değildir. Amaç, insanların veritabanını hızlı bir şekilde anlamalarına ve okuduklarına güvenmelerine yardımcı olan yaşayan bir haritadır.

Referanslar ve daha fazla okuma

Daha Fazla Yazı