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.
Ş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.



