PostgreSQL'de tekrarlayan programlar ve zaman dilimleri: desenler

Neden zaman dilimleri ve tekrarlayan etkinlikler yanlış gider

Çoğu takvim hatası matematik hatası değildir. Anlam hatasıdır. Bir şeyi saklarsınız (zamandaki bir anı), ama kullanıcılar başka bir şey bekler (belirli bir yerdeki yerel saat). Bu fark, tekrarlayan programların ve zaman dilimlerinin testlerde doğru görünüp gerçek kullanıcılar geldiğinde bozulmasının nedenidir.

Yaz saati uygulaması (DST) klasik tetikleyicidir. "Her pazar 09:00" gibi bir kurallar, "başlangıç zaman damgasından itibaren her 7 günde bir" ile aynı değildir. Ofset değiştiğinde bu iki fikir bir saat kayar ve takviminiz sessizce yanlış olur.

Seyahat ve karışık zaman dilimleri ekstra bir katman ekler. Bir rezervasyon fiziksel bir yere bağlanmış olabilir (Chicago'daki bir kuaför koltuğu), oysa onu görüntüleyen kişi Londra'dadır. Mekan bazlı bir programı kişi bazlı kabul ederseniz, yerel saati en az bir taraf için yanlış gösterirsiniz.

Yaygın hata yolları:

• Kaydedilmiş zamana bir aralık ekleyerek tekrarları üretiyorsunuz, sonra DST değişiyor.
• Zaman dilimi kuralları olmadan "yerel saatleri" saklıyorsunuz, böylece istenen anları daha sonra yeniden oluşturamazsınız.
• Hiçbir zaman DST sınırını geçmeyen tarihlerle test ediyorsunuz.
• "etkinlik zaman dilimi", "kullanıcı zaman dilimi" ve "sunucu zaman dilimi"ni tek bir sorguda karıştırıyorsunuz.

Bir şema seçmeden önce, ürününüz için "doğru"nun ne anlama geldiğine karar verin.

Bir rezervasyon için "doğru" genellikle şunu ifade eder: randevu, mekanın zaman diliminde hedeflenen duvar saatiyle gerçekleşir ve bunu görüntüleyen herkes doğru dönüşümü görür.

Bir vardiya için "doğru" sıklıkla şunu ifade eder: vardiya, çalışan seyahat etse bile mağaza için sabit bir yerel saatte başlar.

Bu tek karar (programın bir yere mi yoksa bir kişiye mi bağlı olduğu) geri kalan her şeyi yönlendirir: neyi saklayacağınız, tekrarları nasıl üreteceğiniz ve takvim görünümünü bir saatlik sürprizler olmadan nasıl sorgulayacağınız.

Doğru zihinsel modeli seçin: an vs yerel saat

Birçok hata iki farklı zaman fikrinin karıştırılmasından kaynaklanır:

• Bir an: mutlak, tek bir kez gerçekleşen bir an.
• Yerel saat kuralı: "Paris'te her Pazartesi 09:00" gibi bir duvar saati.

Bir an her yerde aynıdır. "2026-03-10 14:00 UTC" bir an. Video çağrıları, uçuş kalkışları ve "bu bildirimi tam olarak bu anda gönder" türü işlemler genellikle anar.

Yerel saat, bir yerdeki saatteki okumadır. "Hafta içi her gün Avrupa/Paris'te 09:00" bir yerel saattir. Mağaza saatleri, tekrar eden dersler ve personel vardiyaları genelde bir konumun zaman dilimine sabitlenir. Zaman dilimi bir görüntü tercihinden ziyade anlamın parçasıdır.

Basit bir kural:

• Etkinlik dünyada tek bir gerçek anda gerçekleşmeliyse başlangıç/bitişi anlar (timestamptz) olarak saklayın.
• Etkinlik bir yerdeki saate göre takip edilecekse yerel tarih ve yerel saati artı bir bölge kimliği olarak saklayın; meydana gelen örnekleri oluştururken bunları anlara çevirin.
• Kullanıcılar seyahat ediyorsa, görüntüleyiciye kendi zona'sında gösterin ama programı bağlı olduğu zona'ya sabitleyin.
• "+02:00" gibi ofsetlerden bir zona tahmin etmeyin. Ofsetler DST kurallarını içermez.

Örnek: bir hastane vardiyası "Pzt-Cum 09:00-17:00 America/New_York" ise DST değişim haftasında vardiya yerel olarak hâlâ 9-5 olur, UTC anları bir saat hareket eder.

PostgreSQL'de önemli tipler (ve kaçınılması gerekenler)

Çoğu takvim hatası yanlış sütun tipiyle başlar. Anahtar, gerçek bir an ile duvar saati beklentisini ayırmaktır.

Gerçek anlar için timestamptz kullanın: rezervasyonlar, giriş zamanları, bildirimler ve kullanıcılar/regionlar arasında karşılaştırdığınız her şey. PostgreSQL bunu mutlak bir an olarak saklar ve görüntüleme için çevirir; böylece sıralama ve örtüşme kontrolleri beklenildiği gibi çalışır.

Yerel duvar saati değeri olanlar için timestamp without time zone kullanmayın; bunun yerine yalnızca zaman-of-day için time ve ayrıca bir zaman dilimi kimliği saklayın. (Genelde timestamp without time zone yerine time + date + tzid kombinasyonu uygundur.) Tekrar eden örüntüler için temel tipler yardımcı olur:

• date sadece gün bazlı istisnalar için (tatiller)
• time günlük başlangıç saati için
• interval süreler için (örneğin 6 saatlik vardiya)

Zaman dilimini bir IANA adı (örneğin America/New_York) olarak text sütununda (veya küçük bir lookup tablosunda) saklayın. -0500 gibi ofsetler yeterli değildir çünkü yaz saati kurallarını taşımazlar.

Birçok uygulama için pratik set:

• Randevuların başlangıç/bitiş anları için timestamptz
• İstisna günleri için date
• Tekrarlayan yerel başlangıç saati için time
• Süre için interval
• IANA zaman dilimi kimliği için text

Rezervasyon ve vardiya uygulamaları için veri modeli seçenekleri

En iyi şema, programların ne sıklıkla değiştiğine ve kullanıcıların ne kadar ileriye baktığına bağlıdır. Genelde çok sayıda satır yazmak ile okurken üretmek arasında seçim yaparsınız.

Seçenek A: her örneği saklayın

Her vardiya veya rezervasyon için (zaten genişletilmiş) bir satır ekleyin. Sorgulaması ve anlaşılması kolaydır. Dezavantajı çok yazma ve bir kural değiştiğinde çok sayıda güncelleme gerektirmesidir.

Bu yaklaşım, etkinliklerin çoğunlukla tek seferlik olduğu veya örnekleri yalnızca kısa vadeye (örneğin 30 gün) oluşturduğunuz durumlarda iyi çalışır.

Seçenek B: kuralı saklayın, okuma zamanında genişletin

Bir program kuralını saklayın (örneğin "haftada Pazartesi ve Çarşamba 09:00 America/New_York") ve istenen aralıkta örnekleri isteğe bağlı oluşturun.

Depolama hafif ve esnektir, ancak sorgular daha karmaşık olur. Aylık görünümler yavaşlayabilir, önbellek yoksa.

Seçenek C: kural + önbelleğe alınmış örnekler (hibrit)

Kuralı tek gerçek kaynağınız olarak tutun ve aynı zamanda kaydırmalı bir pencere için (örneğin 60-90 gün) oluşturulmuş örnekleri saklayın. Kural değiştiğinde önbelleği yeniden oluşturun.

Bu, vardiya uygulamaları için güçlü bir varsayılandır: aylık görünümler hızlı kalır, ama düzenleme için tek bir yeriniz olur.

Pratik tablo seti:

• schedule: owner/resource, time zone, local start time, duration, recurrence rule
• occurrence: start_at timestamptz, end_at timestamptz ile genişletilmiş örnekler ve durum
• exception: "bu tarihi atla" veya "bu tarih farklı" işaretleri
• override: per-örnek düzenlemeler (değişmiş başlangıç saati, personel değişimi, iptal bayrağı)
• (opsiyonel) schedule_cache_state: son oluşturulan aralık, hangi aralığın doldurulması gerektiğini bilmeniz için

Takvim aralığı sorguları için "bu pencere içindekileri göster" odaklı indeksleyin:

• occurrence üzerinde: btree (resource_id, start_at) ve sıklıkla btree (resource_id, end_at)
• "aralıkla örtüşüyor" sorguları varsa: üretilmiş bir tstzrange(start_at, end_at) ve gist indeksi

Tekrar kurallarını kırılgan hale getirmeden temsil etmek

Tekrarlayan programlar kural çok karmaşık, çok esnek veya sorgulanamaz bir blob olarak saklandığında bozulur. İyi bir kural formatı, uygulamanızın doğrulayabileceği ve ekibinizin hızlıca açıklayabileceği bir formattır.

İki yaygın yaklaşım:

• Gerçekten desteklediğiniz desenler için basit özel alanlar (haftalık vardiyalar, aylık fatura tarihleri)
• Çok sayıda kombinasyonu desteklemeniz gerekiyorsa iCalendar-benzeri kurallar (RRULE tarzı)

Pratik bir orta yol: sınırlı bir seçenek setine izin verin, bunları sütunlarda saklayın ve herhangi bir RRULE dizesini yalnızca alışveriş için kullanın.

Örneğin, haftalık bir vardiya kuralı şu alanlarla ifade edilebilir:

• freq (daily/weekly/monthly) ve interval (her N)
• byweekday (0-6 dizisi veya bitmask)
• aylık kurallar için isteğe bağlı bymonthday (1-31)
• starts_at_local (kullanıcının seçtiği yerel tarih+zaman) ve tzid
• isteğe bağlı until_date veya count (ikisini de desteklemeyin, gerçekten gerekmedikçe)

Sınırlar için, her örneğe bir süre saklamayı tercih edin (örneğin 8 saat) yerine her örnek için bir bitiş zaman damgası saklamak. Süre, saatler değiştiğinde sabit kalır. Örnek başına bitişi şu şekilde hesaplayabilirsiniz: örnek başlangıç + süre.

Kural genişletilirken güvenli ve sınırlı tutun:

• Sadece window_start ve window_end içinde genişletin.
• Gece boyu olaylar için küçük bir tampon ekleyin (örneğin 1 gün).
• Maksimum örnek sayısından sonra durun (örneğin 500).
• Üretmeden önce adayları filtreleyin (tzid, freq, başlangıç tarihi ile) ve sonra üretin.

Adım adım: DST güvenli tekrar eden bir program oluşturma

Güvenilir bir desen şöyle çalışır: her örneği önce yerel takvim fikri olarak düşünün (tarih + yerel saat + mekanın zaman dilimi), sonra sıralama, çakışma veya gösterim gerektiğinde anlara çevirin.

1. UTC tahminleri değil, yerel niyeti saklayın

Programın konum zaman dilimini (IANA adı gibi America/New_York) ve bir yerel başlangıç saatini (09:00) kaydedin. Bu yerel saat işin anlamıdır, DST değiştiğinde bile.

Ayrıca bir süre ve kural için net sınırlar (başlangıç tarihi ve ya bir bitiş tarihi ya da tekrar sayısı) saklayın. Sınırlar "sonsuz genişleme" hatalarını önler.

2. İstisnaları ve geçersiz kılmaları ayrı modelleyin

İki küçük tablo kullanın: birisi atlanan tarihler için, diğeri değiştirilmiş örnekler için. Bunları schedule_id + local_date ile anahtarlandırın ki orijinal tekrarla temiz eşleştirme yapabilesiniz.

Pratik bir yapı şöyle görünür:

-- core schedule
-- tz is the location time zone
-- start_time is local wall-clock time
schedule(id, tz text, start_date date, end_date date, start_time time, duration_mins int, by_dow int[])

schedule_skip(schedule_id, local_date date)

schedule_override(schedule_id, local_date date, new_start_time time, new_duration_mins int)

3. Sadece istenen pencere içinde genişletin

Gördüğünüz aralık (hafta, ay) için aday yerel tarihleri üretin. Gün-of-week ile filtreleyin, sonra atlamaları ve geçersiz kılmaları uygulayın.

WITH days AS (
  SELECT d::date AS local_date
  FROM generate_series($1::date, $2::date, interval '1 day') d
), base AS (
  SELECT s.id, s.tz, days.local_date,
         make_timestamp(extract(year from days.local_date)::int,
                        extract(month from days.local_date)::int,
                        extract(day from days.local_date)::int,
                        extract(hour from s.start_time)::int,
                        extract(minute from s.start_time)::int, 0) AS local_start
  FROM schedule s
  JOIN days ON days.local_date BETWEEN s.start_date AND s.end_date
  WHERE extract(dow from days.local_date)::int = ANY (s.by_dow)
)
SELECT b.id,
       (b.local_start AT TIME ZONE b.tz) AS start_utc
FROM base b
LEFT JOIN schedule_skip sk
  ON sk.schedule_id = b.id AND sk.local_date = b.local_date
WHERE sk.schedule_id IS NULL;

4. Görüntüleyici için dönüştürmeyi en son yapın

Sıralama, çakışma kontrolleri ve rezervasyonlar için start_utc'yi timestamptz olarak tutun. Yalnızca gösterim sırasında, görüntüleyicinin zaman dilimine çevirin. Bu, DST sürprizlerini engeller ve takvim görünümlerini tutarlı tutar.

Doğru bir takvim görünümü üretme sorgu desenleri

Bir takvim ekranı genellikle bir aralık sorgusudur: "bana from_ts ile to_ts arasındakileri göster." Güvenli bir desen:

1. Sadece o penceredeki adayları genişletin.
2. İstisna/geçersiz kılmaları uygulayın.
3. start_at ve end_at sütunlarını timestamptz olarak çıktılayın.

Günlük veya haftalık genişletme için generate_series

Basit haftalık kurallar için ("her Pzt-Cum 09:00 yerel") önce programın zaman diliminde yerel tarihleri üretin, sonra her yerel tarih + yerel saati bir ana dönüştürün.

-- Inputs: :from_ts, :to_ts are timestamptz
-- rule.tz is an IANA zone like 'America/New_York'
WITH bounds AS (
  SELECT
    (:from_ts AT TIME ZONE rule.tz)::date AS from_local_date,
    (:to_ts   AT TIME ZONE rule.tz)::date AS to_local_date
  FROM rule
  WHERE rule.id = :rule_id
), days AS (
  SELECT d::date AS local_date
  FROM bounds, generate_series(from_local_date, to_local_date, interval '1 day') AS g(d)
)
SELECT
  (local_date + rule.start_local_time) AT TIME ZONE rule.tz AS start_at,
  (local_date + rule.end_local_time)   AT TIME ZONE rule.tz AS end_at
FROM rule
JOIN days ON true
WHERE EXTRACT(ISODOW FROM local_date) = ANY(rule.by_isodow);

Bu iyi çalışır çünkü timestamptz'e dönüşüm her örnek için ayrı yapılır; böylece DST kaymaları doğru güne uygulanır.

Daha karmaşık kurallar için recursive CTE

Kurallar "n'inci hafta günü" gibi bağımlılıklar, boşluklar veya özel aralıklar gerektiriyorsa, bir recursive CTE to_ts'yi geçene kadar bir sonraki örneği üretebilir. Rekürsiyonu pencereye sabitleyin ki sonsuza kadar çalışamasın.

Aday satırları elde ettikten sonra, istisna ve geçersiz kılmaları (rule_id, start_at) veya yerel anahtar (rule_id, local_date) ile birleştirerek uygulayın. İptal kaydı varsa satırı düşürün. Geçersiz kılma varsa start_at/end_at'i geçersiz kılma değerleriyle değiştirin.

Önemli performans desenleri:

• Aralığı erken kısıtlayın: önce kuralları filtreleyin, sonra sadece [from_ts, to_ts) içinde genişletin.
• İstisna/geçersiz kılma tablolarını (rule_id, start_at) veya (rule_id, local_date) üzerinde indeksleyin.
• Bir ay görünümü için yıllarca veriyi genişletmekten kaçının.
• Kurallar değiştiğinde önbelleği temizleyebiliyorsanız, genişletilmiş örnekleri önbelleğe alın.

İstisnaları ve geçersiz kılmaları temiz yönetme

Tekrarlayan programlar, güvenle kırılabiliyorsa faydalıdır. Rezervasyon ve vardiya uygulamalarında "normal" hafta temel kuraldır; geri kalan her şey istisnadır: tatiller, iptaller, taşınan randevular veya personel değişimleri. İstisnalar sonradan eklenirse, takvim görünümleri kayar ve kopyalar görünür.

Üç kavramı ayrı tutun:

• Baz program (tekrar eden kural ve zaman dilimi)
• Atlamalar (olması gereken, ama olmayacak örnekler)
• Geçersiz kılmalar (var olan örneklerin değişmiş ayrıntıları)

Öncelik sırasını sabitleyin

Bir sıra seçin ve tutarlı kalın. Yaygın bir tercih:

1. Temel tekrarlar için adayları üretin.
2. Geçersiz kılmaları uygulayın (üretileni değiştirin).
3. Atlamaları uygulayın (gizleyin).

Kuralı kullanıcıya bir cümlede açıklanabilir kılın.

Geçersiz kılma bir örneği değiştirirken çoğaltmaları önleyin

Çoğaltmalar genelde sorgunun hem üretilmiş örneği hem de geçersiz kılma satırını döndürmesinden ortaya çıkar. Bunu kararlı bir anahtarla önleyin:

• Her üretilmiş örneğe (schedule_id, local_date, start_time, tzid) gibi kararlı bir anahtar verin.
• Bu anahtarı geçersiz kılma satırında "orijinal örnek anahtarı" olarak saklayın.
• Her temel örnek için yalnızca bir geçersiz kılma olmasını sağlamak üzere unique constraint ekleyin.

Sonra sorgularda, eşleşen bir geçersiz kılma olan üretilmiş örnekleri hariç tutun ve geçersiz kılma satırlarını birleştirin.

Denetlenebilirliği sürdürün

İstisnalar tartışmaların olduğu yerlerdir ("Vardiyamı kim değiştirdi?"). schedule_skip ve schedule_override üzerinde created_by, created_at, updated_by, updated_at ve isteğe bağlı bir neden alanı ekleyin.

Bir saatlik hatalara neden olan yaygın yanlışlar

Çoğu bir saatlik hata, zamanı iki anlamını karıştırmaktan gelir: bir an (UTC zaman çizelgesindeki bir nokta) ve yerel saat okuması (her Pazartesi 09:00 New York gibi).

Klasik bir hata, yerel duvar saati kuralını timestamptz olarak saklamaktır. "New York'ta Pazartesi 09:00"u tek bir timestamptz olarak kaydederseniz, zaten belirli bir tarih (ve DST durumu) seçmiş olursunuz. Daha sonra gelecekteki Pazartesileri üretirken orijinal niyet ("her zaman yerelde 09:00") kaybolur.

Sık diğer bir neden de sabit UTC ofsetlerine (-05:00) güvenmektir; bunlar IANA bölge adları gibi DST kurallarını içermez. Bölge kimliğini (örnek: America/New_York) saklayın ve PostgreSQL'in her tarih için doğru kuralları uygulamasına izin verin.

Ne zaman dönüştüreceğinize dikkat edin. Tekrar üretirken çok erken UTC'ye çevirirseniz, bir DST ofsetini dondurabilir ve her örneğe uygulayabilirsiniz. Daha güvenli desen: örnekleri yerel terimlerle (tarih + yerel saat + zona) üretin, sonra her örneği an'a dönüştürün.

Tekrarlanan şekilde tekrar eden hatalar:

• Tekrarlayan yerel saat-of-day'ı saklamak için timestamptz kullanmak (asıl ihtiyaç time + tzid + kural idi).
• Yalnızca bir ofset saklamak, IANA bölge adı saklamamak.
• Üretim sırasında dönüştürme yapmak yerine en sonda dönüştürmek.
• "Sonsuza" kadar tekrarları genişletmek.
• DST başlangıç ve bitiş haftalarını test etmemek.

Çoğu sorunu yakalayan basit bir test: DST olan bir bölge seçin, haftalık 09:00 vardiya oluşturun ve DST değişimini geçen iki aylık takvimi render edin. Her örneğin yerel saatte 09:00 olduğunu doğrulayın; altta yatan UTC anları farklı olsa bile.

Yayına almadan önce hızlı kontrol listesi

Yayın öncesi temel kontroller:

• Her program bir yerle (veya iş birimiyle) ilişkilendirilmiş, programın kendisinde adlandırılmış bir zaman dilimi var.
• IANA bölge kimlikleri (America/New_York gibi) saklanıyor; ham ofsetler değil.
• Tekrar genişletme sadece istenen aralık içinde gerçekleşiyor.
• İstisna ve geçersiz kılmalar için tek, belgelendirilmiş bir öncelik sırası var.
• DST değişim haftalarını ve programın olduğu zamandan farklı bir zaman dilimindeki görüntüleyiciyi test ettiniz.

Gerçekçi bir kuru çalıştırma yapın: Europe/Berlin'de haftalık 09:00 vardiyası olan bir mağaza, America/Los_Angeles'tan bir yönetici tarafından görüntüleniyor. Her hafta Berlin yerelinde 09:00 olarak kaldığını, iki tarafın farklı tarihlerde DST değiştirmesine rağmen doğrulayın.

Örnek: tatil ve DST değişimi içeren haftalık vardiyalar

Küçük bir klinik şu tekrarlayan vardiyayı çalıştırıyor: her Pazartesi 09:00-17:00 klinik yerel zaman diliminde (America/New_York). Klinik bir Pazartesi için kapalı (tatil). Bir personel iki hafta Avrupa'da seyahat ediyor, ama klinik takvimi personelin konumuna değil klinik duvar saatine bağlı kalmak zorunda.

Bunu doğru yapmak için:

• Tekrarlayan kuralı yerel tarihlere sabitleyin (hafta günü = Pazartesi, yerel saatler = 09:00–17:00).
• Program zaman dilimini (America/New_York) saklayın.
• Kural için etkili bir başlangıç tarihi saklayın ki kuralın açık bir sabitleyicisi olsun.
• Tatil Pazartesisini iptal etmek için bir istisna saklayın (ve tek seferlik değişiklikler için geçersiz kılmalar saklayın).

Şimdi DST değişimini içeren iki haftalık bir takvim aralığı render edin. Sorgu o yerel tarihlerde Pazartesileri üretir, klinik yerel saatlerini iliştirir, sonra her örneği mutlak an (timestamptz) haline çevirir. Dönüştürme her örnek için ayrı yapıldığı için DST doğru günde uygulanır.

Farklı görüntüleyiciler aynı an için farklı yerel saatler görür:

• Los Angeles'taki bir yönetici saati daha erken görür.
• Berlin'deki seyahat eden personel saati daha geç görür.

Klinik yine de istediğini alır: her iptal edilmeyen Pazartesi New York saatiyle 09:00–17:00.

Sonraki adımlar: uygulayın, test edin ve sürdürülebilir tutun

Zaman yaklaşımınızı erken kilitleyin: yalnız kural mı saklayacaksınız, yalnız örnek mi saklayacaksınız yoksa hibrit mi? Birçok rezervasyon ve vardiya ürünü için hibrit iyi çalışır: kuralı tek gerçek kaynak olarak tutun, gerekiyorsa kaydırmalı bir önbellek saklayın ve istisnalar ile geçersiz kılmaları somut satırlar olarak saklayın.

"Zaman sözleşmenizi" tek bir yerde yazılı hale getirin: ne an sayılır, ne yerel duvar saati sayılır ve her birini hangi sütun saklar. Bu, bir uç noktanın yerel zaman döndürüp diğerinin UTC döndürmesi gibi sürüklenmeyi önler.

Tekrar üretimini tek bir modül olarak tutun, dağınık SQL parçaları halinde değil. "Yerel 09:00" yorumunu değiştirmeniz gerekirse, tek bir yer güncellemek istersiniz.

Eğer her şeyi elle kodlamadan zamanlama aracı inşa ediyorsanız, AppMaster (appmaster.io) bu tür işler için pratik bir uyum sağlar: Data Designer'da veritabanını modelleyebilir, iş süreçlerinde tekrar ve istisna mantığını kurabilir ve hâlâ gerçek üretilebilir backend ve uygulama koduna sahip olabilirsiniz.