Connector/Node.js Callback API
Документация
Существует две различные реализации соединения: одна, по умолчанию, использует Promise, а другая - Callback, что обеспечивает совместимость с API mysql и mysql2. В документации, представленной на этой странице, используется Callback. Если вам нужна информация об API Promise, смотрите documentation.
Быстрый старт
Установите mariadb Connector используя npm
$ npm install mariadb
Затем вы можете использовать коннектор в коде вашего приложения с помощью Callback API. Например,
const mariadb = require('mariadb/callback'); const conn = mariadb.createConnection({host: 'mydb.com', user:'myUser', password: 'myPwd'}); conn.query("SELECT 1 as val", (err, rows) => { console.log(rows); //[ {val: 1}, meta: ... ] conn.query("INSERT INTO myTable value (?, ?)", [1, "mariadb"], (err, res) => { console.log(res); // { affectedRows: 1, insertId: 1, warningStatus: 0 } conn.end(); }); });
Установка
Чтобы использовать коннектор, сначала необходимо установить его в вашей системе. Процесс установки для Promise и Callback API управляется одним и тем же пакетом через npm.
$ npm install mariadb
Чтобы использовать коннектор, необходимо импортировать пакет в код вашего приложения. Учитывая, что Callback API не используется по умолчанию, оператор `require()` немного отличается.
const mariadb = require('mariadb/callback');
Это инициализирует константу `mariadb`, которая настроена на использование Callback API, а не Promise API по умолчанию.
Часовой пояс
Это не рекомендуется, но в некоторых случаях Node.js и база данных настроены на разный часовой пояс.
По умолчанию опция `timezone` установлена в значение 'local', что указывает на использование часового пояса клиента, поэтому преобразование не будет производиться.
Если часовой пояс клиента и сервера отличается, опция `timezone` должна быть установлена на часовой пояс сервера. - Значение 'auto' означает, что клиент будет запрашивать часовой пояс сервера при создании соединения, а в дальнейшем будет использовать часовой пояс сервера. - Чтобы избежать этой дополнительной команды при подключении, `timezone` может быть установлен в значение IANA time zone.
Коннектор будет преобразовывать дату в часовой пояс сервера, а не в текущий часовой пояс Node.js.
Callback API
Коннектор с Callback API похож на коннектор с использованием Promise, но с некоторыми отличиями.
Base:
- createConnection(options) → Connection: Создает соединение с сервером MariaDB.
- createPool(options) → Pool : Создает новый пул.
- createPoolCluster(options) → PoolCluster : Создает новый кластер пула.
Connect:
- connection.query(sql[, values][, callback]) → Emitter: Выполняет запрос.
- connection.batch(sql, values[, callback]): быстрая пакетная обработка.
- connection.beginTransaction([callback]): Начинает транзакцию.
- connection.commit([callback]): Зафиксировать текущую транзакцию, если таковая имеется.
- connection.rollback([callback]): Откатывает текущую транзакцию, если таковая имеется.
- connection.changeUser(options[, callback]): Изменяет текущего пользователя соединения.
- connection.ping([callback]): Отправляет пустой пакет на сервер, чтобы проверить, что соединение активно.
- connection.end([callback]): Закрывает соединение.
- connection.reset([callback]): сброс текущего состояния соединения.
- connection.isValid() → boolean: Проверяет, активно ли соединение без проверки состояния сокета.
- connection.destroy(): Принудительное закрытие соединения.
- connection.pause(): Приостанавливает вывод сокета.
- connection.resume(): Возобновляет вывод сокета.
- connection.serverVersion(): Получает текущую версию сервера.
- events: Подписка на события об ошибках соединения.
Pool:
- pool.getConnection([callback]) : Создает новое соединение.
- pool.query(sql[, values][, callback]): Выполняет запрос.
- pool.batch(sql, values[, callback]): Выполняет пакет.
- pool.end([callback]): Благородно закрывает соединение.
- pool.activeConnections() → Number: Получает номер текущего активного соединения.
- pool.totalConnections() → Number: Получает текущее общее количество соединений.
- pool.idleConnections() → Number: Получает текущее количество неиспользуемых соединений.
- pool.taskQueueSize() → Number: Получает текущий стекированный запрос.
- pool events: Подписка на события пула.
PoolCluster:
- poolCluster.add(id, config) : добавить пул в кластер.
- poolCluster.remove(pattern) : удаление и завершение пула в соответствии с шаблоном.
- poolCluster.end([callback]) : завершить кластер.
- poolCluster.getConnection([pattern, ][selector, ]callback) : возвращает соединение из кластера.
- poolCluster events: подписывается на события кластера пула.
- poolCluster.of(pattern, selector) → FilteredPoolCluster : возвращает подмножество кластера.
Base API
createConnection(options) → Connection
- `options`: *JSON/String* Использует те же опции, что и Promise API. Для получения полного списка см. option documentation.
Возвращает объект Connection.
Создает новое соединение.
Разница между этим методом и аналогичным методом с Promise API заключается в том, что этот метод возвращает объект `Connection`, а не Promise, который разрешается в объект `Connection`.
const mariadb = require('mariadb/callback'); const conn = mariadb.createConnection({ host: 'mydb.com', user:'myUser', password: 'myPwd' }); conn.connect(err => { if (err) { console.log("не удалось подключиться из-за ошибки: " + err); } else { console.log("подключено ! идентификатор соединения равен " + conn.threadId); } });
Connection options
Список основных опций:
user | Пользователь для доступа к базе данных. | *string* | ||
---|---|---|---|---|
user | Пользователь для доступа к базе данных. | *string* | ||
password | Пароль пользователя. | *string* | ||
host | IP-адрес или DNS сервера базы данных. *Не используется при использовании опции `socketPath`*. | *string* | "localhost" | . |
port | Номер порта сервера базы данных. *Не используется при использовании опции `socketPath`* | *integer* | 3306 | . |
ssl | Включает поддержку TLS. Для получения дополнительной информации смотрите документацию ssl option. | *mixed* | ||
database | База данных по умолчанию, используемая при установлении соединения. | *string* | ||
socketPath | Разрешает соединения с базой данных через сокет домена Unix или именованный канал. | *string* | ||
compress | Сжимает обмен с базой данных с помощью gzip. Это позволяет повысить производительность, когда база данных находится в другом месте. | *boolean* | false | |
connectTimeout | Устанавливает таймаут соединения в миллисекундах. | *integer* | 10 000 | |
socketTimeout | Устанавливает таймаут сокета в миллисекундах после успешного соединения. Значение `0` отключает таймаут. | *integer* | 0 | |
rowsAsArray | Возвращает наборы результатов в виде массивов, а не JSON. Это более быстрый способ получения результатов. Для получения дополнительной информации смотрите раздел Запрос. | *boolean* | false |
Для получения дополнительной информации см. Connection Options documentation.
Подключение к локальным базам данных
При работе с локальной базой данных (то есть в случаях, когда MariaDB и ваше приложение Node.js работают на одном хосте), вы можете подключиться к MariaDB через сокет Unix или именованную трубу Windows для лучшей производительности, а не использовать уровень TCP/IP.
Чтобы настроить это, вам нужно присвоить соединению значение `socketPath`. Когда это сделано, коннектор игнорирует параметры `host` и `port`.
Конкретный путь к сокету, который необходимо задать, определяется параметром socket системной переменной сервера. Если вы не знаете ее, вы можете получить ее с сервера.
SHOW VARIABLES LIKE 'socket';
По умолчанию это `/tmp/mysql.sock` в Unix-подобных операционных системах и `MySQL` в Windows. Кроме того, в Windows эта функция работает только тогда, когда сервер запущен с опцией `--enable-named-pipe`.
Например, на Unix соединение может выглядеть следующим образом:
const mariadb = require('mariadb/callback'); const conn = mariadb.createConnection({ socketPath: '/tmp/mysql.sock', user: 'root' }); conn.connect(err => { //do something with connection conn.end(); });
Это же имеет аналогичный синтаксис в Windows:
const mariadb = require('mariadb/callback'); const conn = mariadb.createConnection({ socketPath: '\\\\.\\pipe\\MySQL', user: 'root' });
createPool(options) → Pool
- `options`: *JSON/string* pool options
Возварщает объект Pool
Создает новый пул.
Пример:
const mariadb = require('mariadb/callback'); const pool = mariadb.createPool({ host: 'mydb.com', user: 'myUser', connectionLimit: 5 }); pool.getConnection((err, conn) => { if (err) { console.log("не удалось подключиться из-за ошибки: " + err); } else { console.log("подключено ! идентификатор соединения - " + conn.threadId); conn.end(); //передача в пул } });
Варианты pool'ов
Опции пула включают документацию по опциям соединения, которые будут использоваться при создании новых соединений.
Конкретные варианты для pool'ов - это :
acquireTimeout | Время ожидания получения нового соединения из пула в мс. | *целое* | 10000 | |
---|---|---|---|---|
connectionLimit | Максимальное количество соединений в пуле. | *целое* | 10 | |
idleTimeout | Укажите время простоя, после которого соединение с пулом будет освобождено. Значение должно быть меньше, чем https://mariadb.com/kb/en/library/server-system-variables/#wait_timeout. В секундах (0 означает никогда не освобождать | @@wait_timeout]] | *целое число* | 1800 |
minimumIdle | Разрешает установить минимальное количество соединений в пуле. Рекомендация - использовать фиксированный пул, поэтому не устанавливать это значение. | *integer* | *set to connectionLimit value* | *set to connectionLimit value*. |
minDelayValidation | При запросе соединения в пул, пул будет проверять состояние соединения. "minDelayValidation" позволяет отключить эту проверку, если соединение было заимствовано недавно, избегая бесполезных проверок в случае частого повторного использования соединений. 0 означает, что проверка выполняется каждый раз, когда запрашивается соединение. (в мс) | *целое* | 500 | |
noControlAfterUse | После возврата соединения в пул (connection.end) коннектор сбросит или откатит соединение, чтобы убедиться, что оно действительно. Эта опция позволяет отключить эти элементы управления | *boolean* | false |
События в pool'е
acquire | Это событие означает, что соединение было получено из пула. |
---|---|
connection | Это событие возникает, когда в пул добавляется новое соединение. Имеет параметр объекта соединения |
enqueue | Это событие возникает, когда команда не может быть немедленно удовлетворена пулом и ставится в очередь. |
release | Это событие возникает, когда соединение возвращается обратно в пул. Имеет параметр объекта соединения |
Пример:
pool.on('connection', (conn) => console.log(`соединение ${conn.threadId} было создано в пуле`);
createPoolCluster(options) → PoolCluster
- `options`: *JSON* poolCluster options
Возвращает объект PoolCluster,
Создает новый кластер пулов. Кластер обрабатывает несколько пулов, обеспечивая высокую доступность / распределяя нагрузку (с использованием круговой / случайной / упорядоченной).
Пример:
const mariadb = require('mariadb/callback'); const cluster = mariadb.createPoolCluster(); cluster.add("master", { host: 'mydb1.com', user: 'myUser', connectionLimit: 5 }); cluster.add("slave1", { host: 'mydb2.com', user: 'myUser', connectionLimit: 5 }); cluster.add("slave2", { host: 'mydb3.com', user: 'myUser', connectionLimit: 5 }); //получение соединения от slave1 или slave2 с использованием round-robin cluster.getConnection(/^slave*$/, "RR", (err, conn) => { conn.query("SELECT 1", (err, rows) => { conn.end(); return row[0]["@node"]; }); });
Параметры PoolCluster
Опции кластера пулов включают pool option documentation, которые будут использоваться при создании новых пулов.
Специфическими опциями для кластера пулов являются :
canRetry | Когда получение соединения из пула не удалось, кластер может повторить попытку с другими пулами | *boolean* | true | |
---|---|---|---|---|
removeNodeErrorCount | Максимальное количество последовательных ошибок соединения из пула перед удалением пула из конфигурации кластера. null означает, что узел не будет удален | *integer* | 5 | |
restoreNodeTimeout | Задержка перед повторным использованием пула после разрыва соединения. 0 = может быть использован немедленно (в мс) | *integer* | 0 | |
defaultSelector | Селектор пулов по умолчанию. Может быть 'RR' (round-robin), 'RANDOM' или 'ORDER' (use in sequence = всегда использовать первые пулы, если не происходит сбой) | *string* | 'RR' |
API подключения
connection.query(sql[, values][, callback])` -> `Emitter
- `sql`: *string | JSON* Строковое значение SQL или объект JSON, заменяющий стандартные параметры соединений. Если это объект JSON, он должен иметь свойство `` sql``. Например: `{dateStrings:true, sql:'SELECT NOW()'}`.
- ``значения``: *массив | объект* Значения заполнителя. Обычно это массив, но в случаях, когда есть только одно значение, его можно указать как есть.
- `callback`: *function* Функция обратного вызова с аргументами (ошибка, результаты, метаданные).
Возвращает объект Emitter, который может испускать четыре различных типа событий:
- error : Выдает объект Error, если запрос завершился неудачно.
- columns : Выдается при получении метаданных колонок из набора результатов (параметр представляет собой массив полей метаданных.
- data : Выдается каждый раз при получении строки (параметр - строка).
- end : Выдается, когда запрос заканчивается (без параметра).
Отправляет запрос в базу данных с функцией обратного вызова, которая вызывается после завершения.
В случаях, когда запрос возвращает огромные наборы результатов, это означает, что все данные хранятся в памяти. Возможно, вам покажется более практичным использовать объект `Emitter` для обработки строк по одной, чтобы избежать перегрузки ресурсов памяти.
Например, выдача запроса с SQL-строкой:
connection.query("SELECT NOW()", (err, rows, meta) => { if (err) throw err; console.log(rows); //[ { { 'now()': 2018-07-02T17:06:38.000Z } ] });
Использование объектов JSON:
connection.query({dateStrings:true, sql:'SELECT now()'}, (err, rows, meta) => { if (err) throw err; console.log(rows); //[ { { 'now()': '2018-07-02 19:06:38' } } });
Placeholder
Чтобы избежать атак SQL Injection, в запросах разрешается использовать вопросительный знак в качестве заполнителя. Коннектор экранирует значения в соответствии с их типом. Вы можете использовать в этих значениях любой собственный тип JavaScript, Buffer, Readable или любой объект с методом `toSqlString`. Все остальные объекты строятся с помощью метода `JSON.stringify`.
Коннектор автоматически передает потоки объектов, реализующих Readable. В этих случаях проверьте значения следующих системных переменных сервера, так как они могут мешать:
- net_read_timeout: Сервер должен полностью получить запрос от коннектора, прежде чем произойдет таймаут. Значение по умолчанию для этой системной переменной - 30 секунд. - max_allowed_packet: С помощью этой системной переменной вы можете контролировать максимальный объем данных, который коннектор может отправить на сервер.
// Отправляет INSERT INTO someTable VALUES (1, _BINARY '.\'.st', 'mariadb') connection.query( "INSERT INTO someTable VALUES (?, ?, ?)", [1, Buffer.from("c327a97374", "hex"), "mariadb"], (err, result) => { if (err) throw err; console.log(result); //log : { affectedRows: 1, insertId: 1, warningStatus: 0 } } );
Вы также можете выполнить тот же запрос, используя Streaming.
const https = require("https"); https.get("https://node.green/#ES2018-features-Promise-prototype-finally-basic-support", readableStream => { connection.query("INSERT INTO StreamingContent (b) VALUE (?)", [readableStream], (err, res) => { if (err) throw err; //inserted }); } )
Результаты запроса
Запросы, выполняемые из коннектора, возвращают два различных вида результатов: объект JSON и массив, в зависимости от типа выполняемого запроса. Запросы, которые записывают данные в базу данных, такие как команды `INSERT`, `DELETE` и `UPDATE`, возвращают объект JSON со следующими свойствами:
- `affectedRows`: Указывает количество строк, затронутых запросом.
- `insertId`: Показывает последнее автоинкрементное значение из `INSERT`.
- `warningStatus`: Указывает, завершился ли запрос предупреждением.
connection.query( "CREATE TABLE animals (" + "id MEDIUMINT NOT NULL AUTO_INCREMENT," + "name VARCHAR(30) NOT NULL," + "PRIMARY KEY (id))", err => { connection.query("INSERT INTO animals(name) value (?)", ["морские львы"], (err, res) => { if (err) throw err; console.log(res); //log : { affectedRows: 1, insertId: 1, warningStatus: 0 } }); } );
Массив набора результатов
Запросы, выполняемые с помощью Коннектора, возвращают два различных вида результатов: объект JSON и массив, в зависимости от типа запроса. Если запрос возвращает несколько строк, коннектор возвращает массив, представляющий данные для каждой строки в массиве. Он также возвращает объект `meta`, содержащий метаданные запроса.
Вы можете формировать результаты данных с помощью опций `nestTables` и `rowsAsArray`. По умолчанию возвращается объект JSON для каждой строки.
connection.query('select * from animals', (err, res, meta) => { console.log(res); // [ //{id: 1, name: 'sea lions' }, //{id: 2, name: 'bird' }, //meta: [ ... ] // ] }); <<code>> === Потоковое вещание <<code lang="javascript">> connection.query("SELECT * FROM mysql.user") .on("error", err => { console.log(err); //если ошибка }) .on("fields", meta => { console.log(meta); // [ ... ]. }) .on("data", row => { console.log(row); }) .on("end", () => { //ended });
connection.batch(sql, values [, callback])
- `sql`: *string | JSON* Строковое значение SQL или объект JSON для замены опций соединений по умолчанию. Объекты JSON должны иметь свойство `` sql``. Например, `{ dateStrings: true, sql: 'SELECT now()' }`
- ``значения``: *array* Массив параметра (массив массива или массив объекта, если используются именованные заполнители).
- `callback`: *function* Функция обратного вызова с аргументами (ошибка, результаты, метаданные).
обратный вызов либо возвращает Error с нулевыми результатами/метаданными, либо с пустой ошибкой и результатами/метаданными
Реализация зависит от типа и версии сервера. для сервера MariaDB версии 10.2.7+, реализация использует выделенный протокол bulk.
В других случаях запросы на вставку будут переписаны для оптимизации. пример: insert into ab (i) values (?) со значениями первой партии = 1, второй = 2 будет переписано вставьте в ab (i) значения (1), (2).
Если запрос не может быть переписан, будет выполнен запрос для каждого значения.
Разница в результате по сравнению с выполнением нескольких вставок по одному запросу заключается в том, что возвращается только первый сгенерированный идентификатор вставки.
Например,
connection.query( "CREATE TEMPORARY TABLE batchExample(id int, id2 int, id3 int, t varchar(128), id4 int)" ); подключение .batch("INSERT INTO `batchExample` values (1, ?, 2, ?, 3)", [[1, "john"], [2, "jack"]], (err, res) => { if (err) { console.log('ошибка обработки'); } else { console.log(res.affectedRows); // 2 } });
connection.beginTransaction([callback])
- ``callback``: *function* Функция обратного вызова с аргументом Error, если произошла ошибка.
Начинает новую транзакцию.
connection.commit([callback])
- `callback`: *функция* функция обратного вызова с аргументом Error, если произошла ошибка.
Завершает текущую транзакцию, если она активна. Коннектор отслеживает состояние текущей транзакции на сервере. Когда активной транзакции нет, этот метод не посылает никаких команд на сервер.
connection.rollback([callback])
- ``callback``: *function* Функция обратного вызова с аргументом Error, если произошла ошибка.
Откатывает текущую транзакцию, если она активна. Коннектор отслеживает текущее состояние транзакции на сервере. Если активной транзакции нет, этот метод не посылает никаких команд на сервер.
conn.beginTransaction(err => { if (err) { // обработка ошибки } else { conn.query("INSERT INTO testTransaction values ('test')", (err) => { if (err) { // обработка ошибки } else { conn.query("INSERT INTO testTransaction values ('test2')", (err) => { if (err) { conn.rollback(err => { if (err) { // обработка ошибки } }); } else { conn.commit(err => { if (err) { // обработка ошибки } }); } }); } }) } });
connection.changeUser(options[, callback])
- ``options``: *JSON*, подмножество документация по опциям подключения = база данных / charset / пароль / пользователь
- `callback`: *функция* функция обратного вызова с аргументом Error, если произошла ошибка.
Сброс соединения и повторная аутентификация с заданными учетными данными. Это эквивалентно созданию нового соединения с новым пользователем, повторно используя существующий открытый сокет.
conn.changeUser({user: 'changeUser', password: 'mypassword'}, err => { if (err) { // обработка ошибки } else { //Пользователь соединения теперь изменен. } });
connection.ping([callback])
- ``callback``: *function* Функция обратного вызова с аргументом Error, если произошла ошибка.
Отправляет однобайтовый пакет на сервер, чтобы проверить, что соединение все еще активно.
conn.ping(err => { if (err) { // обработка ошибки } else { //соединение действительно } })
connection.end([callback])
- ``callback``: *function* Функция обратного вызова с аргументом Error, если произошла ошибка.
Закрывает соединение изящно. То есть коннектор ожидает завершения выполнения текущих запросов, после чего закрывает соединение.
conn.end(err => { // обработка ошибки })
connection.reset([callback])
- ``callback``: *function* Функция обратного вызова с аргументом Error, если произошла ошибка.
сбросить соединение. Сброс будет:
- откат любой открытой транзакции
- сброс уровня изоляции транзакций
- сброс переменных сессии
- удалить пользовательские переменные
- удалить временные таблицы
- удалить все утверждения PREPARE
connection.isValid() → boolean
Возвращает булево значение
Указывает состояние соединения, известное Коннектору. Если возвращается false, значит, с соединением возникли проблемы, например, сокет отключился без ведома Коннектора.
connection.destroy()
Закрывает соединение, не дожидаясь выполнения текущих запросов. Эти запросы прерываются. MariaDB регистрирует это событие как неожиданное закрытие сокета.
connection.pause()
Приостанавливает считывание данных.
connection.resume()
Возобновляет чтение данных после паузы.
connection.serverVersion()
Возвращает строку
Получает версию текущего подключенного сервера. Выбрасывает ошибку при отсутствии подключения к серверу.
console.log(connection.serverVersion()); //10.2.14-MariaDB
Ошибка
Когда коннектор сталкивается с ошибкой, Promise возвращает объект Error. В дополнение к стандартным свойствам, этот объект имеет следующие свойства:
- `fatal`: Булево значение, указывающее, остается ли соединение действительным.
- `errno`: Номер ошибки.
- `sqlState`: Код состояния SQL.
- `code`: Код ошибки.
Пример на `console.log(error)`:
{ Error: (conn=116, no: 1146, SQLState: 42S02) Таблица 'testn.falsetable' не существует sql: INSERT INTO falseTable(t1, t2, t3, t4, t5) values (?, ?, ?, ?, ?, ?) - parameters:[1,0x01ff,'hh','01/01/2001 00:00:00.000',null] ... at Socket.Readable.push (_stream_readable.js:134:10) at TCP.onread (net.js:559:20) От события: at C:\mariadb-connector-nodejs\lib\connection.js:185:29 at Connection.query (C:\mariadb-connector-nodejs\lib\connection.js:183:12) at Context.<anonymous> (C:\mariadb-connector-nodejs\test\integration\test-error.js:250:8) fatal: false, errno: 1146, sqlState: '42S02', код: 'ER_NO_SUCH_TABLE' } }
Ошибки содержат стек ошибок, запрос и значения параметров (длина которых по умолчанию ограничена 1024 символами). Чтобы получить начальную трассировку стека (показанную как `From event...` в примере выше), у вас должна быть включена опция Connection `trace`.
Для получения дополнительной информации о номерах ошибок и обозначениях состояний SQL смотрите документацию MariaDB Error Code.
события
Объект соединения, который наследуется от Node.js EventEmitter. Выдает событие ошибки при неожиданном закрытии соединения.
const conn = mariadb.createConnection({user: 'root', password: 'myPwd', host: 'localhost', socketTimeout: 100}) conn.on('error', err => { //будет выполнен через 100 мс из-за бездействия, сокет закрылся. console.log(err); //log : //{ Ошибка: (conn=6283, no: 45026, SQLState: 08S01) таймаут сокета // ... //atSocket.emit (events.js:208:7) //atSocket._onTimeout (net.js:410:8) //atontimeout (timers.js:498:11) //attryOnTimeout (timers.js:323:5) //atTimer.listOnTimeout (timers.js:290:5) // fatal: true, // errno: 45026, // sqlState: '08S01', // код: 'ER_SOCKET_TIMEOUT' } });
API пула
При каждом запросе соединения, если пул содержит соединение, которое не используется, пул будет проверять соединение, обмен пустым пакетом MySQL с сервером, чтобы убедиться в состоянии соединения, а затем отдать соединение. Пул интенсивно использует соединения, поэтому эта проверка выполняется только в том случае, если соединение не использовалось в течение определенного периода времени (задается параметром "minDelayValidation" со значением по умолчанию 500 мс).
Если соединение недоступно, запрос на соединение будет помещен в очередь до истечения времени соединения. Когда соединение становится доступным (новое создание или освобождение в пул), оно будет использоваться для удовлетворения запросов в очереди в порядке FIFO.
Когда соединение передается обратно в пул, все оставшиеся транзакции будут откатаны.
pool.getConnection(callback)
- `callback`: *function* Функция обратного вызова с аргументами (Error](#error), [Connection.
Создает новый объект Connection. Соединение должно быть передано обратно пулу с помощью метода connection.end().
Пример:
const mariadb = require('mariadb/callback'); const pool = mariadb.createPool({ host: 'mydb.com', user:'myUser' }); pool.getConnection((err, conn => { if (err) { console.log("не удалось подключиться из-за ошибки: " + err); } else { console.log("подключено ! идентификатор соединения - " + conn.threadId); conn.end(); //передача в пул } }));
pool.query(sql[, values][, callback])
- `sql`: *string | JSON* Строка SQL или объект JSON для замены стандартных опций подключения. При использовании объекта JSON, объект должен иметь ключ "sql". Например, `{ dateStrings: true, sql: 'SELECT now()' }`
- ``значения``: *массив | объект* Значения заполнителя. Обычно это массив, но в случаях, когда есть только один заполнитель, его можно указать как есть.
- `callback`: *function* Функция обратного вызова с аргументами (ошибка, результаты, метаданные).
Это быстрый способ получить соединение из пула, выполнить запрос и освободить соединение.
const mariadb = require('mariadb/callback'); const pool = mariadb.createPool({ host: 'mydb.com', user:'myUser' }); pool.query("SELECT NOW()", (err, rows, metadata) => { if (err) { // обработка ошибки } else { console.log(rows); //[ { { 'NOW()': 2018-07-02T17:06:38.000Z }, meta: [ ... ] ] } });
pool.batch(sql, values[, callback])
- `sql`: *string | JSON* Строка SQL или объект JSON для замены стандартных опций подключения. При использовании объекта JSON, объект должен иметь ключ "sql". Например, `{ dateStrings: true, sql: 'SELECT now()' }`
- `values`: *массив* массив значений плейсхолдеров. Обычно это массив массивов, но в случаях, когда на одно значение приходится только один плейсхолдер, он может быть задан как один массив.
- `callback`: *function* Функция обратного вызова с аргументами (ошибка, результаты, метаданные).
Это быстрый способ получить соединение из пула, выполнить пакет и освободить соединение.
const mariadb = require('mariadb/callback'); const pool = mariadb.createPool({ host: 'mydb.com', user:'myUser' }); pool.query( "CREATE TABLE parse(autoId int not null primary key auto_increment, c1 int, c2 int, c3 int, c4 varchar(128), c5 int)" ); pool .batch("INSERT INTO `parse`(c1,c2,c3,c4,c5) values (1, ?, 2, ?, 3)", [[1, "john"], [2, "jack"]], (err, res) => { if (err) { // обработка ошибки } else { //res = { affectedRows: 2, insertId: 1, warningStatus: 0 } assert.equal(res.affectedRows, 2); pool.query("select * from `parse`", (err, res) => { /* res = [ { autoId: 1, c1: 1, c2: 1, c3: 2, c4: 'john', c5: 3 }, { autoId: 2, c1: 1, c2: 2, c3: 2, c4: 'jack', c5: 3 }, meta: ... } */ }); } });
pool.end([callback])
- ``callback``: *функция* Функция обратного вызова с аргументом (Error).
Изящно закрывает пул и базовые соединения.
pool.end(err => { if (err) { // обработка ошибки console.log(err); } else { //соединения были завершены должным образом } });
События в pool'е
acquire | Это событие означает, что соединение было получено из пула. |
---|---|
connection | Это событие возникает, когда в пул добавляется новое соединение. Имеет параметр объекта соединения |
enqueue | Это событие возникает, когда команда не может быть немедленно удовлетворена пулом и ставится в очередь. |
release | Это событие возникает, когда соединение возвращается обратно в пул. Имеет параметр объекта соединения |
Пример:
pool.on('connection', (conn) => console.log(`соединение ${conn.threadId} было создано в пуле`);
API кластера пула
Кластер обрабатывает несколько пулов в соответствии с шаблонами и обрабатывает обход отказа / распределенную нагрузку (круговая / случайная / упорядоченная).
poolCluster.add(id, config)
- `id`: *строка* идентификатор узла. пример : 'master'.
- `config`: *JSON* pool options для создания пула.
Добавьте новый пул в кластер.
Пример:
const mariadb = require('mariadb/callback'); const cluster = mariadb.createPoolCluster(); cluster.add("master", { host: 'mydb1.com', user: 'myUser', connectionLimit: 5 }); cluster.add("slave1", { host: 'mydb2.com', user: 'myUser', connectionLimit: 5 }); cluster.add("slave2", { host: 'mydb3.com', user: 'myUser', connectionLimit: 5 });
poolCluster.remove(pattern)
- ``шаблон'': *строка* regex-шаблон для выбора пулов. Пример, `"slave*".
удалить и завершить пул(ы), сконфигурированные в кластере.
poolCluster.end([callback])
- ``callback``: *функция* Функция обратного вызова с аргументом (Error).
Закрывает кластер пулов и базовые пулы.
poolCluster(err => { if (err) { // обработка ошибки console.log(err); } else { //pool'ы были завершены должным образом } });
poolCluster.getConnection([pattern, ][selector, ]callback)
- ``шаблон'': *строка* regex-шаблон для выбора пулов. Пример, `"slave*"`. По умолчанию `'*'`.
- `селектор`: *строка* селектор пулов. Может быть 'RR' (round-robin), 'RANDOM' или 'ORDER' (использовать по порядку = всегда использовать первые пулы, если нет неудач). по умолчанию - 'RR'.
- `callback`: *function* Функция обратного вызова с аргументами (Error](#error), [Connection.
Создает новый объект Connection. Соединение должно быть передано обратно пулу с помощью метода connection.end().
Пример:
const mariadb = require('mariadb/callback'); const cluster = mariadb.createPoolCluster(); cluster.add("master", { host: 'mydb1.com', user: 'myUser', connectionLimit: 5 }); cluster.add("slave1", { host: 'mydb2.com', user: 'myUser', connectionLimit: 5 }); cluster.add("slave2", { host: 'mydb3.com', user: 'myUser', connectionLimit: 5 }); cluster.getConnection("slave*", (err, conn) => { //использовать соединение и обработать возможную ошибку })
события poolCluster
Объект PoolCluster наследуется от объекта Node.js EventEmitter. Выдает событие 'remove', когда узел удаляется из конфигурации, если определена опция `removeNodeErrorCount`. (по умолчанию 5) и коннектору не удается подключиться более `removeNodeErrorCount` раз. (если присутствуют другие узлы, каждая попытка будет ждать значения опции `restoreNodeTimeout`)
const mariadb = require('mariadb/callback'); const cluster = mariadb.createPoolCluster({ removeNodeErrorCount: 20, restoreNodeTimeout: 5000 }); cluster.add("master", { host: 'mydb1.com', user: 'myUser', connectionLimit: 5 }); cluster.add("slave1", { host: 'mydb2.com', user: 'myUser', connectionLimit: 5 }); cluster.add("slave2", { host: 'mydb3.com', user: 'myUser', connectionLimit: 5 });* cluster.on('remove', node => { console.log(`узел ${node} был удален`); })
poolCluster.of(pattern, selector) → FilteredPoolCluster
- ``шаблон'': *строка* regex-шаблон для выбора пулов. Пример, `"slave*"`. По умолчанию `'*'`.
- `селектор`: *строка* селектор пулов. Может быть 'RR' (round-robin), 'RANDOM' или 'ORDER' (использовать по порядку = всегда использовать первые пулы, если нет неудач). по умолчанию - 'RR'.
Возвращается
- разрешается с помощью объекта filtered pool cluster,
- вызывает Error.
Создает новый объект filtered pool cluster, который является подмножеством кластера.
Пример:
const mariadb = require('mariadb/callback') const cluster = mariadb.createPoolCluster(); cluster.add("master-north", { host: 'mydb1.com', user: 'myUser', connectionLimit: 5 }); cluster.add("master-south", { host: 'mydb1.com', user: 'myUser', connectionLimit: 5 }); cluster.add("slave1-north", { host: 'mydb2.com', user: 'myUser', connectionLimit: 5 }); cluster.add("slave2-north", { host: 'mydb3.com', user: 'myUser', connectionLimit: 5 }); cluster.add("slave1-south", { host: 'mydb2.com', user: 'myUser', connectionLimit: 5 }); const masterCluster = cluster.of('master*'); const northSlaves = cluster.of(/^slave?-north/, 'RANDOM'); northSlaves.getConnection((err, conn) => { //использовать это соединение });
Кластер фильтрованных pool'ов
- `filteredPoolCluster.getConnection(callback)` : Создает новое соединение из пулов, соответствующих шаблону.
- `filteredPoolCluster.query(sql[, values][, callback])` : это быстрый способ получить соединение из пулов, соответствующих шаблону, выполнить запрос и освободить соединение.