Урок Плагин MySQL - разбор функций

[Zeus u3 BeJlarusi]

Всем здравствуйте. На данном форуме много уроков по MySQL и по переводу мода на него, но нет урока, который бы описывал функции данного плагина. В официальном Pawno описание функций только на английском.

Поэтому я решил написать урок, посвященный всем доступным функциям MySQL

Ну для начала: по этой ссылке можно скачать плагин MySQL для сервера. Тут же есть и описание функций (на англ)
Кстати, функции подходят только к плагину от BlueG (G-sTyLeZzZ)

Итак, поехали...


Функции плагина
Примечание: Каждая функция (кроме mysql_connect и mysql_debug) имеет параметр connectionHandle - ID базы данных. Если вы подключены только к одной базе данных, то вам не нужно использовать данный параметр. Он всегда будет 1 по умолчанию

1. mysql_debug

С помощью данной функции можно включить / отключить запись всех действий с базой данных в лог (не рекомендую, если не требуется - может тормозить сервер)

Синтаксис:

mysql_debug(enable);

enable: 0 - отключить, 1 - включить

Пример использования (так, как его использую я):

format(str, sizeof(str), "UPDATE contracts SET taken = 0 WHERE uID = %d", hittakecontract[playerid]);
if(!mysql_query(str)) { mysql_debug(1); mysql_query(str); mysql_debug(0); } // Запишет в дебаг, только если в запросе будет ошибка

Возвращает: ничего



2. mysql_connect

С помощью данной функции можно подключиться к Базе Данных
Важное замечание: Не пытайтесь переподключиться к Базе Данных с помощью этой функции. Для этого используйте mysql_reconnect()

Синтаксис:

mysql_connect(const host[], const user[], const database[], const password[]);

const host[]: IP, на котором расположена База Данных
const user[]: логин пользователя для доступа к Базе Данных
const database[]: имя Базы Данных
const password[]: пароль, для подключения к Базе Данных

Пример использования:

public OnGameModeInit()
{
        new mysql = mysql_connect("127.0.0.1","root","mydatabase","mypass"); // подключимся к Базе Данных
        // ...
}

Возвращает: ID соединения (его нудно использовать в connectionHandle)



4. mysql_ping

Данная функция проверяет, если ли соединение с Базой Данных
Важное замечание: проверка на состояние соединения (и рестарт, если нужно) происходят автоматически при использовании потоков

Синтаксис:

mysql_ping(connectionHandle);

connectionHandle: ID соединения

Пример использования:

if(mysql_ping()) print("MySQL соединение установлено!");
// ...
if(!mysql_ping()) print("MySQL соединение прервано!");

Возвращает: 1 - если соединение есть, 0 - если нет



5. mysql_stat

Данная функция получает статистику MySQL сервера

Синтаксис:

mysql_stat(const destination[], connectionHandle);

const destination[]: строка, в которую необходимо записать полученный результат
connectionHandle: ID соединения

Пример использования:

new stats[150]; mysql_stat(stats); print(stats);
 
//Выведет:
Uptime: 380  Threads: 1  Questions: 3  Slow queries: 0  Opens: 12  Flush tables: 1  
Open tables: 6  Queries per second avg: 0.008

Возвращает: ничего



6. mysql_set_charset

С помощью этой функции можно изменить кодировку симовлов в Базе Данных. Полезно для использования в БД символов, отличных от английских (например, кириллицу)

Синтаксис:

mysql_set_charset(charset[],connectionHandle);

charset[]: необходимая кодировка
connectionHandle: ID соединения

Пример использования:

mysql_set_charset("utf8_unicode_ci");

Возвращает: ничего



7. mysql_get_charset

С помощью этой функции можно узнать, какая сейчас кодировка установлена

Синтаксис:

mysql_get_charset(destination[], connectionHandle);

destination[]: строка, в которую запишем текущую кодировку
connectionHandle: ID соединения

Пример использования:

new charset[20]; mysql_get_charset(charset);

Возвращает: ничего



8. mysql_reconnect

С помощью этой функции можно переподключиться к БД

Синтаксис:

mysql_get_charset(connectionHandle);

connectionHandle: ID соединения

Пример использования:

//Если соединение по какой-либо причине пропало
mysql_reconnect();

Возвращает: ничего



9. mysql_reload

С помощью этой функции можно попросить MySQL сервер перезагрузить таблицы пользовательских привилегий (сам не юзал)

Синтаксис:

mysql_reload(connectionHandle);

connectionHandle: ID соединения

Пример использования:

mysql_reload();
 
//Данный запрос имеет тот же смысл, что и строка выше
mysql_query("FLUSH PRIVILEGES");

Возвращает: ничего



10. mysql_format

С помощью этой функции можно попросить MySQL сервер перезагрузить таблицы пользовательских привилегий (сам не юзал)
Важное замечание: функция добавлена в версии R6-2 плагина и не работает в более ранних версиях
Замечание: такие спецификаторы как %2.f, %10.s еще не поддерживаются

Синтаксис:

mysql_format(connectionHandle, output[], format[], {Float,_}:...);

connectionHandle: ID соединения
output[]: строка, в которую придется записать результат
format[]: строка, которую нужно подготовить для запроса
{Float,_}:...: тут аргументы

Пример использования:

new szDestination[100];
mysql_format(connectionHandle, szDestination, "SELECT * FROM `%s` WHERE `bar` = '%e' AND `foobar` = '%f' LIMIT %d", "foobar", "escape'me\"please", 1.2345, 1337);
mysql_query(szDestination);

Дополнения:
Эту функцию можно использовать (и надо использовать) вместо простого format, если вы хотите отправить этот запрос к БД, т.к. она автоматически проверяет запрос на запрещенные символы, которыми можно вызвать SQL инъекцию и заменяет их не безопасные

Доступные спецификаторы:

%s - обычная строка (опасные символы не трогаются)
%e - строка, которую необходимо почистить от возможной SQL инъекции (в этом и есть вся разница с format
%d - целое число (ну это и так понятно...)
%f - вещественный тип (дробь)
%i - число

Возвращает: ничего



11. mysql_query

Самая главная функция в плагине. Отправляет запрос к Базе Данных
Важное замечание: я рекомендую всем Вам для каждого запроса создавать потоки. Подробнее о них ниже

Синтаксис:

mysql_query(query[], resultid, extraid, connectionHandle);

query[]: запрос, который необходимо отправить к Базе Данных
resultid: ID запроса (необходимо для потоков)
extraid: переменная, которую вы хотите передать в поток
connectionHandle: ID соединения

Пример использования:

//Если вы не хотите использовать потоки
mysql_query("SELECT * FROM `mytable` WHERE condition=true");
 
//А это если хотите использовать их
#define THREAD_MYSELECT  (1)
mysql_query("SELECT * FROM `mytable` WHERE condition=true",THREAD_MYSELECT,playerid);
//Данный запрос будет отправлен и обработан в отдельном потоке
//Подробнее ниже...

Возвращает: 1 - если запрос отправлен, 0 - если произошла ошибка



12. mysql_query_callback

Функция схожа с mysql_query. Разница в том, что тут вы на каждый поток можете создать свой паблик

Синтаксис:

mysql_query_callback(index, query[], callback[], extraid, connectionHandle);

index: переменная, которую вы хотите передать для использования в потоке
query[]: запрос, который необходимо отправить к Базе Данных
callback[]: название потока (паблика)
extraid: (дополнительный) переменная, которую вы хотите передать в поток
connectionHandle: ID соединения

Замечание: так как создается новый public, не забудьте добавить к нему forward

Пример использования:
f

orward MySqlCallback(query[], index, extraid, connectionHandle);
 
public OnPlayerConnect(playerid)
{
        mysql_query_callback(playerid,"SELECT * FROM `mybuildings`","MySqlCallback");
}
 
public MySqlCallback(query[], index, extraid, connectionHandle)
{
        //Query processed, you can execute your code now
}

Возвращает: 1 - если запрос отправлен, 0 - если произошла ошибка



13. mysql_store_result

Всегда используйте эту функцию после отправки запросов SELECT, SHOW, DESCRIBE, EXPLAIN, CHECK TABLE. Иначе будут создавать пробки
Замечание: Функция используется для сохранения результата запроса для последующей обработки. Не забывайте очищать данные, когда они больше не нужны - mysql_free_result().

Синтаксис:

mysql_store_result(connectionHandle);

connectionHandle: ID соединения

Пример использования:

mysql_query("SELECT * FROM `players` WHERE name='iamcool'");
mysql_store_result();
//...
mysql_free_result();

Возвращает: 1 - если сохранено, 0 - если произошла ошибка



14. mysql_free_result

Функция используется для очистки результата после использования mysql_store_result

Синтаксис:

mysql_free_result(connectionHandle);

connectionHandle: ID соединения

Пример использования:

mysql_query("SELECT * FROM `players` WHERE name='iamcool'");
mysql_store_result();
//...
mysql_free_result();

Возвращает: ничего



15. mysql_real_escape_string

Данная функция проверяет строку на символы, которые могут вызвать SQL инъекцию и отключа Например, \x00, \n, \r, \, ', " и \x1a.
Важное замечание: Всегда используйте эту фунцкию (если не используете mysql_format), если хотите отправить запрос с данными полученными от игрока. Во избежание SQL инъекции

Синтаксис:

mysql_real_escape_string(const source[], destination[], connectionHandle);

const source[]: первоначальная строка
destination[]: строка, в которую записать безопасную строку
connectionHandle: ID соединения

Замечание: Перед использованием этой функции необходимо, чтобы соединение с БД было установлено.
Замечание: Символы % и _ не блокируются, т.к. используются в некоторых запросах.

Пример использования:

public OnPlayerText(playerd, text[])
{
        new escape[140];
        mysql_real_escape_string(text,escape); // строка теперь безопасна
        // ...
}

Возвращает: кол-во найденных и нейтрализованных вредоносных символов



16. mysql_errno

Функция получает код ошибки предыдущей MySQL операции

Синтаксис:

mysql_errno(connectionHandle);

connectionHandle: ID соединения

Пример использования:

mysql_query("SELECT * FROM `mytable`");
if(mysql_errno() == 0) print("Запрос отправлен без ошибок!");

Возвращает: код ошибки, 0 - если ошибок нет



17. mysql_warning_count

Функция получает кол-во ошибок / предупреждений из предыдущего запроса

Синтаксис:

mysql_warning_count(connectionHandle);

connectionHandle: ID соединения

Пример использования:

mysql_query("UPDATE `notable` SET something=2 WHERE nofield=0");
if(mysql_warning_count()) print("Предупреждения обнаружены!");

Возвращает: код кол-во предупреждений, 0 - если их нет



18. mysql_affected_rows

Функция получает кол-во строк работа с которыми совершилась через запросы INSERT, UPDATE, REPLACE или DELETE

Синтаксис:

mysql_affected_rows(connectionHandle);

connectionHandle: ID соединения

Замечание: Если последний запрос был DELETE, но без WHERE - все строки из данной таблицы будут удалены, но это функция вернет 0.

Пример использования:

mysql_query("DELETE FROM mylogs WHERE log_id > 10");
printf("%d логов удалено!",mysql_affected_rows());

Возвращает: кол-во строк



19. mysql_num_rows

Функция получает кол-во строк, полученных в результате выполнения запросов SELECT и SHOW (схожа с mysql_affected_rows)

Синтаксис:

mysql_num_rows(connectionHandle);

connectionHandle: ID соединения

Пример использования:

mysql_query("SELECT NULL FROM table1");
mysql_store_result(); 
new rows = mysql_num_rows(); 
mysql_free_result();
printf("В таблице %d строк",rows);

Возвращает: кол-во строк



20. mysql_num_fields

Функция получает кол-во столбцов в результате запроса

Синтаксис:

mysql_num_fields(connectionHandle);

connectionHandle: ID соединения

Пример использования:

mysql_query("SELECT field1,field2,field3 FROM table2");
mysql_store_result();
printf("%d столбцов выбрано.",mysql_num_fields());
 mysql_free_result();

Возвращает: кол-во столбцов



21. mysql_insert_id

Функция получает ID сгенерированный благодаря AUTO_INCREMENT в предыдущем INSERT запросе

Синтаксис:

mysql_insert_id(connectionHandle);

connectionHandle: ID соединения

Пример использования:

mysql_query("INSERT INTO `players` (name,password) VALUES ('Ownage',MD5('mypass')");
printf("ID зарегистрированного игрока: %d",mysql_insert_id());

Возвращает: число вставленное в таблицу, как AUTO_INCREMENT



22. mysql_field_count

Функция получает кол-во столбцов в самом последнем запросе

Синтаксис:

mysql_field_count(connectionHandle);

connectionHandle: ID соединения

Пример использования:

mysql_query("SELECT * FROM mytable");
mysql_store_result();
 
printf("В результате запроса %d столбцов.",mysql_field_count());
 
mysql_free_result();

Возвращает: число столбцов



23. mysql_fetch_int

Функция получает число из результата запроса (только если получено 1 число)

Синтаксис:

mysql_fetch_int(connectionHandle);

connectionHandle: ID соединения

Пример использования:

mysql_query("SELECT myid FROM players LIMIT 1");
mysql_store_result();
 
new myid = mysql_fetch_int();
 
mysql_free_result();

Возвращает: полученное число



24. mysql_fetch_float

Функция получает дробь из результата запроса (только если получена 1 дробь)

Синтаксис:

mysql_fetch_float(&Float:result, connectionHandle);

Float:result: вещественная переменная, в которую записать полученную дробь
connectionHandle: ID соединения

Пример использования:

mysql_query("SELECT health FROM players LIMIT 1");
mysql_store_result();
new Float:health;
mysql_fetch_float(health);
mysql_free_result();

Возвращает: ничего



25. mysql_fetch_row_format

Функция служит для обработки полной строки из результата запроса

Замечание: Если запросом получено несколько строк, то данная функция после обработки текущей строки перейдет на следующую.
Замечание: Есть еще одна функция (точнее макрос) - mysql_fetch_row. В нем в отличии от данной функции используется разделитель по умолчанию - '|'

Синтаксис:

mysql_fetch_row_format(string[], const delimiter[], connectionHandle);

string[]: строка, в которую необходимо записать полученный результат
const delimiter[]: разделитель, которым будут разделяться значения из разных столбцов (| по умолчанию). Если не используется, то смело используйте mysql_fetch_row
connectionHandle: ID соединения

Пример использования:

mysql_query("SELECT * FROM players WHERE name='Myname'");
mysql_store_result(); new resultline[200];
 
if(mysql_fetch_row_format(resultline))
{
        //Для разделения можете использовать - sscanf, split, strtok или любой другой способ. Я использую sscanf
        sscanf(resultline,"p<|>dds",PlayerInfo[playerid][pLevel],PlayerInfo[
playerid][pAdmin],PlayerInfo[playerid][pRandomString]);
}
else SendClientMessage(playerid,0xFFFFFF,"В базе данных нет!");
 
mysql_free_result();

Возвращает: 1 - при обработке, 0 - если нет строк для обработки



26. mysql_retrieve_row

Функция служит для перехода на следующую строку.

Замечание: Помните, что mysql_fetch_row_format автоматически переводит на следующую строку (будьте внимательны)
Замечание: Есть еще одна функция (точнее макрос) - mysql_next_row. Она полностью дублирует данную

Синтаксис:

mysql_retrieve_row(connectionHandle);

connectionHandle: ID соединения

Пример использования:

mysql_query("SELECT * FROM houses");
mysql_ store_result();
while(mysql_retrieve_row()) //будет идти пока не достигнет последней строки
{
        //Можете использовать mysql_fetch_field и mysql_fetch_field_row тут
}
mysql_free_result();

Возвращает: 1 - если строка сменилась, 0 - если больше нет строк



27. mysql_fetch_field

Функция получает название определенного столбца.

Синтаксис:

mysql_fetch_field(number, dest[], connectionHandle);

number: номер столбца
dest[]: строка, в которую нужно записать название столбца
connectionHandle: ID соединения

Важное замечание: Если вы укажите неверный номер столбца, плагин крешнется
Замечание: Номер первого столбца - 0


Пример использования:

if(mysql_retrieve_row())
{
        new field[20];
        for(new i, num = mysql_num_fields(); i < num; i++)
        {
                mysql_fetch_field(i,field); //Получит имя всех столбцов
        }
}

Возвращает: ничего



28. mysql_fetch_field_row

Функция получает данные из указанного столбца

Замечание: Есть еще одна функция (точнее макрос) - mysql_get_field

Синтаксис:

mysql_fetch_field_row(string[], const fieldname[], connectionHandle);
mysql_get_field(const fieldname[], string[], connectionHandle); // макрос

string[]: строка куда будет помещен результат из столбца
const fieldname[]: имя столбца, из которого будем брать данные
connectionHandle: ID соединения


Пример использования:

if(mysql_retrieve_row())
{
        new result[50];
        mysql_fetch_field_row(result,"username");
        //или макрос:
        mysql_get_field("username",result);
}

Возвращает: ничего


Коллбеки плагина
Примечание: Используйте потоки, только если вы профессионал

1. OnQueryFinish

Данный коллбек вызывается, когда число (отличное от -1) передается через resultid параметр в mysql_query

Параметры:

public OnQueryFinish(query[], resultid, extraid, connectionHandle)

query[] - выполненный запрос
resultid - ID потока (передается через resultid в mysql_query)
extraid - переменная (передается через extraid в mysql_query)
connectionHandle - ID соединения

Пример:

#define THREAD_LOADPLAYER (5)
 
public OnPlayerConnect(playerid)
{
        mysql_query("SELECT * FROM players WHERE name='Myname'",THREAD_LOADPLAYER,playerid);
        return 1;
}
 
public OnQueryFinish(query[], resultid, extraid, connectionHandle)
{
        switch(resultid)
        {
                case THREAD_LOADPLAYER:
                {
                        mysql_store_result();
                        if(IsPlayerConnected(extraid))
                        {
                                //Ваш код
                        }
                        mysql_free_result();
                }
        }
        return 1;
}

2. OnQueryError

Данный коллбек вызывается, когда происходит ошибка при отправлении запроса

Параметры:
p

ublic OnQueryError(errorid, error[], resultid, extraid, callback[], query[], connectionHandle)

errorid - ID ошибки
error[] - название ошибки
resultid - ID потока
extraid - переменная (передается через extraid в mysql_query)
callback[] - название коллбека, если был mysql_query_callback (если не было - NULL)
query[] - отправленный запрос
connectionHandle - ID соединения

Пример:

public OnQueryError(errorid, error[], resultid, extraid, callback[], query[], connectionHandle)
{
        switch(errorid)
        {
                case CR_COMMAND_OUT_OF_SYNC:
                {
                        printf("Commands out of sync for thread ID: %d",resultid);
                }
                case ER_SYNTAX_ERROR:
                {
                        printf("Something is wrong in your syntax, query: %s",query);
                }
        }
        return 1;
}