Sql & Veritabanı İle Uygulamalar İçin Veri Sözlüğü Dokümantasyonu Nasıl Yapılır?

Gereksinimler ve Ön Hazırlık

Veri sözlüğü oluşturmaya başlamadan önce, projenizde kullandığınız veritabanı yönetim sisteminin (DBMS) meta veri (metadata) özelliklerine hakim olmanız gerekir. PostgreSQL, MySQL veya SQL Server gibi sistemler, kendi içlerinde bilgi şeması (information_schema) barındırır.

• PostgreSQL 16+ veya MySQL 8.4+ sürümü: Güncel özelliklerin kullanımı için önerilir.
• DBeaver veya DataGrip: Veritabanı şemalarını görselleştirmek ve analiz etmek için kullanılan profesyonel araçlar.
• Markdown veya Confluence: Dokümantasyonun barındırılacağı platform.
• SQL Bilgisi: Sistem tablolarından veri çekebilecek temel sorgulama yeteneği.

Adım 1: Veritabanı Şeması Analizi ve Meta Veri Toplama

Veri sözlüğünün temeli, veritabanının kendi içindeki meta verilerdir. `information_schema`, standart SQL ile veritabanı yapısını sorgulamanıza olanak tanır. İlk adım, tablolarınızın ve sütunlarınızın listesini otomatik olarak çekmektir.

SELECT 
    table_name, 
    column_name, 
    data_type, 
    is_nullable, 
    column_default
FROM information_schema.columns
WHERE table_schema = 'public'
ORDER BY table_name, ordinal_position;

Bu sorgu, veritabanınızdaki tüm sütunların teknik özelliklerini listeleyerek dokümantasyonunuzun ham verisini oluşturur. Bu veriyi bir Excel veya CSV dosyasına aktararak sözlüğünüzü oluşturmaya başlayabilirsiniz.

Adım 2: Veri Sözlüğü Standartlarını Belirleme

Etkili bir veri sözlüğü, sadece teknik veri tiplerini değil, iş mantığını da içermelidir. Dokümantasyonunuzda her sütun için şu başlıkları bulundurmalısınız: Sütun Adı, Veri Tipi, Zorunluluk (Nullable), Varsayılan Değer, İş Mantığı Açıklaması ve İlişkili Tablo.

Adım 3: SQL Yorum Satırları (Comments) ile Dokümantasyon

2026 yılı standartlarında en iyi pratik, dokümantasyonu veritabanının içine gömmektir. SQL'in COMMENT ON komutu, sütun açıklamalarını doğrudan veritabanı nesnesine eklemenizi sağlar. Bu, veritabanı yöneticilerinin ve geliştiricilerin, tabloyu sorgularken açıklamayı görmesini sağlar.

COMMENT ON TABLE users IS 'Kullanıcıların kimlik ve profil bilgilerini tutar.';
COMMENT ON COLUMN users.email IS 'Kullanıcının giriş yaptığı benzersiz e-posta adresi.';
COMMENT ON COLUMN users.created_at IS 'Hesabın oluşturulma zaman damgası (UTC).';

Bu yöntem, dokümantasyonun kodla birlikte yaşamasını sağlar. Veritabanı şeması değiştiğinde, yorumu da aynı SQL dosyası içinde güncelleyebilirsiniz.

Adım 4: İlişkisel Veritabanı Diyagramları ve Görselleştirme

Veri sözlüğü sadece metin değildir; tablolar arasındaki ilişkiler (Foreign Keys) de dokümante edilmelidir. ER (Entity-Relationship) diyagramları, verinin akışını anlamak için kritiktir. Mermaid.js gibi araçlar, kod tabanlı diyagramlar oluşturmanıza olanak tanır.

erDiagram
    USERS ||--o{ ORDERS : "verir"
    USERS {
        int id
        string email
        string password_hash
    }
    ORDERS {
        int id
        int user_id
        decimal amount
    }

Bu diyagram, veri sözlüğünüzün görsel bir özetidir. Teknik olmayan paydaşların veritabanı yapısını anlamasına yardımcı olur.

Adım 5: Güvenlik ve Hassas Veri İşaretleme

Veri sözlüğünde en kritik konulardan biri, hangi verilerin kişisel veri (KVKK/GDPR) veya hassas veri (şifre, kredi kartı) olduğunun işaretlenmesidir. Bu, güvenlik denetimleri sırasında büyük kolaylık sağlar.

-- Hassas verileri etiketlemek için özel bir tablo oluşturulabilir
CREATE TABLE data_classification (
    table_name VARCHAR(100),
    column_name VARCHAR(100),
    sensitivity_level VARCHAR(20) -- 'Public', 'Internal', 'Confidential'
);

INSERT INTO data_classification VALUES ('users', 'password_hash', 'Confidential');

Kritik Uyarı: Veri sözlüğünüzü asla halka açık bir repository üzerinde şifreler, API anahtarları veya gerçek kullanıcı verileriyle birlikte yayınlamayın. Dokümantasyonunuzda sadece veri yapısını belirtin, gerçek veriyi asla dahil etmeyin.

Adım 6: Dokümantasyonu Otomatikleştirme (CI/CD Entegrasyonu)

Dokümantasyonun güncel kalması için CI/CD süreçlerine "schema-spy" veya benzeri araçları dahil etmelisiniz. Bu araçlar, her başarılı veritabanı migrasyonundan sonra veri sözlüğünü otomatik olarak güncelleyerek HTML formatında yayınlar.

# Örnek bir CI/CD adımı (Bash script)
./schemaspy -t pgsql -db my_database -host localhost -u user -p password -o ./docs/db

Bu komut, veritabanınızdan anlık bir snapshot alarak güncel veri sözlüğünü dokümantasyon klasörünüze çıkarır.

Sıkça Sorulan Sorular

Veri sözlüğü ne sıklıkla güncellenmelidir?

Veritabanı şemasında her değişiklik yapıldığında (Migration işlemi sırasında) veri sözlüğü de güncellenmelidir. Otomatik araçlar kullanıyorsanız, bu süreci CI/CD hattına bağlayarak manuel iş yükünü sıfırlayabilirsiniz.

SQL yorumlarını (comments) herkes görebilir mi?

Evet, veritabanı üzerinde okuma yetkisi olan herkes information_schema üzerinden bu yorumları görebilir. Bu nedenle hassas bilgileri (şifreler, anahtarlar) yorum satırlarına yazmamaya özen gösterin.

Veri sözlüğü için Excel mi yoksa veritabanı içi dokümantasyon mu daha iyi?

Veritabanı içi dokümantasyon (SQL yorumları) her zaman daha iyidir çünkü kodla birlikte versiyonlanır. Excel dosyaları zamanla güncelliğini yitirir ve "senkronizasyon hatası" yaşanmasına neden olur.

Veri tiplerini dokümante ederken nelere dikkat etmeliyim?

Veri tipinin yanı sıra, o sütunun aldığı değer aralığını (constraints) ve karakter seti (collation) gibi detayları da belirtmek, veritabanı performansını optimize etmek isteyen geliştiriciler için hayat kurtarıcıdır.

Küçük projelerde veri sözlüğü şart mı?

Proje ne kadar küçük olursa olsun, en azından tablo ve sütun açıklamalarını içeren bir Markdown dosyası tutmak, projenin gelecekteki bakım süreçlerini %50 oranında hızlandırır.

İleri Seviye İpucu: Veri Sözlüğünü Kod Tabanı ile Senkronize Etme

Veri sözlüğünün veritabanı içerisinde kalması harikadır, ancak uygulama katmanındaki (Backend/ORM) modellerle uyumsuz olması "drift" (sapma) sorununa yol açar. Modern yazılım geliştirme süreçlerinde, veritabanı şemasındaki değişiklikleri kod tarafındaki dokümantasyonla eşitlemek için "Schema-as-Code" yaklaşımını benimsemelisiniz.

Örneğin, bir Entity Framework veya SQLAlchemy modeli kullanıyorsanız, veritabanı yorumlarını kod içerisindeki özniteliklere (attributes) bağlayarak dokümantasyonu kodun bir parçası haline getirebilirsiniz. Aşağıda, Python SQLAlchemy ile bir modelin dokümante edilmesine dair örnek bir yapı bulunmaktadır:

from sqlalchemy import Column, Integer, String
from sqlalchemy.orm import declarative_base

Base = declarative_base()

class Kullanici(Base):
    __tablename__ = 'kullanicilar'
    __table_args__ = {'comment': 'Sisteme kayıtlı tüm kullanıcıların ana tablosu.'}

    id = Column(Integer, primary_key=True, comment='Benzersiz kullanıcı kimlik numarası.')
    email = Column(String(255), nullable=False, comment='Kullanıcının giriş yaparken kullandığı e-posta adresi.')
    
    # Bu yapı, veritabanı göçleri (migrations) sırasında 
    # otomatik olarak SQL yorumlarına dönüştürülür.

Veri Sözlüğü ile Performans Analizi ve Optimizasyon

Veri sözlüğü sadece sütun isimlerini açıklamaz; aynı zamanda performans darboğazlarını tespit etmek için bir harita görevi görür. Dokümantasyonunuzda her tablo için "Kullanım Sıklığı" ve "İndeksleme Stratejisi" gibi özel alanlar bulundurmak, veritabanı yöneticilerinin (DBA) işini büyük ölçüde kolaylaştırır.

Aşağıdaki tablo, veri sözlüğünüze ekleyebileceğiniz performans odaklı bir dokümantasyon şablonunu göstermektedir:

İpucu: Eğer bir sütun üzerinde çok sayıda JOIN işlemi yapılıyorsa, veri sözlüğünüzde bu sütunu "Performans Kritik" olarak işaretleyin. Bu işaretleme, gelecekteki veritabanı refactoring süreçlerinde hangi sütunların indekslenmesi gerektiğini hatırlamanızı sağlar.

Hata Ayıklama Süreçlerinde Veri Sözlüğünün Rolü

Karmaşık bir hata ile karşılaştığınızda, veritabanı şemasını anlamak için saatler harcamak yerine, güncel bir veri sözlüğü üzerinden verinin akışını (data lineage) takip edebilirsiniz. Özellikle NULL değerlerin neden olduğu hataları ayıklarken, veri sözlüğündeki nullable kısıtlamaları ve varsayılan değer açıklamaları, sorunun kaynağını saniyeler içinde bulmanıza yardımcı olur.

Veritabanı üzerinde hata ayıklama yaparken şu sorguyu kullanarak dokümantasyonunuzun güncelliğini kontrol edebilirsiniz:

-- Dokümantasyonu eksik olan sütunları listeleyen sorgu
SELECT 
    table_name, 
    column_name 
FROM 
    information_schema.columns 
WHERE 
    table_schema = 'public' 
    AND column_comment IS NULL;

Bu sorgu, projenizin hangi bölümlerinde dokümantasyon açığı olduğunu size raporlar. Bu raporu düzenli olarak CI/CD süreçlerinize dahil ederek, "dokümante edilmemiş kod" kuralını bir kalite standardı haline getirebilirsiniz.

Sonuç

Veri sözlüğü dokümantasyonu, SQL & veritabanı projelerinin sürdürülebilirliği için bir lüks değil, zorunluluktur. Bu rehberde öğrendiğiniz information_schema kullanımı, SQL yorumları ve otomatik araçlar, veritabanı yönetimindeki profesyonelliğinizi bir üst seviyeye taşıyacaktır. Bir sonraki adım olarak, mevcut projenizdeki tüm tabloları kapsayan bir "Veri Sözlüğü Markdown" dosyası oluşturmayı deneyin ve bunu ekip arkadaşlarınızla paylaşarak geri bildirim alın.

Yasal Sorumluluk Reddi: Bu makalede paylaşılan kod örnekleri eğitim amaçlıdır. Üretim ortamlarında (Production) çalıştırmadan önce mutlaka yedek alınız. SQL injection ve diğer güvenlik açıklarına karşı her zaman parametreli sorgular (prepared statements) kullanınız.