Veriyi Ekleme veya Mevcut Kaydı Güncelleme
Yazılım geliştirirken sıkça şu senaryoyla karşılaşırız: Bir veriyi tabloya eklemek isteriz ancak aynı anahtara sahip bir kayıt zaten mevcutsa, hata almak yerine o kaydı güncellemek daha mantıklıdır. UPSERT mekanizması olmasaydı, önce
SELECT ile kaydın varlığını kontrol edip ardından duruma göre INSERT veya UPDATE sorgularından birini çalıştırmamız gerekirdi. Bu yöntem hem iki ayrı sorgu gerektirdiği için verimsizdir hem de işlemler arasında "yarış durumu" (race condition) riskini beraberinde getirir.SQLite, UPSERT özelliği sayesinde tüm bu süreci tek bir komutla çözer:
SQL:
CREATE TABLE products (
sku TEXT PRIMARY KEY,
name TEXT NOT NULL,
price REAL NOT NULL
);
INSERT INTO products (sku, name, price)
VALUES ('A-100', 'Widget', 9.99)
ON CONFLICT(sku) DO UPDATE SET
name = excluded.name,
price = excluded.price;
SELECT * FROM products;
Kodu çalıştırdığınızda, ilk seferde satır tabloya eklenir. Ancak aynı
sku değerine sahip farklı bir fiyatla işlemi tekrarladığınızda, mevcut kayıt güncellenir. Böylece ne mükerrer kayıt oluşur ne de hata alınır.ON CONFLICT Yapısının Detayları
Kullanılan genel şablon şöyledir:
SQL:
INSERT INTO table (...) VALUES (...)
ON CONFLICT(conflict_target) DO UPDATE SET col = expr, ...
WHERE condition;
Bu yapıda üç temel nokta öne çıkar:
•
conflict_target - Çakışmanın beklenildiği, UNIQUE veya PRIMARY KEY kısıtı olan sütun ya da sütun grubudur. SQLite, hangi indeks üzerinden kontrol yapacağını buradan anlar.•
DO UPDATE SET ... - Bir çakışma yaşandığında hangi alanların nasıl güncelleneceğini belirler. Eğer herhangi bir işlem yapılmasın isteniyorsa DO NOTHING kullanılır.• Opsiyonel
WHERE - Güncelleme işleminin gerçekleşmesi için sağlanması gereken ek şarttır.Çakışma hedefinin (conflict target), tabloda tanımlanmış gerçek bir unique kısıtla örtüşmesi şarttır. Örneğin
price sütunu unique olarak tanımlanmamışsa, ON CONFLICT(price) ifadesi çalışmaz çünkü SQLite'ın çakışmayı tespit edeceği bir indeks yoktur.DO NOTHING: Kayıt Yoksa Ekle, Varsa Atla
Bu, UPSERT'ün daha yalın bir versiyonudur. Özellikle veri besleme (seeding) veya log tutma işlemlerinde, tekrar eden kayıtların sessizce görmezden gelinmesi istendiğinde kullanılır:
SQL:
CREATE TABLE seen_events (
event_id TEXT PRIMARY KEY,
seen_at TEXT DEFAULT CURRENT_TIMESTAMP
);
INSERT INTO seen_events (event_id) VALUES ('evt-1')
ON CONFLICT(event_id) DO NOTHING;
INSERT INTO seen_events (event_id) VALUES ('evt-1')
ON CONFLICT(event_id) DO NOTHING;
INSERT INTO seen_events (event_id) VALUES ('evt-2')
ON CONFLICT(event_id) DO NOTHING;
SELECT * FROM seen_events;
Normalde aynı
event_id ile ikinci bir INSERT denemesi UNIQUE constraint failed hatasına yol açardı. Fakat DO NOTHING kullanımı sayesinde SQLite bu işlemi hata vermeden atlar; sonuç olarak ne bir hata oluşur ne de yeni bir satır eklenir.Bu durum, "idempotent insert" senaryolarında sıklıkla tercih edilen
INSERT OR IGNORE ile benzerlik gösterir. Ancak UPSERT'ün DO NOTHING kullanımı, WHERE ve RETURNING gibi ifadelerle çok daha esnek bir şekilde çalışabilmektedir.excluded Sanal TablosuBir çakışma meydana geldiğinde, işlem anında iki farklı veri seti bulunur: Tablodaki mevcut eski satır ve eklenmeye çalışılan yeni satır. SQLite, her iki veriye de erişim imkanı tanır.
• Sütun isimleri doğrudan kullanıldığında (
price, name), bu mevcut satırdaki veriyi temsil eder.•
excluded.column ifadesi ise eklenmeye çalışılan ancak reddedilen yeni satırı temsil eder.
SQL:
CREATE TABLE inventory (
sku TEXT PRIMARY KEY,
quantity INTEGER NOT NULL,
updated TEXT
);
INSERT INTO inventory (sku, quantity, updated)
VALUES ('A-100', 5, '2026-04-01')
ON CONFLICT(sku) DO UPDATE SET
quantity = quantity + excluded.quantity,
updated = excluded.updated;
INSERT INTO inventory (sku, quantity, updated)
VALUES ('A-100', 3, '2026-04-02')
ON CONFLICT(sku) DO UPDATE SET
quantity = quantity + excluded.quantity,
updated = excluded.updated;
SELECT * FROM inventory;
Buradaki
quantity = quantity + excluded.quantity mantığı, "mevcut miktara, yeni gelen miktarı ekle" şeklinde okunmalıdır. İki kez ekleme yapıldığında A-100 ürününün toplam miktarı 8 olacaktır. Mevcut verinin üzerine ekleme yaparak birikim sağlamak, UPSERT'ün en etkili kullanım yöntemlerinden biridir.WHERE ile Koşullu UPSERT İşlemleri
Sorgunun sonuna eklenen
WHERE ifadesi, belirli şartlar sağlanmadığında güncelleme işleminin pas geçilmesini sağlar. Bu filtreleme mevcut satır üzerinden yapılır ve yeni gelen verilerle karşılaştırmak için excluded.* referansı kullanılabilir:
SQL:
CREATE TABLE prices (
sku TEXT PRIMARY KEY,
price REAL NOT NULL,
updated_at TEXT NOT NULL
);
INSERT INTO prices VALUES ('A-100', 10.00, '2026-04-01');
INSERT INTO prices (sku, price, updated_at)
VALUES ('A-100', 12.00, '2026-03-15')
ON CONFLICT(sku) DO UPDATE SET
price = excluded.price,
updated_at = excluded.updated_at
WHERE excluded.updated_at > prices.updated_at;
SELECT * FROM prices;
Bu örnekte, yeni gelen satırdaki
updated_at değeri daha eski olduğu için WHERE koşulu sağlanmaz ve güncelleme yapılmaz. Böylece mevcut satır, güncel fiyat bilgisini korumuş olur. Eğer tarihler yer değiştirirse güncelleme işlemi gerçekleşir. Bu yöntem, "sadece daha yeni veri gelirse güncelle" mantığını kurmak için idealdir.SQLite'da Toplu UPSERT Kullanımı
VALUES kısmına birden fazla satır ekleyebilirsiniz ve ON CONFLICT kuralı her satır için ayrı ayrı değerlendirilir:
SQL:
CREATE TABLE products (
sku TEXT PRIMARY KEY,
name TEXT NOT NULL,
price REAL NOT NULL
);
INSERT INTO products VALUES ('A-100', 'Widget', 9.99);
INSERT INTO products (sku, name, price) VALUES
('A-100', 'Widget v2', 10.99),
('A-200', 'Gadget', 14.99),
('A-300', 'Gizmo', 19.99)
ON CONFLICT(sku) DO UPDATE SET
name = excluded.name,
price = excluded.price;
SELECT * FROM products ORDER BY sku;
Kodu çalıştırdığınızda
A-100 kaydı çakıştığı için güncellenirken, A-200 ve A-300 kayıtları yeni olduğu için doğrudan eklenir. Tek bir sorguyla hem toplu ekleme hem de güncelleme yapmak, dış kaynaklarla senkronizasyon işlemleri için oldukça verimlidir.UPSERT ve INSERT OR REPLACE Arasındaki Farklar
INSERT OR REPLACE komutu ilk bakışta UPSERT ile aynı işlemi yapıyor gibi görünse de çalışma mantığı tamamen farklıdır.
SQL:
CREATE TABLE users (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
email TEXT,
notes TEXT
);
INSERT INTO users VALUES (1, 'Ada', 'ada@example.com', 'VIP müşteri');
-- Replace: eski satırı siler, yeni bir tane ekler.
INSERT OR REPLACE INTO users (id, name, email)
VALUES (1, 'Ada Lovelace', 'ada@example.com');
SELECT * FROM users;
Yukarıdaki örnekte
notes verisi kaybolmuştur. Çünkü INSERT OR REPLACE aslında mevcut olan 1 numaralı satırı tamamen siler ve yerine yeni bir satır ekler. Bu durum, sorguda belirtilmeyen tüm sütunların NULL olmasına veya varsayılan değerlerine dönmesine neden olur. Ayrıca bu işlem DELETE trigger'larını tetikler ve ON DELETE cascade kısıtlarını çalıştırır.UPSERT ise satırı silmez, sadece günceller:
SQL:
CREATE TABLE users (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
email TEXT,
notes TEXT
);
INSERT INTO users VALUES (1, 'Ada', 'ada@example.com', 'VIP müşteri');
INSERT INTO users (id, name, email)
VALUES (1, 'Ada Lovelace', 'ada@example.com')
ON CONFLICT(id) DO UPDATE SET
name = excluded.name,
email = excluded.email;
SELECT * FROM users;
Burada
notes sütunu korunmuştur; yalnızca SET bloğunda belirtilen alanlar değiştirilmiştir. Bu nedenle, gerçekten "sil ve yeniden oluştur" davranışı istemediğiniz sürece her zaman UPSERT kullanmanız önerilir.Birden Fazla Çakışma Hedefini Yönetmek
Eğer bir satır birden fazla kısıt üzerinden çakışma potansiyeline sahipse,
ON CONFLICT ifadeleri arka arkaya dizilebilir:
SQL:
CREATE TABLE accounts (
id INTEGER PRIMARY KEY,
username TEXT UNIQUE,
email TEXT UNIQUE,
score INTEGER DEFAULT 0
);
INSERT INTO accounts (username, email, score)
VALUES ('rosa', 'rosa@example.com', 10)
ON CONFLICT(username) DO UPDATE SET score = score + excluded.score
ON CONFLICT(email) DO UPDATE SET score = score + excluded.score;
INSERT INTO accounts (username, email, score)
VALUES ('rosa', 'rosa@example.com', 5)
ON CONFLICT(username) DO UPDATE SET score = score + excluded.score
ON CONFLICT(email) DO UPDATE SET score = score + excluded.score;
SELECT * FROM accounts;
Hangi kısıt önce tetiklenirse ilgili
DO UPDATE bloğu çalışır. Ancak pratikte çoğu tablo tek bir birincil anahtar veya unique sütun üzerinden yönetildiği için bu yönteme nadiren ihtiyaç duyulur.Sık Yapılan Hatalar
Dikkat edilmesi gereken bazı kritik noktalar:
• Uygun bir unique indeks yoksa UPSERT çalışmaz.
ON CONFLICT(col) kullanabilmek için col sütununun ya PRIMARY KEY ya da UNIQUE olarak tanımlanmış olması gerekir; aksi takdirde "no such constraint" hatası alınır.•
DO UPDATE sadece çakışma olduğunda devreye girer. Bu, ekleme işlemine alternatif bir yoldur; ek bir adım değildir. Eğer anahtar ilk kez ekleniyorsa sadece insert gerçekleşir.•
excluded tablosu sadece okunabilir. Bu tablodan veri alabilirsiniz ancak ona veri yazamazsınız. SET kısmındaki hedef her zaman tablodaki mevcut satırdır.• Otomatik artan
INTEGER PRIMARY KEY (rowid) kullanımı: Eğer id değerini siz belirtmezseniz, her işlem yeni bir id oluşturacağı için çakışma yaşanmaz. UPSERT'ün anlamlı olması için çakışan sütunun değerinin açıkça belirtilmesi gerekir.Sıradaki Konu: RETURNING
UPSERT işlemi sonucunda hangi satırların eklendiğini veya güncellendiğini standart olarak göremezsiniz. Bu bilgiyi, etkilenen satırları sorgu anında geri döndüren
RETURNING cümleciği ile elde edebilirsiniz; böylece ayrıca bir SELECT sorgusu çalıştırmanıza gerek kalmaz. Bir sonraki bölümde bunu inceleyeceğiz.