İçeriğe geç

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ı.

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 temizlenir

mysql_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.

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ç.

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.

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 0 dö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
);

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.

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.

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.

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.

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.

  • Kullanıcı stringleri mysql_format ve %e ile hazırlanıyor.
  • Oyun sorgularında mysql_tquery varsayı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.