İçeriğe geç

Görev 10 — SA-MP MySQL Pluginini Kur ve Bağlan

Kazanacağın yetenek: SA-MP MySQL R41-4 pluginini doğru dosyalarla yüklemek, uygulamaya özel veritabanı hesabı oluşturmak ve bağlantıyı gamemode yaşam döngüsünde yönetmek.

Önceki görevde oyuncu skoru yalnızca bellekteydi. Sunucu kapanınca PlayerData dizisi sıfırlanıyordu. Bu bölümden itibaren MySQL kalıcı kayıt katmanı olacak; oyun sırasında kullanılacak güncel veri yine Pawn belleğinde tutulacak.

SA-MP açılır
→ mysql plugin yüklenir
→ OnGameModeInit
→ mysql.ini okunur
→ MySQL bağlantısı açılır
Oyuncu bağlanır
→ profil asenkron yüklenir
→ veri PlayerData içine alınır
→ oyun bellekte devam eder
→ önemli olaylarda ve ayrılırken UPDATE kuyruğa girer

MySQL’i her skor okumasında çağırmayacağız. Veriyi bağlantıda bir kez yüklemek, oyun içinde bellekte değiştirmek ve belirli noktalarda kaydetmek hem daha hızlı hem daha kolay test edilir.

Bu öğrenme yolu MySQL plugin R41-4 API’sini kullanır. Başka ana sürümlere ait include ve binary dosyalarını karıştırma.

Windows yayın paketindeki temel yerleşim şöyledir:

samp-server/
├── libmariadb.dll
├── log-core.dll
├── plugins/
│ └── mysql.dll
└── pawno/
└── include/
└── a_mysql.inc

Linux paketinde:

samp-server/
├── log-core.so
├── plugins/
│ └── mysql.so
└── pawno/
└── include/
└── a_mysql.inc

Arşivi sunucu köküne çıkarmak bu yolları korur. Yalnızca mysql.dll veya mysql.so dosyasını kopyalamak yeterli olmayabilir; paketteki log-core ve istemci kütüphanesi de çalışma zamanı bağımlılığıdır.

server.cfg dosyasına işletim sistemine uygun plugin adını ekle:

Windows server.cfg
plugins mysql
Linux server.cfg
plugins mysql.so

Başka pluginler varsa aynı plugins satırında boşlukla ayır. Linux’ta dinamik MySQL istemci kütüphanesi bulunamıyorsa kullandığın R41-4 paketinin statik Linux dağıtımını tercih edebilirsin; plugin dosyası yine pakette verilen adıyla kullanılmalıdır.

Gamemode’un include bölümünde a_samp sonrasına ekle:

#include <a_samp>
#include <a_mysql>

Compiler a_mysql dosyasını bulamıyorsa doğru pawncc kurulumunun yanındaki pawno/include/ klasörünü kontrol et. Bir include kopyasıyla derleyip farklı sürümde binary yüklemek runtime error 19 ve eksik native hatalarına yol açabilir.

MySQL veya MariaDB yönetici hesabıyla aşağıdaki şemayı bir kez oluştur:

CREATE DATABASE `gtaverse`
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;
CREATE USER 'samp_app'@'127.0.0.1'
IDENTIFIED BY 'replace-with-a-long-random-password';
GRANT SELECT, INSERT, UPDATE, DELETE
ON `gtaverse`.*
TO 'samp_app'@'127.0.0.1';

Gamemode’a root hesabı verme. Uygulama kullanıcısının yalnızca oyun sırasında gereken SELECT, INSERT, UPDATE ve DELETE yetkilerine sahip olması olası bir SQL injection veya kod hatasının etkisini sınırlar.

Oyuncu tablosunu da yönetici hesabıyla oluştur:

USE `gtaverse`;
CREATE TABLE `players`
(
`id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
`username` VARCHAR(24) NOT NULL,
`score` INT NOT NULL DEFAULT 0,
`money` INT NOT NULL DEFAULT 0,
`mission_count` INT UNSIGNED NOT NULL DEFAULT 0,
`last_seen` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
UNIQUE KEY `uq_players_username` (`username`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

username üzerindeki unique index hem aynı profilin iki kez açılmasını engeller hem de bağlantıda yapacağımız profil sorgusunu hızlandırır. Tablo oluşturma ve değiştirme işini gamemode başlangıcına koymak yerine sürümlenmiş SQL migration dosyalarıyla yönetmek production ortamında daha güvenlidir.

SA-MP sunucu kökünde mysql.ini oluştur:

mysql.ini
hostname = 127.0.0.1
username = samp_app
password = replace-with-a-long-random-password
database = gtaverse
auto_reconnect = true
server_port = 3306

mysql_connect_file yalnızca sunucu kökündeki dosyayı okur; alt klasör yolu verme. mysql.ini dosyasını Git’e ekleme, forumda paylaşma veya hata ekran görüntüsünde gösterme.

.gitignore
mysql.ini

Dosya daha önce commit edildiyse .gitignore eklemek geçmişteki parolayı kaldırmaz. Veritabanı parolasını değiştir ve dosyayı repository takibinden ayrıca çıkar.

MySQL ayrı bir Docker container içindeyse 127.0.0.1 SA-MP container’ının kendisini gösterir. Bu durumda hostname, Compose ağındaki MySQL servis adı olmalıdır.

Global bağlantı handle’ı tanımla:

new MySQL:g_Database = MYSQL_INVALID_HANDLE;

Gamemode açılırken bağlantıyı kur:

public OnGameModeInit()
{
mysql_log(ERROR | WARNING);
g_Database = mysql_connect_file("mysql.ini");
if (g_Database == MYSQL_INVALID_HANDLE)
{
print("[database] mysql.ini okunamadi veya handle olusturulamadi");
SendRconCommand("exit");
return 1;
}
new errorCode = mysql_errno(g_Database);
if (errorCode != 0)
{
new errorMessage[160];
mysql_error(errorMessage, sizeof errorMessage, g_Database);
printf(
"[database] Connection failed (%d): %s",
errorCode,
errorMessage
);
mysql_close(g_Database);
g_Database = MYSQL_INVALID_HANDLE;
SendRconCommand("exit");
return 1;
}
if (!mysql_set_charset("utf8mb4", g_Database))
{
print("[database] Could not set utf8mb4 charset; shutting down");
mysql_close(g_Database);
g_Database = MYSQL_INVALID_HANDLE;
SendRconCommand("exit");
return 1;
}
print("[database] MySQL connection established");
SetGameModeText("GTAVerse Academy");
// Keep the existing AddPlayerClass call here.
return 1;
}

Bağlantı kurulamazsa kalıcı veri kullanan sunucuyu açık bırakmak, oyuncuların boş profille oynamasına ve daha sonra gerçek veriyi ezmesine neden olabilir. Bu öğrenme yolunda bağlantı zorunlu olduğu için sunucuyu kontrollü kapatıyoruz.

Gamemode kapanırken handle’ı kapat:

public OnGameModeExit()
{
if (g_Database != MYSQL_INVALID_HANDLE)
{
mysql_close(g_Database);
g_Database = MYSQL_INVALID_HANDLE;
}
return 1;
}

mysql_close, kuyruktaki threaded sorgular bitene kadar bekleyebilir. Bu davranış kapanış sırasında son kayıtların tamamlanmasını sağlar; normal oyun akışında bağlantıyı açıp kapatarak sorgu çalıştırma yöntemi olarak kullanılmamalıdır.

Çağrı Başarılı sonuç Hata sonucu
mysql_connect_file Geçerli MySQL: handle MYSQL_INVALID_HANDLE
mysql_errno Önceki ilgili işlemde hata yoksa 0 MySQL hata kodu, fonksiyon hatasında -1
mysql_error Hata metni hedef buffer’a yazıldıysa 1 0
mysql_set_charset 1 0
mysql_close 1 0

Handle’ın geçerli olması tek başına bağlantının kurulduğunu kanıtlamaz; bağlantıdan hemen sonra mysql_errno(g_Database) sonucunu da doğrula. mysql_connect_file geçersiz handle döndürdüyse o handle ile mysql_error çağırma; mysql.ini ayrıntısı plugin logunda bulunur.

  1. MySQL veya MariaDB servisini başlat.
  2. mysql.ini bilgilerini doğrula.
  3. Pawn kodunu yeniden derle.
  4. SA-MP sunucusunu başlat.
  5. server_log.txt içinde pluginin yüklendiğini ve kendi bağlantı mesajını ara.

Sonra parolayı geçici olarak yanlış yazıp sunucunun açılmayı reddettiğini doğrula. Test bittiğinde doğru değeri geri yükle ve yanlış parolayı loglarda bırakma.

  • R41-4 binary ve a_mysql.inc aynı sürümden geliyor.
  • Windows veya Linux plugin satırı doğru.
  • Uygulama root yerine sınırlı veritabanı hesabı kullanıyor.
  • Bağlantı bilgileri Pawn kaynak kodunda değil.
  • Başarısız bağlantıda gamemode boş veriyi kaydetmeye devam etmiyor.
  • OnGameModeExit geçerli handle’ı kapatıyor.

Sıradaki görev: threaded MySQL sorgularını ve cache akışını öğren.