Kısım II · İnşaat · Bölüm 39

Postgres Pratikte

PostgreSQL in practice

1. Kat 10Bizim uygulamamızGo sunucusu (depo katmanı) ve Postgres: puanlar, cevaplar, kullanıcılar kalıcı olarak burada durur. Bu bölümün işi.
2. Kat 8AğGo süreci ile Postgres süreci TCP ile konuşur; bağlantı kurmak ağ gidiş gelişi demektir (bkz. Bölüm 19). Bu yüzden bağlantı havuzu var.
3. Kat 7İşletim sistemiPostgres sıradan bir süreçtir; verisini dosyalara yazar (bkz. Bölüm 16). Yedekleme bu dosyaların ve günlüğün yönetimidir.
4. Kat 3Bellek ve diskİndeksin sorguyu hızlandırması, sonunda diske (yavaş) gitmemek demektir (bkz. Bölüm 8).

Bu bölümün sonunda şunları yapabilirsin: bir sorgunun neden yavaş olduğunu EXPLAIN çıktısını okuyarak söyleyebilmek; indeksin ne kazandırıp ne kaybettirdiğini açıklamak; "iki kullanıcı aynı anda puan kazanırsa" sorusuna işlem, kilit ve yalıtım düzeyi kavramlarıyla cevap vermek; bir agent'ın yazdığı göç dosyasını (migration) okuyup ne yaptığını anlamak; ve bir Go koduna bakıp SQL enjeksiyonuna açık olup olmadığını görmek.

Bölümdeki bütün sayısal çıktılar hayal ürünü değil: Postgres 18.7'yi bir konteynerde çalıştırıp 10.000 kullanıcı ve 500.000 cevaplık bir tablo kurdum, komutları gerçekten çalıştırdım ve çıktıları buraya olduğu gibi aldım. Makinenden çıkan süreler farklı olacak; öğretici olan süreler değil, oranlar ve plan şekilleri.

39.1 Postgres neden: güvenilirlik, standartlara uyum, zengin tipler (JSONB)

Bölüm 38.1'de veritabanı yönetim sistemlerinin (DBMS) bir tür olduğunu söylemiştik: Postgres, MySQL, SQLite ve diğerleri aynı ilişkisel fikrin farklı gerçeklemeleridir. Postgres'in kendi tanıtım sayfası kendini şöyle tarif eder: SQL dilini kullanan ve genişleten, açık kaynak, nesne-ilişkisel (object-relational) bir veritabanı sistemi. Kökeni 1986'da Berkeley'deki Kaliforniya Üniversitesi'nde başlayan POSTGRES projesine uzanır; yaklaşık kırk yıllık bir geliştirme geçmişi vardır, 2001'den beri ACID uyumludur ve bütün büyük işletim sistemlerinde çalışır.¹ Aynı sayfa, geliştiricilerin kendi veri tiplerini ve işlevlerini tanımlayabildiği bir genişletilebilirlik de vurgular. Bu yazıyı yazdığım gün (13 Kasım 2026) güncel sürüm 18; 18.7 sürümü bir gün önce, 12 Kasım 2026'da yayımlandı.¹

Neden bizim uygulamamız için Postgres? Üç gerekçeyi ayrı ayrı söyleyeyim, çünkü her biri ayrı bir endişeye cevap verir.

• Güvenilirlik. Hukuk uygulamasında bir kullanıcının biriktirdiği 400 puan, "sunucu tam o anda kapandı" diye kaybolmamalı. "ACID" harfleriyle özetlenen güvence (39.3'te açacağız) Postgres'in ana vaadidir. Yazma işlemleri diske güvenli biçimde işlendikten sonra "tamam" denir.
• Standartlara uyum, yani SQL. Postgres SQL'i konuşur; öğrendiğin SELECT, JOIN, GROUP BY burada da geçerlidir. Yarın başka bir ilişkisel veritabanına geçmek zorunda kalırsan, bilgin büyük ölçüde taşınır.
• Zengin tipler. Tam sayı, metin ve tarihin yanında Postgres JSON'u da bir veri tipi olarak tanır. Bunu aşağıda açıyoruz.

JSON ile JSONB: tablonun içinde esnek bir kutu

Bölüm 38.4'te şemayı sütunlara bölmeyi anlatmıştık: her veri parçası bir sütun. Ama bazen verinin şekli değişkendir. Bizim sorularımızı düşün: bir soru çoktan seçmelidir (3 şık), bir başkası "doğru/yanlış"tır (2 seçenek), bir üçüncüsü boşluk doldurmadır. Hepsi için ayrı tablo mu kuracaksın? Postgres burada iki JSON tipi sunar: json ve jsonb. Resmî belgeye göre json girilen metnin birebir kopyasını saklar (boşluklar ve anahtar sırası dahil) ve her kullanımda yeniden çözümlenir; jsonb ise ayrıştırılmış ikilik bir biçimde saklanır, girişte biraz yavaş, işlemede belirgin biçimde hızlıdır ve indekslenebilir. Belge, özel bir ihtiyaç yoksa çoğu uygulamanın jsonb tercih etmesi gerektiğini söyler.²

Farkı kendim denedim. Aynı metni iki tipe de çevirdim; metinde "a" anahtarı iki kez geçiyor:

SELECT '{"b":1, "a":2, "a":3}'::json AS j,
       '{"b":1, "a":2, "a":3}'::jsonb AS jb;

 j                       | jb
-------------------------+---------------------
 {"b":1, "a":2, "a":3}   | {"a": 3, "b": 1}

json metni olduğu gibi tuttu; jsonb tekrarlanan anahtarı son değere indirdi ve anahtarları yeniden sıraladı. Belgede yazanla birebir aynı davranış: jsonb boşluk, anahtar sırası ve tekrarlanan anahtar saklamaz.² Bir de içeriği sorgulayabiliriz:

CREATE TABLE questions (
  id      serial PRIMARY KEY,
  body    text   NOT NULL,
  options jsonb  NOT NULL
);
INSERT INTO questions (body, options) VALUES
 ('Sözleşme ne zaman kurulur?',
  '{"choices":["Teklif ve kabul","Yalnız teklif","Yalnız ödeme"],
    "correct":0, "tags":["borçlar","sözleşme"]}');

SELECT options->>'correct' AS dogru, options->'choices'->>0 AS ilk FROM questions;
-- 0 | Teklif ve kabul

SELECT count(*) FROM questions WHERE options @> '{"tags":["borçlar"]}';
-- 1

-> bir JSON parçasını, ->> onu metin olarak verir; @> ise "bu belge, sağdakini içeriyor mu?" sorusudur. Bunun için indeks de kurulabilir (CREATE INDEX ... USING GIN (options), çalıştı); GIN'in ne olduğunu 39.2'de bir cümleyle göreceğiz.

39.2 Dizin (index) ve B-tree; sorgu planı (EXPLAIN)

Şimdi bölümün en pratik konusuna geliyoruz. Önce deney düzeneği. İki tablo kurdum: users (10.000 kullanıcı) ve answers (kim, hangi soruyu, doğru mu, ne zaman; 500.000 satır). Soru: "42 numaralı kullanıcının kaç cevabı var?"

CREATE TABLE users (
  id bigserial PRIMARY KEY, username text NOT NULL UNIQUE,
  total_xp int NOT NULL DEFAULT 0);
CREATE TABLE answers (
  id bigserial PRIMARY KEY,
  user_id bigint NOT NULL REFERENCES users(id),
  question_id int NOT NULL, correct boolean NOT NULL,
  created_at timestamptz NOT NULL DEFAULT now());

SELECT count(*) FROM answers WHERE user_id = 42;   -- cevap: 59

Sorgu planı: veritabanının "ne yapacağım" notu

Bölüm 38.3'te SQL'in bildirimsel olduğunu söylemiştik (Bölüm 21.5): sen ne istediğini yazarsın, nasıl bulunacağına veritabanı karar verir. O karara sorgu planı (query plan) denir ve planı görmek için sorgunun önüne EXPLAIN yazılır. EXPLAIN ANALYZE ise sorguyu gerçekten çalıştırır ve gerçek süreleri de ekler.³ (Bu yüzden EXPLAIN ANALYZE'i UPDATE ya da DELETE üzerinde çalıştırırsan değişiklik gerçekten yapılır; belge, veriyi değiştirmeden analiz etmek için komutu BEGIN ... ROLLBACK arasına almayı önerir.³)

İndeks yokken aldığım çıktı (okunaklı olsun diye bazı satırları kısalttım):

EXPLAIN ANALYZE SELECT count(*) FROM answers WHERE user_id = 42;

 Finalize Aggregate (cost=7281.43..7281.44 rows=1) (actual time=11.763..14.077 rows=1)
   -> Gather (cost=7281.22..7281.43 rows=2) ... Workers Launched: 2
        -> Partial Aggregate ...
             -> Parallel Seq Scan on answers (cost=0.00..6281.17 rows=21 width=0)
                                             (actual time=0.245..7.262 rows=19.67 loops=3)
                  Filter: (user_id = 42)
                  Rows Removed by Filter: 166647
                  Buffers: shared hit=3677
 Execution Time: 14.102 ms

Okuma kılavuzu:

• Seq Scan (sequential scan, sıralı tarama (sequential scan)): veritabanı tabloyu baştan sona okuyor ve her satıra "user_id = 42 mi?" diye bakıyor. Üç işçi (süreç) iş bölüşümü yapıyor ama her biri yaklaşık 166.647 satırı eliyor (Rows Removed by Filter). 500.000 satırın 59'unu bulmak için yarım milyon satıra bakmak, bir kanun maddesini bulmak için bütün Resmî Gazete arşivini baştan okumaya benzer.
• cost: planlayıcının tahmini maliyeti. Birimi "keyfî"dir; belgeye göre gelenekte bir disk sayfasını okumanın maliyeti 1 alınır ve diğer her şey buna göre ölçülür. Süre değildir; planları birbiriyle karşılaştırmak içindir.³
• actual time / Execution Time: gerçek süre, milisaniye. Burada 14,1 ms.
• Buffers: shared hit=3677: Postgres'in kendi bellek önbelleğinden okuduğu sayfa sayısı (varsayılan sayfa boyutu 8 KB). Tablo 29 MB; hepsi taranıyor. (Bölüm 8'in önbellek fikri burada da işliyor: sayfalar bellekteydi, o yüzden 14 ms; diskten okunsaydı çok daha yavaş olurdu.)

Dizin ve B-tree

Çözüm, bir kitabın arkasındaki dizindir. Postgres belgesi benzetmeyi kendisi yapar: çok aranan terimler kitabın sonunda alfabetik bir dizinde toplanır, okur bütün kitabı okumak yerine dizine bakıp ilgili sayfaya gider.⁴ Veritabanında dizin (index), bir sütunun değerlerini sıralı tutan ve her değerin tablodaki yerini gösteren ek bir veri yapısıdır. Kurmak tek komut:

CREATE INDEX answers_user_id_idx ON answers (user_id);

Postgres'te CREATE INDEX varsayılan olarak B-tree (B-tree, dengeli arama ağacı) kurar.⁵ Bu, Bölüm 11'deki ağaç fikrinin disk için ayarlanmış halidir: her düğüm birçok anahtar taşır, ağaç dengeli kalır ve herhangi bir değere, ağacın birkaç düzeyi inilerek ulaşılır (belge de "arama ağacında birkaç düzey yürümesi yeterli" der⁴). 500.000 değeri ikili aramayla ortadan bölerek bulmak yaklaşık 19 adımdır (2¹⁹ = 524.288); B-tree düğümleri geniş olduğundan gerçekte daha da az sayfa okunur. B-tree eşitlik (=) ve aralık (<, <=, >, >=, BETWEEN) sorgularını destekler, sıralı veri döndürmeye de yarar.⁵

Aynı sorguyu dizinden sonra çalıştırdım:

 Aggregate (cost=188.07..188.08 rows=1) (actual time=0.125..0.126 rows=1)
   -> Bitmap Heap Scan on answers (cost=4.81..187.94 rows=50) (actual rows=59)
        Recheck Cond: (user_id = 42)
        -> Bitmap Index Scan on answers_user_id_idx
             Index Cond: (user_id = 42)
 Execution Time: 0.145 ms

14,1 ms'den 0,145 ms'ye: yaklaşık 100 kat. Planda "Index Scan" ailesi göründü; sayfalar yalnızca 59'luk sonuca gidecek kadar okundu (Buffers: shared hit=62, öncekinde 3677). Dizinin kendisi 3.496 kB, tablo 29 MB: yaklaşık altıda biri kadar ek yer.

Dizin bedava değildir

Her yeni cevap eklendiğinde Postgres yalnızca tabloya değil, her dizine da yazar; bu yüzden dizinler yazmayı yavaşlatır, yer kaplar ve bakım ister. Belge de dizinlerin eklenip kaldırılabileceğini, sistemin dizini güncel tuttuğunu ve yalnızca daha verimli olacağını düşündüğünde kullandığını söyler.⁴ İlkel kural: okuma çok, yazma az olan ve sık filtrelenen/sıralanan/birleştirilen sütunlara dizin kur; her sütuna kurma. Bu kurala bir istisna: çok küçük bir tabloda (birkaç yüz satır) tarama zaten ucuzdur, planlayıcı dizini kullanmayabilir ve bu normaldir.

Bileşik dizin: filtre ve sıralama birlikte

Leaderboard'a ya da "kullanıcının son 10 cevabı" ekranına gelelim: WHERE user_id = 42 ORDER BY created_at DESC LIMIT 10. Tek sütunluk dizinle plan, 59 satırı bulup sonra sıralıyor (Sort düğümü). İki sütunlu bir dizin ikisini birden çözer:

CREATE INDEX answers_user_created_idx ON answers (user_id, created_at DESC);

 Limit (cost=0.42..41.40 rows=10) (actual time=0.039..0.046 rows=10)
   -> Index Scan using answers_user_created_idx on answers
        Index Cond: (user_id = 42)
 Execution Time: 0.056 ms

Dizin zaten user_id'ye göre, onun içinde created_at'e göre sıralı olduğundan veritabanı ilk 10 girdiyi alıp duruyor; sıralama adımı planda yok. Bileşik dizinde sütun sırası önemlidir: bu dizin "yalnızca created_at'e göre ara" sorgusuna aynı verimle yardım etmez, çünkü önce user_id ile sıralıdır.

Dizin ne zaman kullanılmaz: bir tuzak

users.username üzerinde dizin vardı (çünkü UNIQUE). Yine de WHERE username LIKE 'u99%' ve WHERE lower(username) = 'u99' sorgularının ikisi de planda Seq Scan verdi. Neden? Belge ilkini açıklıyor: B-tree dizini LIKE için ancak desenin başa sabitli olduğu durumda kullanılabilir ('foo%'), fakat veritabanı C yerel ayarında değilse özel bir işleç sınıfıyla kurulması gerekir.⁵ İkincisi daha basit: dizin username'in kendisini tutuyor, lower(username)'i değil; sorguda sütun bir işlevin içine girince dizin devre dışı kalır. Çözümü ("ifade dizini": CREATE INDEX ... (lower(username))) bilmen şart değil; asıl ders şu: dizin kurmak yetmez, planı gör. Agent "dizin ekledim" dediğinde EXPLAIN ile kullanılıp kullanılmadığına bakmak senin işin.

Postgres'te başka dizin türleri de var: Hash (yalnızca eşitlik), GiST, SP-GiST, GIN ("içinde birden çok değer barındıran" veriler: diziler, JSONB), BRIN.⁵ Hepsini ezberlemene gerek yok; adı geçtiğinde bunların "aynı fikrin farklı veri şekilleri için varyantları" olduğunu bil.

39.3 İşlem (transaction) ve ACID; eşzamanlı yazma

Bölüm 14.4'te iki iş parçacığı aynı sayacı arttırınca bir artışın kaybolabildiğini görmüştük: yarış durumu. Aynı şey veritabanında da olur; hatta daha sık, çünkü yüzlerce kullanıcı aynı anda yazıyor. Veritabanının buna cevabı işlem (transaction): birden çok adımı tek bir "ya hep ya hiç" birimine bağlayan mekanizma. Belgenin tarifi: bir işlem birçok adımı tek bir hep-ya-da-hiç işlemine toplar; adımlar arasındaki ara durumlar diğer eşzamanlı işlemlerce görülmez ve bir arıza işlemin tamamlanmasını engellerse hiçbir adım veritabanını etkilemez.⁶

Hukuk benzetmesi yerinde: noterde yapılan bir işlem. Satış sözleşmesinde "bedel ödendi" ve "mülkiyet geçti" iki ayrı adımdır; ikisinden yalnızca biri gerçekleşmiş bir dünya kabul edilemez. İşlem, ikisini tek bir tasarrufa çevirir.

BEGIN;
UPDATE users SET total_xp = total_xp + 10 WHERE id = 1;
INSERT INTO answers (user_id, question_id, correct) VALUES (1, 7, true);
COMMIT;      -- ikisi birden görünür olur
-- araya ROLLBACK; girseydi ikisi de iptal olurdu

BEGIN işlemi açar, COMMIT onaylar, ROLLBACK geri alır. Postgres'te BEGIN yazmasan bile her SQL deyimi kendi küçük işleminin içinde çalışır.⁶

ACID: dört güvence

İşlemlerin vaadi dört harfle anılır. Postgres'in öğretici belgesi her birine değinir; ben aynı sırayla açıklıyorum:⁶

Kalıcılık, Bölüm 8.3'teki uçucu ve kalıcı ayrımıyla birebir ilgili: bellekte duran veri güç gidince kaybolur; "tamam" cevabından önce diske yazılmak zorunda olan şey, işlemin günlüğüdür.

Yarış durumunu gözümüzle görelim

İki kullanıcı değil, aynı kullanıcı için iki olay düşün: Kerem aynı anda iki sekmede iki soruyu doğru bildi; sunucu iki istek alıyor, biri +10, öbürü +5 puan yazacak. Doğru sonuç 15. Üç yöntemi iki gerçek psql oturumuyla yarıştırdım (her ikisi de 0 puanla başlıyor):

Birinci yöntem tam Bölüm 14.4'ün hatası: iki oturum da 0'ı okudu; biri 0+10 yazdı, öbürü 0+5 yazdı ve sonuncu kazandı. Hata mesajı yok, kimse fark etmeyecek; puan sessizce yanlış. İkinci yöntemde işlem artırmayı veritabanının içinde yapar; bir satırı güncelleyen iki komut sırayla çalışır ve ikincisi, birincinin değiştirdiği güncel değeri görür. Belgenin Read Committed açıklaması tam bunu söyler: ikinci güncelleyici, birincinin bitmesini bekler ve commit olmuşsa satırın güncellenmiş sürümü üzerinde işlemini uygular.⁷ Üçüncü yöntemde FOR UPDATE satırı "kilitler": belgeye göre aynı satırı güncellemeye, silmeye ya da kilitlemeye çalışan diğer işlemler, bu işlem bitene kadar bloke olur.⁸

Ders: değeri koda çekip hesaplayıp geri yazmak yerine, hesabı veritabanına yaptır (Bölüm 35.4'te gördüğün idempotent işlem fikri de buna yakın bir ruhla çalışır). Bunu agent'ın kodunda gözünle arayacağın en önemli kalıplardan biri olarak not et: "user.XP += 10; db.Save(user)" türü kod, tam bu hatanın kaynağıdır.

Yalıtım düzeyleri ve MVCC

"Yalıtım" tek bir ayar değil, bir kademe. SQL standardı dört düzey tanımlar; Postgres'in varsayılanı Read Committed'dır.⁷ Kademeleri anlamak için önce hangi anomalilerin önlenmeye çalışıldığını bil:⁷

• dirty read (kirli okuma): henüz onaylanmamış (commit edilmemiş) bir işlemin yazdığını okumak. Postgres'te hiçbir düzeyde olmaz.
• nonrepeatable read (tekrarlanamayan okuma): aynı satırı aynı işlemde iki kez okuyup, arada başkasının onayladığı bir değişiklik yüzünden farklı değer görmek.
• phantom read (hayalet okuma): aynı koşulla iki kez sorgulayıp, arada başkasının onayladığı bir işlem yüzünden satır kümesinin değiştiğini görmek.
• serialization anomaly: bir grup işlemin onaylanmış sonucu, onların tek tek, sırayla çalıştırılmasından çıkabilecek hiçbir sonuca benzememesi.

Postgres Read Committed'da her komut, komutun başladığı anın görüntüsünü (snapshot) görür. Repeatable Read'de ise görüntü işlemin başladığı andır; yani işlem boyunca dünya donmuş gibi görünür.⁷ Serializable en katı düzeydir: sonucu sanki işlemler teker teker çalışmış gibi garanti eder.⁷

Bu görüntü fikrinin arkasındaki mekanizma çok sürümlü eşzamanlılık denetimi (MVCC, multiversion concurrency control)'dir. Belgenin tanımı: her SQL komutu, altta yatan verinin şu an ne olduğundan bağımsız olarak, verinin bir zaman önceki görüntüsünü görür.⁹ Pratik sonucu: MVCC'de okumak için alınan kilitler yazmak için alınanlarla çakışmaz; yani okuma yazmayı, yazma okumayı bloke etmez.⁹ Leaderboard sayfasını yüzlerce kullanıcı açarken puan yazan işlemler beklemez; bu, Postgres'in bu iş için iyi bir seçim olmasının temel nedenlerinden biri.

Repeatable Read'i de denedim. İki işlem aynı satırı güncellemeye çalışırken, ilki onayladı; ikincisi şu hatayı aldı ve geri alındı:

ERROR:  could not serialize access due to concurrent update

Belgenin söylediği tam bu: Repeatable Read'de işlem başladıktan sonra başkasının onayladığı bir değişikliği değiştirmeye çalışırsan hata alırsın ve uygulama işlemi baştan denemeye hazır olmalıdır (retry).⁷ Yani daha katı yalıtım, bedelini "yeniden dene" yükü olarak uygulamaya bırakır. Varsayılan Read Committed + atomik UPDATE kalıbı, bizim ihtiyaçlarımızın çoğunu karşılar; katı düzeylere ancak gerçekten gerektiğinde, nedenini bilerek geç.

Başka bir kalkan: kısıt ve ON CONFLICT

Aynı bölümü iki kez tamamlayarak puanı iki kez almak ("çift tıklama" ya da ağ yeniden denemesi) de bir yarış durumudur. Çözümü kodda "daha önce aldı mı?" diye bakmak (bu da okuyup-sonra-yazmak) yerine, veritabanına kısıt bildirmektir:

CREATE TABLE completions (
  user_id bigint, lesson_id int, xp int,
  PRIMARY KEY (user_id, lesson_id));        -- aynı çift iki kez olamaz

INSERT INTO completions VALUES (1, 7, 10) ON CONFLICT DO NOTHING;  -- INSERT 0 1
INSERT INTO completions VALUES (1, 7, 10) ON CONFLICT DO NOTHING;  -- INSERT 0 0

İkinci eklemede hata da yok, ikinci satır da yok (INSERT 0 0: sıfır satır eklendi). Kontrolü veritabanı yapıyor; iki istek aynı anda gelse de çakışan birine veritabanı karar verir. "Bir kullanıcı bir bölümü yalnızca bir kez tamamlayabilir" kuralı artık kodun değil, şemanın kuralı.¹⁰

func AddXP(ctx context.Context, pool *pgxpool.Pool, userID int64, xp int) (int, error) {
	tx, err := pool.Begin(ctx)                 // BEGIN
	if err != nil {
		return 0, err
	}
	defer tx.Rollback(ctx)                     // hata olursa geri al; COMMIT sonrası zararsız

	var total int
	err = tx.QueryRow(ctx,
		`UPDATE users SET total_xp = total_xp + $1 WHERE id = $2 RETURNING total_xp`,
		xp, userID).Scan(&total)               // atomik artış, yeni değeri geri al
	if err != nil {
		return 0, err
	}
	_, err = tx.Exec(ctx,
		`INSERT INTO answers (user_id, question_id, correct) VALUES ($1, $2, true)`,
		userID, 1)
	if err != nil {
		return 0, err
	}
	return total, tx.Commit(ctx)               // COMMIT: ikisi birden kalıcı
}

39.4 Şema göçü (migration)

İlk gün şemayı kurarsın. Üçüncü hafta bir şey değişir: kullanıcıya "seri" (streak) sütunu eklemek gerekir. Prototipte dosyayı elle değiştirirdin. Ama canlı veritabanında binlerce kullanıcının verisi var ve her ortamda (senin bilgisayarın, test, üretim; Bölüm 43.1) şemanın aynı olması lazım. Çözüm: şema değişikliklerini, sırayla numaralanmış küçük SQL dosyaları olarak depoya koymak ve bir araçla uygulamak. Bu dosyalara şema göçü (migration) denir.

Go dünyasında yaygın araçlardan biri golang-migrate. Resmî öğreticisindeki düzen şöyle: migrate create -ext sql -dir db/migrations -seq create_users_table komutu iki dosya üretir, 000001_create_users_table.up.sql ve 000001_create_users_table.down.sql. up dosyası değişikliği uygular, down dosyası geri alır. Uygulamak için migrate -database $URL -path db/migrations up çalıştırılır.¹¹ Yani:

db/migrations/
  000001_create_users.up.sql         -- CREATE TABLE users (...)
  000001_create_users.down.sql       -- DROP TABLE users
  000002_add_streak_to_users.up.sql  -- ALTER TABLE users ADD COLUMN streak int NOT NULL DEFAULT 0;
  000002_add_streak_to_users.down.sql-- ALTER TABLE users DROP COLUMN streak;

Araç, hangi numaraya kadar uygulandığını veritabanının içinde tutar; up dediğinde yalnızca henüz uygulanmamış dosyaları, sırayla çalıştırır. Böylece şema da kod gibi sürüm denetimine girer (Bölüm 28): bir git commit'i hem kodu hem o kodun beklediği şemayı birlikte getirir.

Aracın öğreticisi bir önemli ayrıntıyı vurgular: Postgres'te sorguların bir işlem içinde çalışmasını istiyorsan BEGIN ve COMMIT ile sarmalamalısın; yoksa göç yarıda kesilirse şema yarım kalır.¹¹ Üç tür tuzak:

• Var olan satırlar. 10.000 kullanıcılı tabloya NOT NULL sütun eklerken değer vermezsen eski satırlar neyle dolacak? Bu yüzden yukarıdaki göçte DEFAULT 0 var. Gerçekten çalıştırdım: ALTER TABLE users ADD COLUMN streak int NOT NULL DEFAULT 0 sonrasında SELECT count(*), max(streak) sonucu 10000 | 0 verdi.
• Kilit. Postgres belgesi, bazı işlemlerin (örneğin çoğu ALTER TABLE biçiminin) özel kilit gerektirdiğini söyler;¹² büyük bir tabloda bu, o an için diğer işlemlerin beklemesi demektir. Trafik altındaki üretim veritabanında göç yazmak ayrı bir beceri.
• Geri alınamazlık. DROP COLUMN verinin kendisini siler; down dosyası şemayı geri getirir, veriyi değil. Veri silen göçlerden önce yedek (39.6) alınır.

39.5 Go'dan bağlanmak: bağlantı havuzu, SQL enjeksiyonu ve parametreli sorgu

Bölüm 37'de handler → servis → depo katmanlarını kurmuştuk; depo katmanı artık gerçekten Postgres'le konuşacak. Postgres ayrı bir süreç olduğundan (Bölüm 14) Go programı ona ağ üzerinden, TCP ile bağlanır (Bölüm 19.5). Go'nun standart kütüphanesindeki database/sql ortak arayüzü sunar; Postgres için yaygın olarak kullanılan sürücü ve araç takımı ise pgx'tir. Aşağıdaki örneklerin hepsi pgx v5 ile yazılıp gerçek bir Postgres'e karşı çalıştırıldı.

Bağlantı havuzu

Her istek için yeni bir veritabanı bağlantısı açmak pahalıdır: ağ el sıkışması, kimlik doğrulama, sunucu tarafında bir bağlantı kurmak. Bunun yerine program açılırken birkaç bağlantıyı hazır açar, istekler kullanıp geri verir. Bu hazır bağlantı grubuna bağlantı havuzu (connection pool) denir. pgx'in pgxpool paketi tam bunu yapar; paketin tanımı: "pgx için eşzamanlı çağrılara güvenli (concurrency-safe) bir bağlantı havuzu". Havuz kurulurken bağlantıların hemen açılmasını beklemez (bağlantıyı denemek için hemen bir bağlantı edinmek gerekir) ve MaxConns ayarı havuzun azami boyutudur; varsayılanı 4 ile işlemci sayısından büyük olanıdır.¹³

cfg, err := pgxpool.ParseConfig(os.Getenv("DATABASE_URL"))  // adres ortam değişkeninden (bkz. 43.7)
if err != nil { panic(err) }
cfg.MaxConns = 10                                           // en fazla 10 eşzamanlı bağlantı
pool, err := pgxpool.NewWithConfig(ctx, cfg)
if err != nil { panic(err) }
defer pool.Close()

Havuz sınırdır de: Postgres'in kendisinin de bir üst bağlantı sınırı vardır (max_connections; denediğim kurulumda 100). Hem yüzlerce Go goroutine'in (Bölüm 36.4) hem de birden çok sunucu kopyasının her biri havuz boyutu kadar bağlantı alırsa bu sınır dolar. "Daha çok bağlantı = daha hızlı" değildir; havuz boyutu bilinçli seçilen bir sayıdır.

SQL enjeksiyonu

Güvenliğin en klasik hatası, kullanıcıdan gelen metni SQL cümlesine yapıştırmaktır. Kullanıcı adı alanına şunu yazdığını düşün: x' OR '1'='1. Kod, sorguyu metin birleştirerek kurduysa, veritabanının gördüğü şey artık:

SELECT count(*) FROM users WHERE username = 'x' OR '1'='1'

Kullanıcıdan gelen veri, verinin içinde kalmadı; komutun bir parçası oldu. Bu hatanın adı SQL enjeksiyonu (SQL injection)'dur. İki yöntemi aynı bağlantıda denedim:

kotu := "x' OR '1'='1"
// 1) parametreli: değer ayrı gönderilir
pool.QueryRow(ctx, `SELECT count(*) FROM users WHERE username = $1`, kotu).Scan(&n)
//    -> n = 0       (kimse "x' OR '1'='1" adını taşımıyor)

// 2) metin birleştirme: değer cümlenin içine gömülür
pool.QueryRow(ctx, "SELECT count(*) FROM users WHERE username = '"+kotu+"'").Scan(&n)
//    -> n = 10000   (koşul her zaman doğru: bütün kullanıcılar eşleşti)

Birincisi 0, ikincisi 10.000 döndü. Parametreli sorgu (parameterized query)nun fikri: SQL'in yapısı ile değerleri ayrı kanallardan gider; veritabanı $1 yerine gelen şeyi her koşulda bir değer olarak ele alır, komut olarak asla. Hem OWASP'ın SQL Injection Prevention Cheat Sheet'i hem Go'nun resmî belgesi aynı şeyi söyler: parametreli sorguları tercih et, elle kaçışlamaya (escaping) güvenme ve sütun/tablo adı gibi parametrelenemeyen yapısal parçaları kullanıcıdan alma, sabit bir izin listesinden seçtir.¹⁴¹⁵ SQL enjeksiyonunu Bölüm 41.4'te diğer saldırılarla birlikte yeniden göreceğiz.

39.6 Yedekleme (backup)

Bütün bu güvencelerin (ACID, kısıtlar) bir sınırı var: hiçbiri "yanlışlıkla DELETE FROM users; yazdım", "disk bozuldu", "sunucu silindi" ya da "bir göç hatalı veri yazdı" durumunu kurtarmaz. Bunun için tek çare, verinin ayrı bir yerde duran bir kopyasıdır: yedek. Postgres belgesi yedeklemenin üç ayrı yaklaşımını anlatır: SQL dökümü, dosya sistemi düzeyinde yedek ve sürekli arşivleme.

SQL dökümü: pg_dump

En basit ve en çok kullanılanı pg_dump: veritabanını, geri yüklendiğinde aynı durumu yeniden kuracak SQL komutlarına (ya da sıkıştırılmış bir biçime) dönüştürür.¹² Belgeye göre dökümler, pg_dump'ın çalışmaya başladığı andaki tutarlı bir görüntüdür ve çalışırken diğer işlemleri engellemez (özel kilit isteyen işlemler hariç).¹² Bunu da MVCC'ye borçlusun: dökümü alan işlem kendi görüntüsünü okur, yazanlar beklemez. Aynı belge, pg_dump çıktısının genellikle daha yeni Postgres sürümlerine yüklenebildiğini, dosya düzeyindeki yedeklerin ise sürüme özel olduğunu söyler.¹²

pg_dump -Fc postgres -f hukuk.dump            # -Fc: sıkıştırılmış özel biçim
createdb kopya                                # boş bir veritabanı
pg_restore -d kopya hukuk.dump                # geri yükle

Denedim: 500.000 cevaplı veritabanının dökümü yaklaşık 3,7 MB'lık bir dosya oldu (sıkıştırılmış) ve kopya veritabanında users 10.000, answers 500.001 satır olarak geri geldi (500.001: Go örneğinin eklediği bir cevap). Belge ayrıca iki önemli ayrıntı söyler: düz metin dökümü psql ile yüklenir ve --single-transaction (-1) ile yüklersen yükleme ya tam biter ya da tam geri alınır; yükleme sonrası da ANALYZE çalıştırman önerilir ki planlayıcı güncel istatistiklere sahip olsun.¹²

Sürekli arşivleme ve belirli ana dönüş (PITR)

Dökümün zayıf yanı, dökümün alındığı ana dönebilmeni sağlamasıdır; dünkü dökümle çalışıyorsan bugünkü işler gider. Postgres her değişikliği önce bir ön yazma günlüğüne (WAL, write-ahead log) yazar; bu günlük çökme güvenliği için vardır, ama aynı zamanda yedekleme için de kullanılır: bir dosya sistemi yedeği ile günlük dosyalarının arşivini birleştirirsen, günlüğü istediğin ana kadar tekrar oynatarak veritabanını geçmişteki herhangi bir ana döndürebilirsin. Buna belirli ana dönüş (point-in-time recovery, PITR) denir.¹⁶ Belge bu yöntemi yönetmesi daha karmaşık, ama yüksek güvenilirlik istenen birçok durumda tercih edilen yöntem diye tarif eder; aynı belge, pg_dump çıktısının bu yönteme kaynak olamayacağını da belirtir (dökümler mantıksaldır).¹⁶

Bu bölümde neler kuruldu

Postgres güvenilirliği, SQL uyumu ve JSONB gibi zengin tipleri nedeniyle seçilen, ACID uyumlu ilişkisel bir sistemdir. Dizin (varsayılan olarak B-tree) sorguyu tüm tabloyu taramaktan kurtarır; EXPLAIN hangi planın seçildiğini gösterir; bedeli yazma yavaşlığı ve yerdir. İşlem adımları ya-hep-ya-hiç birimine toplar; ACID bölünmezlik, tutarlılık, yalıtım ve kalıcılığı vaat eder; MVCC ile okuma yazmayı bloke etmez; aynı satıra eşzamanlı yazmada hesabı veritabanına yaptırmak (atomik UPDATE), gerekirse FOR UPDATE ya da kısıt/ON CONFLICT kullanmak gerekir. Şema göçü şema değişikliğini sürümlü SQL dosyalarına çevirir. Go'da bağlantı havuzu bağlantıları yeniden kullanır; parametreli sorgu SQL enjeksiyonunu engeller. Yedek felakette dönüş yoludur; pg_dump mantıksal, sürekli arşivleme ise zamanda geri gitmeye izin verir.

Terimler sözlükte, Bölüm 39 başlığı altında.

Kaynaklar

1. PostgreSQL, About: nesne-ilişkisel sistem, 1986 kökeni, 2001'den beri ACID uyumu, genişletilebilirlik; sayfa 13 Kasım 2026'da 18.7 sürümünü duyurmaktadır.
2. PostgreSQL 18 belgeleri, 8.14 JSON Types: json ile jsonb farkı.
3. PostgreSQL 18 belgeleri, 14.1 Using EXPLAIN: maliyet birimi, EXPLAIN ANALYZE. Bölümdeki plan çıktıları Postgres 18.7 üzerinde bu bölümü yazarken gerçekten alındı.
4. PostgreSQL 18 belgeleri, 11.1 Introduction (Indexes): kitap dizini benzetmesi, dizin bakımı, ANALYZE.
5. PostgreSQL 18 belgeleri, 11.2 Index Types: B-tree, Hash, GiST, SP-GiST, GIN, BRIN; B-tree ve LIKE.
6. PostgreSQL 18 belgeleri, 3.4 Transactions: hep-ya-da-hiç, kalıcılık, BEGIN/COMMIT/ROLLBACK, SAVEPOINT.
7. PostgreSQL 18 belgeleri, 13.2 Transaction Isolation: anomaliler, Read Committed, Repeatable Read, Serializable, "could not serialize access" hatası.
8. PostgreSQL 18 belgeleri, 13.3 Explicit Locking: FOR UPDATE.
9. PostgreSQL 18 belgeleri, 13.1 Introduction (Concurrency Control): MVCC, okuma yazmayı bloke etmez.
10. PostgreSQL 18 belgeleri, INSERT: ON CONFLICT DO NOTHING.
11. golang-migrate, PostgreSQL tutorial: up/down dosyaları, migrate create, migrate up, BEGIN/COMMIT ile göç.
12. PostgreSQL 18 belgeleri, 25.1 SQL Dump: pg_dump, özel kilit gerektiren işlemler (ör. çoğu ALTER TABLE), geri yükleme, ANALYZE.
13. pgx, pgxpool paketi: eşzamanlı çağrılara güvenli havuz, MaxConns varsayılanı.
14. OWASP, SQL Injection Prevention Cheat Sheet: parametreli sorgular, izin listesi.
15. Go belgeleri, Avoiding SQL injection risk: parametre değerlerini sql paketi işlevlerine argüman olarak vermek.
16. PostgreSQL 18 belgeleri, 25.3 Continuous Archiving and PITR: WAL, belirli ana dönüş.
17. PostgreSQL 18 belgeleri, 5.5 Constraints: yabancı anahtar ve dizin.