SQLite RETURNING: INSERT, UPDATE, DELETE Sonuçlarını Alın

Az Önce Ne Olduğunu Görmenin Bir Yolu

Bir INSERT, UPDATE ya da DELETE çalıştırdığınızda SQLite size kaç satırın etkilendiğini söyler — ama hangi satırların etkilendiğini ya da satırların son hâlinin nasıl göründüğünü söylemez. Klasik çözüm, hemen ardından bir SELECT çekmek. Bu da iki ayrı sorgu, iki gidiş-dönüş ve arada başka birinin satırı değiştirebileceği küçük bir yarış penceresi anlamına geliyor.

İşte RETURNING tam da bu sorunu çözüyor. Yazma sorgunuzun sonuna ekliyorsunuz, geri istediğiniz sütunları listeliyorsunuz ve SQLite size etkilenen satırları sanki üzerlerinde bir SELECT çalıştırmışsınız gibi geri veriyor:

CREATE TABLE notes (
    id INTEGER PRIMARY KEY,
    title TEXT NOT NULL,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO notes (title) VALUES ('İlk not')
RETURNING id, title, created_at;

Tek sorgu, tek gidiş-dönüş ve hem üretilen id'yi hem de veritabanının sizin için doldurduğu varsayılan created_at değerini geri alıyorsunuz.

RETURNING, SQLite 3.35.0 ile (Mart 2021) eklendi. Eğer sorgunuz sözdizimi hatası verip reddediliyorsa, SELECT sqlite_version(); çıktısına bakın — eski sürümler bu anahtar kelimeyi tanımıyor.

Üretilen ID'yi Geri Alma

RETURNING denildiğinde akla gelen ilk kullanım, kayıt eklerken otomatik üretilen birincil anahtarı anında yakalamaktır:

CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    email TEXT NOT NULL UNIQUE
);

INSERT INTO users (email) VALUES ('rosa@example.com')
RETURNING id;

RETURNING ifadesi gelmeden önce, kayıt eklemek için önce INSERT çalıştırıp ardından aynı bağlantı üzerinde last_insert_rowid() (veya kullandığınız sürücünün karşılığını) çağırırdınız. Bu yöntem hâlâ çalışıyor ama bağlantı durumuna bağlı bir tür sihir; bağlantı havuzları ya da thread'ler işin içine girince kolayca yanlış sonuç verebiliyor. RETURNING id ise açık, doğrudan ifadenin kendisine bağlı ve bağlantıyı kim yönetirse yönetsin aynı şekilde çalışıyor.

Tablonuzda açıkça INTEGER PRIMARY KEY tanımlı değilse bile, örtük satır kimliğini şu şekilde alabilirsiniz:

CREATE TABLE logs (event TEXT);

INSERT INTO logs (event) VALUES ('başlatma')
RETURNING rowid, event;

Her standart SQLite tablosunun bir rowid değeri vardır ve RETURNING bu değeri sana geri verir.

Birden Fazla Sütun ve İfade

RETURNING ifadesi, bir SELECT sorgusundaki sütun listesiyle aynı yapıyı kabul eder. İsterseniz sütunları tek tek yazarsınız, isterseniz * kullanırsınız; ifade oluşturup bunlara takma ad da verebilirsiniz:

CREATE TABLE line_items (
    id INTEGER PRIMARY KEY,
    product TEXT NOT NULL,
    price REAL NOT NULL,
    quantity INTEGER NOT NULL
);

INSERT INTO line_items (product, price, quantity)
VALUES ('Defter', 4.50, 3)
RETURNING id, product, price * quantity AS subtotal;

RETURNING *, veritabanının kendi doldurduğu varsayılanlar dahil her şeyi geri almak istediğinde işine yarar; üstelik kolonları tek tek yazmana da gerek kalmaz:

CREATE TABLE events (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO events (name) VALUES ('giriş')
RETURNING *;

Yeni id'yi, ilettiğiniz name'i ve SQLite'ın hesapladığı timestamp değerini bir arada görürsünüz.

UPDATE ile RETURNING kullanımı

UPDATE ifadesinde RETURNING, satırın güncellenmiş halini döndürür — yani değişiklikler uygulandıktan sonraki değerleri elinize verir:

CREATE TABLE accounts (
    id INTEGER PRIMARY KEY,
    name TEXT,
    balance INTEGER NOT NULL
);
INSERT INTO accounts (name, balance) VALUES ('Ada', 100), ('Boris', 50);

UPDATE accounts
SET balance = balance + 25
WHERE name = 'Ada'
RETURNING id, name, balance;

Aynı sorguda Ada'nın eski bakiyesi olan 100 değil, yeni bakiyesi olan 125 dönüyor. İşte tam da bu yüzden RETURNING, atomik sayaçlar ve borç/alacak işlemleri için biçilmiş kaftan — önce oku, hesapla, yaz, sonra tekrar oku gibi bir döngüye girmene gerek kalmıyor.

WHERE koşulu birden fazla satıra uyuyorsa, etkilenen her satır için bir satır geri dönüyor:

CREATE TABLE products (id INTEGER PRIMARY KEY, name TEXT, price REAL);
INSERT INTO products (name, price) VALUES ('A', 10), ('B', 20), ('C', 30);

UPDATE products
SET price = price * 1.1
RETURNING id, name, price;

Üç satır girdi, üç satır çıktı. Ama sıraya güvenme — belirli bir sıralama lazımsa, sonucu istemci tarafında sırala.

DELETE ile RETURNING kullanımı

DELETE işleminde RETURNING, sana satırları silinmeden hemen önceki hâliyle verir. Arşivleme, denetim kaydı tutma ya da neyin silindiğini teyit etmek için epey işe yarar:

CREATE TABLE sessions (
    id INTEGER PRIMARY KEY,
    user_id INTEGER NOT NULL,
    expires_at TEXT NOT NULL
);
INSERT INTO sessions (user_id, expires_at) VALUES
    (1, '2024-01-01'), (2, '2024-01-02'), (3, '2026-01-01');

DELETE FROM sessions
WHERE expires_at < '2025-01-01'
RETURNING id, user_id, expires_at;

Süresi dolmuş iki oturumu, tablodan silinmiş olmalarına rağmen tüm alanlarıyla birlikte geri alırsınız. Bunları başka bir yere taşımak istiyorsanız, bu bir arşiv tablosu için biçilmiş kaftandır — sonucu okuyup aynı işlem (transaction) içinde başka bir tabloya ekleyebilirsiniz.

UPSERT ile RETURNING kullanımı

RETURNING, INSERT ... ON CONFLICT ... DO UPDATE ile de sorunsuz çalışır. Dönen satır, hangi dal çalıştıysa onu yansıtır — yeni eklenen kayıt mı yoksa çakışma sonucu güncellenen kayıt mı:

CREATE TABLE counters (
    name TEXT PRIMARY KEY,
    value INTEGER NOT NULL DEFAULT 0
);

INSERT INTO counters (name, value) VALUES ('visits', 1)
ON CONFLICT(name) DO UPDATE SET value = value + 1
RETURNING name, value;

Bu ifadeyi iki kez çalıştırın. İlkinde satır eklenir ve ('visits', 1) döner. İkincisinde çakışma tetiklenir, değer bir artırılır ve geriye ('visits', 2) gelir. Her iki durumda da tek bir ifade çalıştırırsınız ve tek bir satır geri alırsınız — devam etmeden önce "ekleme mi yapıldı yoksa güncelleme mi?" diye sormaya gerek kalmaz.

Bu, SQLite'ta "değer yoksa oluştur, varsa mevcut değeri ver" işlemini ekstra sorgu atmadan yapmanın en temiz yoludur.

Bilmeniz Gereken Birkaç Detay

İnsanları sıklıkla şaşırtan birkaç ince nokta var:

• RETURNING, INSERT ve UPDATE için satırı her zaman değişiklik sonrası, DELETE için ise değişiklik öncesi haliyle gösterir. Tersini istemenin bir söz dizimi yok.
• Dönen satırların sırası garanti değildir. Sıra önemliyse istemci tarafında ORDER BY ekleyin.
• RETURNING'i bir alt sorgunun içine koyamazsınız. Bir ifade değil, yazma ifadesinin en üst düzey bir parçasıdır.
• RETURNING, BEFORE tetikleyicilerinin değiştirdiği veriyi yansıtmaz — gerçekte yazılan değerleri döndürür. AFTER tetikleyicileri ise yazma ile satırın dönüşü arasında çalışır.
• Generated (üretilmiş) sütunlar ve DEFAULT değerleri sonuçta görünür. Veritabanının sizin yerinize ne doldurduğunu anlamak için RETURNING * kullanmak tam da bu yüzden pratiktir.

Sırada: CSV Verisini İçe Aktarma

RETURNING, tek satır veya birkaç satır yazıp sonucu hemen görmek istediğinizde harikadır. Ama bir dosyadan binlerce satır yüklüyorsanız iş SQLite'ın CSV içe aktarma araçlarına düşer — bir sonraki sayfanın konusu da bu.