PostgreSQL UPSERT nedir?
PostgreSQL UPSERT, benzersiz anahtar çatıştığında yeni satır eklemek yerine mevcut satırı güncelleme yaklaşımıdır. INSERT ... ON CONFLICT DO UPDATE, bu kararı veritabanındaki tek komutta ifade eder. Önce kaydı arayıp sonra eklemekten farklı olarak, ekleme ve çatışma çözümü aynı işlemin parçasıdır. PostgreSQL INSERT belgesi, ON CONFLICT davranışını tanımlar.
Bir fiyat aktarımında aynı ürün kodu tekrar gelebilir. Her aktarımı yeni satır yapmak kopya üretir; ilk satırdan sonra bütün kayıtları reddetmek ise güncel fiyatı kaçırır. İhtiyaç, hangi kaydın aynı ürünü temsil ettiğini ve hangi yeni bilginin kabul edileceğini açıkça tanımlamaktır.
ON CONFLICT hangi benzersiz anahtarı kullanır?
Çatışma hedefi, veritabanında karşılığı olan uygun bir benzersiz kısıt veya indeksle eşleşmelidir. Örnekte sku birincil anahtardır; ürünün iş kimliğini temsil eder. Kısıtlar belgesi, benzersizliğin veritabanında nasıl sağlandığını açıklar.
Aşağıdaki SQL blokları aynı oturumda sırayla çalıştırılabilir. Geçici tablo yalnızca örnek içindir:
CREATE TEMP TABLE product_prices (
sku text PRIMARY KEY,
price numeric(10, 2) NOT NULL CHECK (price >= 0),
observed_at timestamptz NOT NULL
);
INSERT INTO product_prices (sku, price, observed_at)
VALUES ('BOOK-1', 100.00, TIMESTAMPTZ '2026-11-03 09:00:00+00');
Gerçek sistemde aynı ürün kodu farklı tedarikçilerde farklı anlam taşıyorsa, yalnızca sku yeterli olmayabilir. İş anahtarını yanlış seçmek, teknik olarak başarılı bir UPSERT'in yanlış kaydı güncellemesine neden olabilir. Kapsam kararını SQL sözdiziminden önce verin.
EXCLUDED ve mevcut satır nasıl ayrılır?
EXCLUDED, eklenmesi önerilen satırın değerlerini; tablo adı veya takma adı ise mevcut satırı ifade eder. Böylece hangi alanların yeni değerle değişeceği açıkça yazılabilir.
INSERT INTO product_prices AS current_price (sku, price, observed_at)
VALUES ('BOOK-1', 120.00, TIMESTAMPTZ '2026-11-03 10:00:00+00')
ON CONFLICT (sku) DO UPDATE
SET price = EXCLUDED.price,
observed_at = EXCLUDED.observed_at
WHERE EXCLUDED.observed_at > current_price.observed_at
RETURNING sku, price, observed_at;
Bu örnekte yeni gözlem daha güncelse fiyat değiştirilir. Aynı zaman damgası veya eski bir gözlem güncelleme yapmaz. Zaman damgasının güvenilirliği ve eşit zamanda gelen farklı fiyatlar için seçilecek politika uygulamanın sorumluluğudur; SQL, hangi kaynağın gerçeği söylediğini bilemez.
Bu koruma olmasaydı, geç ulaşan eski aktarım güncel fiyatın üzerine yazabilirdi. Kontrol yalnızca uygulamada önce SELECT yapılarak uygulanırsa, okuma ile yazma arasına başka bir işlem girebilir. İzolasyon belgesi, eşzamanlı ON CONFLICT işlemlerini açıklar.
RETURNING boş gelirse işlem başarısız mı olmuştur?
RETURNING, gerçekten eklenen veya güncellenen satırları döndürür. DO UPDATE içindeki WHERE koşulu sağlanmadığında satır kilitlenebilir, fakat güncellenmez ve RETURNING sonucunda yer almaz. Bu, tek başına SQL hatası değildir.
İkinci sorguyu daha eski bir observed_at değeriyle tekrar deneyin. Mevcut fiyat korunmalı ve sonuç boş olmalıdır. Uygulama bunu güncelleme yapıldı şeklinde raporlamamalıdır; iş kuralına göre eski kayıt atlandı gibi ayrı bir sonuç üretilebilir.
DO NOTHING de mevcut kaydı döndürmek anlamına gelmez:
INSERT INTO product_prices (sku, price, observed_at)
VALUES ('BOOK-1', 90.00, TIMESTAMPTZ '2026-11-03 08:00:00+00')
ON CONFLICT (sku) DO NOTHING
RETURNING sku;
Ürün zaten bulunduğundan bu komut yeni satır eklemez ve sku döndürmez. Mevcut veriyi okumak gerekiyorsa bunu ayrıca tasarlayın.
UPSERT bütün veri hatalarını çözer mi?
ON CONFLICT, seçilen benzersizlik çatışmasını yönetir; CHECK, NOT NULL ve diğer bağımsız hataları yok saymaz. Tek bir toplu DO UPDATE komutunda aynı mevcut satırı birden fazla kez etkilemeye çalışan girdiler de hata verebilir.
Aktarım başlamadan aynı iş anahtarının bir dosyada tekrar edip etmediğini kontrol edin. İlk kayıt mı son kayıt mı seçilecek, yoksa aktarım mı reddedilecek? Bu karar, dosyanın geliş sırasına tesadüfen bırakılmamalıdır.
UPSERT, gönderilen e-postayı veya dış servis çağrısını tekrar güvenli hale de getirmez. Veritabanı kaydı ile dış etkiler farklı sorumluluklardır; webhook idempotency rehberi bu ayrımı ele alır.
UPSERT örneği nasıl doğrulanır?
Yeni anahtar, mevcut anahtar, daha yeni gözlem, eski gözlem ve eşit zaman damgasını ayrı deneyin. Negatif fiyatın kısıt nedeniyle reddedildiğini ve tabloda bir ürün için tek satır kaldığını kontrol edin.
Eşzamanlı iki aktarımda yalnızca son satır sayısına bakmayın; kabul edilen gözlem ve fiyatın birlikte tutarlı kaldığını da doğrulayın. Daha geniş iş akışı bütünlüğü için transaction rehberindeki kuralları değerlendirin.
Sık sorulan sorular
ON CONFLICT için UNIQUE gerekli mi? Örnekteki sku hedefi uygun benzersizlik güvencesine dayanır; PRIMARY KEY bunu sağlar.
DO NOTHING mevcut satırı RETURNING ile verir mi? Hayır. Atlanan satır eklenmiş veya güncellenmiş sayılmaz.
UPSERT yerine önce SELECT yapmak yeterli mi? Tek başına değil. Başka bir istek, kontrol ile ekleme arasına girebilir.

