Connector/Node.js Callback API

You are viewing an old version of this article. View the current version here.

Документация

Существует две различные реализации соединения: одна, по умолчанию, использует 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:

Connect:

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:

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*
hostIP-адрес или 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

Возварщает объект 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

Возвращает объект 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])

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

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)

Создает новый объект 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, который является подмножеством кластера.

Пример:

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])` : это быстрый способ получить соединение из пулов, соответствующих шаблону, выполнить запрос и освободить соединение.

Comments

Comments loading...
Content reproduced on this site is the property of its respective owners, and this content is not reviewed in advance by MariaDB. The views, information and opinions expressed by this content do not necessarily represent those of MariaDB or any other party.