Tüm Ürünler
Search
Belge Merkezi

PolarDB:Lua script usage guide

Son Güncelleme:Oct 07, 2026

PolarDB for MySQL içindeki Redis uyumlu protokol Orca, tek bir veritabanı etkileşiminde birden çok komutun atomik olarak çalıştırılması için Lua betiklerini destekler. Lua betiklerini; dağıtılmış kilitler, hız sınırlayıcılar ve koşullu güncellemeler uygulamak üzere kullanın. Bu yaklaşım, çoklu gidiş-dönüşlerin neden olduğu gecikme süresi ve yarış durumu risklerini ortadan kaldırır.

Ön koşullar

Başlamadan önce aşağıdakilere sahip olduğunuzdan emin olun:

  • MySQL 8.0.2 sürümünü ve 8.0.2.2.33 veya üzeri küçük motor sürümünü çalıştıran bir PolarDB kümesi

  • Read/Write seçeneği Read/Write (Automatic Read/Write Splitting) olarak ayarlanmış bir ORCA uç noktası

Temel kavramlar

Atomisite — Bir Lua betiğindeki tüm komutlar tek ve bölünemez bir birim olarak çalıştırılır. Hiçbir başka komut veya betik yürütmeyi kesintiye uğratamaz; bu sayede kısmi yazma işlemleri ve ara durumlar önlenir.

Betik önbelleğe alma — Bir betiği SHA1 toplam değerini almak için SCRIPT LOAD ile bir kez yükleyin, ardından yalnızca kısa SHA1 değerini kullanarak EVALSHA ile tekrar tekrar çağırın. Bu yöntem, her çağrıda tam betiği göndermeye kıyasla ağ trafiğini azaltır.

Betik önbelleği değişkenliği — Betik önbelleği kalıcı değildir. Küme yeniden başlatıldığında, yüksek kullanılabilirlik (HA) yük devretme işlemi gerçekleştiğinde veya açık bir SCRIPT FLUSH çağrısı yapıldığında temizlenir. Uygulamanızı, NOSCRIPT hatalarını yakalayacak ve betikleri otomatik olarak yeniden yükleyecek şekilde tasarlayın.

Komutlar

Tüm Lua betiği komutları aynı parametre kuralını izler: anahtar adlarını KEYS[] üzerinden, diğer bağımsız değişkenleri ise ARGV[] üzerinden iletin. Dizi indeksleri 1'den başlar.

Tam Redis teknik özellikleri için redis.io üzerindeki Scripting with Lua ve EVAL command reference belgelerine bakın.

Komut Sözdizimi Açıklama
EVAL EVAL script numkeys [key [key ...]] [arg [arg ...]] Bir Lua betiğini doğrudan çalıştırın. numkeys parametresi, kendisinden sonra gelen KEYS[] bağımsız değişkenlerinin sayısını belirten negatif olmayan bir tamsayıdır.
EVAL_RO EVAL_RO script numkeys [key [key ...]] [arg [arg ...]] Bir Lua betiğini salt okunur modda çalıştırın. Betik yazma komutları içeriyorsa hata döndürür. Okuma/yazma ayrıştırma senaryolarında bu komutu kullanın.
EVALSHA EVALSHA sha1 numkeys [key [key ...]] [arg [arg ...]] Önbelleğe alınmış bir betiği SHA1 toplam değeriyle çalıştırın. Betik önbellekte yoksa NOSCRIPT hatası döndürür; betiği EVAL veya SCRIPT LOAD ile yeniden yükleyip tekrar deneyin.
EVALSHA_RO EVALSHA_RO sha1 numkeys [key [key ...]] [arg [arg ...]] Önbelleğe alınmış bir betiği salt okunur modda çalıştırın. EVALSHA ile aynı davranışı sergiler ancak EVAL_RO komutunun yazma kısıtlamasına tabidir.
SCRIPT LOAD SCRIPT LOAD script Bir betiği önbelleğe yükler ve SHA1 toplam değerini döndürür. Sonraki çağrılar için toplam değerini EVALSHA ile kullanın.
SCRIPT EXISTS SCRIPT EXISTS sha1 [sha1 ...] Betiklerin önbellekte olup olmadığını kontrol eder. Önbellekteki her betik için 1, eksik olan her betik için 0 döndürür.
SCRIPT KILL SCRIPT KILL Şu anda çalışan betiği sonlandırır. Orca, yazma betikleri dahil olmak üzere betik tarafından yapılan tüm veri değişikliklerini otomatik olarak geri alır.
SCRIPT FLUSH SCRIPT FLUSH [ASYNC | SYNC] Kümedeki tüm önbelleğe alınmış Lua betiklerini temizler. SYNC (varsayılan) işlem tamamlanana kadar bekler; ASYNC önbelleği arka planda temizler.

Desteklenmeyen komutlar

Aşağıdaki komutlar bir Lua betiği içinde redis.call() veya redis.pcall() kullanılarak çağrılamaz:

  • İşlem denetimi: WATCH, UNWATCH, MULTI, EXEC, DISCARD

  • Bloklayan komutlar: BLPOP, BRPOP

  • Lua betiği komutları: EVAL, EVAL_RO, EVALSHA, EVALSHA_RO, SCRIPT

  • Pub/Sub komutları: SUBSCRIBE, UNSUBSCRIBE, PSUBSCRIBE, PUNSUBSCRIBE

  • Bağlantı yönetimi: AUTH, HELLO, CLIENT

Bu komutlardan herhangi birinin çağrılması derhal hata döndürür.

Hızlı başlangıç

Aşağıdaki örneklerde SET polardb orca komutuyla ayarlanan test anahtarı kullanılmaktadır.

EVAL

EVAL — Bir betiği doğrudan çalıştırın:

EVAL "return redis.call('GET', KEYS[1])" 1 polardb

Çıktı:

"orca"

SCRIPT LOAD

SCRIPT LOAD — Bir betiği önbelleğe alır ve SHA1 toplam değerini elde eder:

SCRIPT LOAD "return redis.call('GET', KEYS[1])"

Çıktı:

"d3c21d0c2b9ca22f82737626a27bcaf5d288f99f"

EVALSHA

EVALSHA — Önbelleğe alınmış betiği SHA1 toplam değeriyle çalıştırır:

EVALSHA d3c21d0c2b9ca22f82737626a27bcaf5d288f99f 1 polardb

Çıktı:

"orca"

SCRIPT EXISTS

SCRIPT EXISTS — Betiklerin önbellekte olup olmadığını kontrol eder (ilk SHA1 mevcuttur, ikincisi yoktur):

SCRIPT EXISTS d3c21d0c2b9ca22f82737626a27bcaf5d288f99f ffffffffffffffffffffffffffffffffffffffff

Çıktı:

1) (integer) 1
2) (integer) 0

Yaygın senaryolar

Atomik sayaç uygulama

Eşzamanlı INCR işlemlerinden kaynaklanan yarış durumlarını önlemek için Lua betiklerini kullanın. SCRIPT LOAD + EVALSHA deseni, sonraki çağrılarda betik içeriğini ağ üzerinden göndermeden tutarak ağ trafiğini azaltır ve aktarım hızını artırır.

1. Betiği yazın ve yerel olarak kaydedin:

-- counter.lua
-- Initialize the key to 0 if it does not exist, then increment by 1.
if redis.call('EXISTS', KEYS[1]) == 0 then
  redis.call('SET', KEYS[1], 0)
end
return redis.call('INCR', KEYS[1])

2. SHA1 toplam değerini almak için betiği yükleyin:

SCRIPT LOAD "if redis.call('EXISTS', KEYS[1]) == 0 then redis.call('SET', KEYS[1], 0) end return redis.call('INCR', KEYS[1])"

Çıktı:

"b547eabbcde73b25330442e4f4e4dc1783b91241"

3. Betiği SHA1 toplam değeriyle çalıştırın:

EVALSHA b547eabbcde73b25330442e4f4e4dc1783b91241 1 my_counter

İlk çağrıdaki çıktı:

(integer) 1

İkinci çağrıdaki çıktı:

(integer) 2

Salt okunur betik çalıştırma

Bir betiğin yazma işlemleri gerçekleştirmeyeceğini garanti etmek için EVAL_RO veya EVALSHA_RO kullanın. Bu yaklaşım, betiklerin yalnızca okuma çoğaltmalarına erişmesi gereken okuma/yazma ayrıştırma senaryolarında kullanışlıdır.

EVAL_RO kullanmadan önce betiğinizin SET, DEL, HSET veya LPUSH gibi yazma komutlarını çağırmadığından emin olun. Eğer çağırıyorsa bunun yerine EVAL kullanın.

EVAL_RO "return {redis.call('GET', KEYS[1]), redis.call('TTL', KEYS[1])}" 1 polardb

Çıktı:

1) "orca"
2) (integer) -1
Not

Betik yazma komutları içeriyorsa EVAL_RO komutu (error) ERR Write commands are not allowed from read-only scripts. hatasını döndürür.

Uzun süre çalışan bir betiği durdurma

Bir betik beklendiğinden daha uzun sürer ve kümeyi engellerse SCRIPT KILL ile sonlandırın. Orca, betiğin yaptığı tüm değişiklikleri otomatik olarak geri alır.

SCRIPT KILL

Çıktı:

OK
Not

SCRIPT KILL yalnızca şu anda çalışan betiği sonlandırır. Belirli bir betiği SHA1 ile hedefleyemezsiniz.

En iyi uygulamalar

Üretim iş yükleri için SCRIPT LOAD + EVALSHA kullanın

Aşağıdaki tüm örnekler, betikleri önbelleğe almak için başlangıçta SCRIPT LOAD kullanır ve sonraki her çağrı için EVALSHA uygular. Bu desen, her istekte tam betiğin yeniden iletilmesini önler.

1. Uygulama başlatma sırasında betiği yükleyin:

# Cache a script that sets a key's value
SCRIPT LOAD "return redis.call('set', KEYS[1], ARGV[1])"

Çıktı:

"55b22c0d0cedf3866879ce7c854970626dcef0c3"

Bu SHA1 değerini uygulamanızda saklayın.

2. Betiği önbelleğe alınan SHA1 ile çalıştırın:

# Set k1 = v1
EVALSHA 55b22c0d0cedf3866879ce7c854970626dcef0c3 1 k1 v1

# Set k2 = v2 using the same cached script
EVALSHA 55b22c0d0cedf3866879ce7c854970626dcef0c3 1 k2 v2

3. NOSCRIPT hatalarını ele alın:

EVALSHA bir NOSCRIPT hatası döndürürse betik artık önbellekte değildir. Betiği yeniden çalıştırmak ve önbelleğe almak için EVAL veya SCRIPT LOAD kullanın, ardından EVALSHA kullanmaya devam edin.

Betikleri KEYS[] ve ARGV[] ile parametreleştirin

Betik gövdesinde değerleri sabit kodlamak yerine tüm değişken verileri KEYS[] ve ARGV[] üzerinden iletin. Sabit kodlanmış betikler benzersiz dizelerdir; her varyasyon ayrı bir önbellek girişi oluşturur, bu da bellek kullanımını şişirir ve önbelleğe almanın etkisini ortadan kaldırır.

Aşağıdaki örnek anti-deseni ve doğru yaklaşımı göstermektedir:

-- Anti-pattern: each hard-coded variant creates a separate cache entry
EVAL "return 'Hello'" 0
EVAL "return 'Scripting!'" 0

-- Correct: one parameterized script reuses the same cache entry for any value
EVAL "return ARGV[1]" 0 Hello
EVAL "return ARGV[1]" 0 Scripting!

Betikleri kısa ve hızlı tutun

Lua betikleri atomik olarak çalışır ve yürütme sırasında diğer tüm komutları engeller. Uzun süre çalışan veya büyük toplu iş betikleri, kümedeki diğer tüm istemciler için gecikme süresini artırır.

  • Betikler içinde karmaşık döngülerden veya geniş ölçekli veri geçişlerinden kaçının.

  • Varsayılan çalıştırma zaman aşımı 300 saniyedir. Bu sınırı aşan bir betik, mantığın basitleştirilmesi gerektiğine işaret eder.

  • Karmaşık işlemleri tek bir büyük betik yerine birden çok daha küçük betiğe bölün.

Betik önbelleğini güvenli bir şekilde temizleyin

Tüm önbelleğe alınmış betikleri kaldırmak için SCRIPT FLUSH kullanın. Temizleme işleminden sonra, betikler yeniden yüklenene kadar EVALSHA veya EVALSHA_RO yapılan her çağrı NOSCRIPT hatası döndürür.

Uyarı

Çok sayıda önbelleğe alınmış betiği olan kümelerde SCRIPT FLUSH komutu kümeyi uzun süre engelleyebilir. Bu komutu yoğun saatler dışında çalıştırın.

SCRIPT FLUSH

Çıktı:

OK

Betik kaynak kodunu uygulamanızda saklayın ve NOSCRIPT hataları için otomatik kurtarma mekanizması uygulayın. Hata durumunda betiği SCRIPT LOAD ile yeniden yükleyin veya EVAL ile yeniden kaydedin.

SSS

NOSCRIPT No matching script. Please use EVAL. hatasını nasıl düzeltirim?

Betik artık küme önbelleğinde bulunmuyor. Bu durum, küme yeniden başlatıldığında, HA yük devretme işlemi gerçekleştiğinde veya bir SCRIPT FLUSH çağrısından sonra meydana gelir. İstemcinizde NOSCRIPT hatalarını yakalayın ve betiği yeniden kaydetmek için EVAL veya SCRIPT LOAD komutlarına geri dönün. Yeniden kayıttan sonra EVALSHA çağrıları beklendiği gibi çalışmaya devam eder.

Bir betik zaman aşımına uğradığında ne yapmalıyım?

Varsayılan zaman aşımı 300 saniyedir. Zaman aşımı genellikle betik mantığının çok karmaşık olduğunu veya çok fazla veri işlediğini gösterir. Kurtarmak için SCRIPT KILL çalıştırın; PolarDB betiğin yaptığı tüm değişiklikleri geri alır. Tekrarlanmasını önlemek için betiği verimsiz döngülerden veya geniş ölçekli veri okumalarından kaçınacak şekilde optimize edin veya mantığı birden çok daha küçük betiğe bölün.

Neden EVAL_RO komutu ERR Write commands are not allowed from read-only scripts. hatası döndürür?

EVAL_RO ve EVALSHA_RO tüm yazma işlemlerini yasaklar. Betikte SET, HSET veya DEL gibi yazma komutları olup olmadığını kontrol edin ve bunları kaldırın. Betiğin veri yazması gerekiyorsa bunun yerine EVAL veya EVALSHA kullanın.