Görev 11 — SA-MP MySQL Sorguları ve Cache
Kazanacağın yetenek: SQL sorgusunu güvenli hazırlamak, sunucuyu bekletmeden kuyruğa göndermek ve sonucu yalnızca ilgili callback’in aktif cache’i içindeyken okumak.
MySQL sorgusu ağ ve disk erişimi yapar. Bunu SA-MP ana thread’inde bekletirsen bir sorgu tamamlanana kadar oyuncu güncellemeleri de bekler. R41-4 ile günlük oyun sorgularında varsayılan seçimin mysql_tquery olmalı.
Threaded sorgunun olay zinciri
Bölüm başlığı “Threaded sorgunun olay zinciri”Pawn mysql_tquery çağırır → sorgu sıraya alınır → SA-MP ana döngüsü devam eder → MySQL thread'i sorguyu çalıştırır → sonuç hazır olduğunda public callback çağrılır → callback süresince sonuç cache'i aktiftir → callback bittiğinde geçici cache temizlenirmysql_tquery dönüşündeki 1, sorgunun veritabanında başarılı olduğu anlamına gelmez. Yalnızca sorgunun çalıştırılmak üzere kuyruğa kabul edildiğini bildirir. SQL hataları MySQL güvenliği ve hata ayıklama bölümünde ele alacağımız OnQueryError callback’ine gider. Hata yolunda sorgunun normal sonuç callback’i çağrılmaz; oyuncuya bağlı akışlarda ayrıca zaman aşımı veya başka bir kurtarma yolu gerekir.
Kullanıcı verisini %e ile kaçır
Bölüm başlığı “Kullanıcı verisini %e ile kaçır”Oyuncu adı, komut parametresi veya dialog girdisini SQL metnine %s ile doğrudan ekleme. mysql_format içindeki %e, MySQL için özel karakterleri escape eder:
LoadPlayerProfile(playerid){ new playerName[MAX_PLAYER_NAME + 1]; new query[160];
GetPlayerName(playerid, playerName, sizeof playerName);
mysql_format( g_Database, query, sizeof query, "SELECT `id`, `score` FROM `players` WHERE `username` = '%e' LIMIT 1", playerName );
return mysql_tquery( g_Database, query, "OnPlayerProfileLoaded", "d", playerid );}%e string değeri içindir. Tablo veya kolon adını kullanıcı girdisinden üretme; dinamik identifier gerekiyorsa önceden belirlenmiş whitelist içinden seç.
Callback parametre formatını oku
Bölüm başlığı “Callback parametre formatını oku”mysql_tquery içindeki callback formatı, sorgu sonucunu değil callback’e geri taşınacak Pawn değerlerini tanımlar:
| Format | Taşınan değer |
|---|---|
d veya i |
Integer |
f |
Float |
s |
String |
b |
Boolean |
a |
Dizi; ardından eleman türü ve uzunluğu gerekir |
r |
Referans |
Örnekte "d", playerid, sorgu tamamlandığında hangi oyuncu için çalıştığımızı callback’e taşır. Callback adı public olmalı ve compiler tarafından görülebilmesi için forward edilmelidir:
forward OnPlayerProfileLoaded(playerid);
public OnPlayerProfileLoaded(playerid){ return 1;}Callback’in return 1 değeri MySQL sorgusunun sonucunu değiştirmez. Buradaki return, Pawn callback’inin normal şekilde tamamlandığını anlatan proje standardıdır.
SELECT sonucunu cache üzerinden oku
Bölüm başlığı “SELECT sonucunu cache üzerinden oku”cache_get_row_count satır sayısını output parametresine yazar:
forward OnPlayerProfileLoaded(playerid);
public OnPlayerProfileLoaded(playerid){ new rowCount;
if (!cache_get_row_count(rowCount)) { print("[database] Could not read row count"); return 1; }
if (rowCount == 0) { SendClientMessage(playerid, 0xFFCC00FF, "Profil bulunamadi."); return 1; }
new databaseId; new score;
cache_get_value_name_int(0, "id", databaseId); cache_get_value_name_int(0, "score", score);
printf("Loaded profile id=%d score=%d", databaseId, score); return 1;}Üç farklı sonucu ayır:
- fonksiyon
0döndürdü: cache okunamadı, - fonksiyon
1,rowCount == 0: sorgu başarılı ama kayıt yok, - fonksiyon
1,rowCount > 0: okunabilir satır var.
LIMIT 1 kullandığımız için ilk satırın indeksi 0’dır. Kolon adına göre typed getter seç:
- string:
cache_get_value_name, - integer:
cache_get_value_name_int, - float:
cache_get_value_name_float.
Enum içindeki string alana yazarken buffer uzunluğunu açıkça gönder:
cache_get_value_name( 0, "username", PlayerData[playerid][playerName], MAX_PLAYER_NAME + 1);Kullanım örneği: en yüksek skorlu oyuncular
Bölüm başlığı “Kullanım örneği: en yüksek skorlu oyuncular”Sonuçta birden fazla satır olduğunda rowCount kadar dön:
ShowTopPlayers(){ return mysql_tquery( g_Database, "SELECT `username`, `score` FROM `players` ORDER BY `score` DESC LIMIT 5", "OnTopPlayersLoaded" );}
forward OnTopPlayersLoaded();
public OnTopPlayersLoaded(){ new rowCount; if (!cache_get_row_count(rowCount)) { return 1; }
for (new rowIndex = 0; rowIndex < rowCount; rowIndex++) { new playerName[MAX_PLAYER_NAME + 1]; new score;
cache_get_value_name( rowIndex, "username", playerName, sizeof playerName ); cache_get_value_name_int(rowIndex, "score", score);
printf("#%d %s - %d", rowIndex + 1, playerName, score); }
return 1;}Bu callback çalışırken cache otomatik olarak aktiftir. Sonucu callback sonrasında kullanman gerekmiyorsa cache_save veya cache_delete çağırma.
INSERT sonrası oluşan ID’yi al
Bölüm başlığı “INSERT sonrası oluşan ID’yi al”Auto increment ID yalnızca INSERT tamamlandıktan sonra bilinir:
CreatePlayerProfile(playerid, const playerName[]){ new query[160];
mysql_format( g_Database, query, sizeof query, "INSERT INTO `players` (`username`) VALUES ('%e')", playerName );
return mysql_tquery( g_Database, query, "OnPlayerProfileCreated", "d", playerid );}
forward OnPlayerProfileCreated(playerid);
public OnPlayerProfileCreated(playerid){ new databaseId = cache_insert_id();
if (databaseId <= 0) { print("[database] Insert did not produce a valid profile id"); return 1; }
printf("Created profile id=%d", databaseId); return 1;}cache_insert_id değerini mysql_tquery çağrısından hemen sonra okumak yanlıştır; sorgu o anda henüz tamamlanmamış olabilir. Aktif cache yoksa -1, INSERT yeni bir auto increment değeri üretmediyse 0 gelebilir. Bu tabloda geçerli profil ID’si pozitif olacağı için örnek iki durumu da reddeder.
UPDATE sonucunu doğrula
Bölüm başlığı “UPDATE sonucunu doğrula”Güncellemenin gerçekten bir satıra dokunup dokunmadığı önemliyse callback kullan:
SavePlayerScore(databaseId, score){ new query[128];
mysql_format( g_Database, query, sizeof query, "UPDATE `players` SET `score` = %d WHERE `id` = %d LIMIT 1", score, databaseId );
return mysql_tquery(g_Database, query, "OnPlayerScoreSaved");}
forward OnPlayerScoreSaved();
public OnPlayerScoreSaved(){ new affectedRows = cache_affected_rows();
if (affectedRows == -1) { print("[database] Could not read affected row count"); }
return 1;}MySQL, yeni değer mevcut değerle aynıysa değişen satır sayısını 0 bildirebilir. Bu her zaman profil bulunamadı demek değildir; sonucu sorgunun amacıyla birlikte yorumla.
Hangi sorgu fonksiyonunu seçmelisin?
Bölüm başlığı “Hangi sorgu fonksiyonunu seçmelisin?”| Fonksiyon | Davranış | Öğrenme yolundaki kullanım |
|---|---|---|
mysql_tquery |
Ayrı thread’de, sırayı koruyarak çalışır | Varsayılan seçim |
mysql_pquery |
Pool üzerinde paralel çalışabilir, sıra garantisi yoktur | Bağımsız ve sırasız işler için ileri konu |
mysql_query |
Ana Pawn thread’ini sonuç gelene kadar bekletir | Oyun akışında kullanma |
mysql_pquery ile aynı oyuncuya ait iki UPDATE farklı sırada tamamlanabilir ve eski veri yeniyi ezebilir. Ayrıca paralel sorgular transaction akışı için uygun değildir. İhtiyacı ölçmeden tquery yerine geçme.
Cache ne zaman saklanır?
Bölüm başlığı “Cache ne zaman saklanır?”Normal mysql_tquery callback’inde aktif cache yalnızca callback boyunca kullanılır. Login dialog’u gibi sonuç daha sonra okunacaksa cache_save ile bir Cache: handle alabilirsin. Bu handle’ı kullandıktan veya oyuncu ayrıldığında cache_delete ile mutlaka temizlemelisin.
Bu akademide profil verisini callback sırasında hemen PlayerData içine kopyalayacağız; cache’i uzun süre saklamaya gerek kalmayacak.
Görev tamamlandı mı?
Bölüm başlığı “Görev tamamlandı mı?”- Kullanıcı stringleri
mysql_formatve%eile hazırlanıyor. - Oyun sorgularında
mysql_tqueryvarsayılan seçim. - Callback parametre formatı callback imzasıyla aynı.
- Satır sayısı output parametresinden okunuyor.
- Integer, Float ve string için doğru cache getter kullanılıyor.
- INSERT ID’si ve affected rows yalnızca sonuç callback’inde okunuyor.
Sıradaki görev: oyuncu profilini MySQL ile yükle, oluştur ve kaydet.