Pular para o conteúdo principal

MySQL2

Cliente MySQL para Node.js com foco em performance. Suporta instruções preparadas (prepared statements), Codificações non-utf8, protocolo de log binário (binary log protocol), compressão, SSL e muito mais.

NPM Version NPM Downloads Node.js Version GitHub Workflow Status (with event) Codecov License

Instalação​

O MySQL2 não tem restrições nativas e pode ser instalado no Linux, Mac OS ou Windows sem qualquer problema.

npm install --save mysql2

Primeira Consulta (Query)​

Para explorar mais exemplos de consulta (queries), visite a seção de exemplos Consultas Simples e Instruções Preparadas (Prepared Statements).

// Obtém o cliente
import mysql from 'mysql2/promise';

// Cria a conexão com o Banco de Dados
const connection = await mysql.createConnection({
  host: 'localhost',
  user: 'root',
  database: 'test',
});

// Consulta simples
try {
  const [results, fields] = await connection.query(
    'SELECT * FROM `table` WHERE `name` = "Page" AND `age` > 45'
  );

  console.log(results); // "results" contêm as linhas retornadas pelo servidor
  console.log(fields); // "fields" contêm metadados adicionais sobre os resultados, quando disponíveis
} catch (err) {
  console.log(err);
}

// Utilizando espaços reservados (placeholders)
try {
  const [results] = await connection.query(
    'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
    ['Page', 45]
  );

  console.log(results);
} catch (err) {
  console.log(err);
}

Usando Instruções Preparadas (Prepared Statements)​

Com o MySQL2 você também pode obter Instruções Preparadas (Prepared Statements). Dessa forma o MySQL não precisa preparar um plano para a mesma consulta todas as vezes, resultando em um melhor desempenho. Se você não sabe por que isso é importante, veja essa discussão:

O MySQL2 fornece o método auxiliar execute que irá preparar e consultar as declarações (statements) SQL. Além disso, você também pode usar os métodos prepare e unprepare para preparar ou desfazer a preparação de declarações (statements) manualmente, se necessário.

Para explorar mais exemplos de Instruções Preparadas (Prepared Statements), visite a seção de exemplos Instruções Preparadas (Prepared Statements).

import mysql from 'mysql2/promise';

try {
  // Cria a conexão com o Banco de Dados
  const connection = await mysql.createConnection({
    host: 'localhost',
    user: 'root',
    database: 'test',
  });

  // "execute" irá chamar internamente a preparação e a consulta (query)
  const [results, fields] = await connection.execute(
    'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
    ['Rick C-137', 53]
  );

  console.log(results); // "results" contêm as linhas retornadas pelo servidor
  console.log(fields); // "fields" contêm metadados adicionais sobre os resultados, quando disponíveis
} catch (err) {
  console.log(err);
}
dica

Se você executar a mesma declaração novamente, ela será selecionada a partir do LRU Cache, o que economizará tempo de preparação da consulta e proporcionará melhor desempenho.

Usando Conjunto de Conexões (pools)​

O conjunto de conexões (pools) ajuda a reduzir o tempo gasto na conexão com o servidor MySQL, reutilizando uma conexão anterior e deixando-as abertas ao invés de fechá-las quando você termina de usá-las.

Isto melhora a latência das consultas (queries), pois evita toda a sobrecarga associada à criação de uma nova conexão.

Para explorar mais exemplos de Conjunto de Conexões (pools), visite a seção de exemplos createPool.

import mysql from 'mysql2/promise';

// Cria a conexão (pool). As definições específicadas do "createPool" são as predefinições padrões
const pool = mysql.createPool({
  host: 'localhost',
  user: 'root',
  database: 'test',
  waitForConnections: true,
  connectionLimit: 10,
  maxIdle: 10, // Máximo de conexões inativas; o valor padrão é o mesmo que "connectionLimit"
  idleTimeout: 60000, // Tempo limite das conexões inativas em milissegundos; o valor padrão é "60000"
  queueLimit: 0,
  enableKeepAlive: true,
  keepAliveInitialDelay: 0,
});
nota

O pool não estabelece todas as conexões previamente, mas as cria sob demanda até que o limite de conexões seja atingido.

Você pode usar o pool da mesma maneira como em uma conexão (usando pool.query() e pool.execute()):

try {
  // Para a inicialização do "pool", veja acima
  const [rows, fields] = await pool.query('SELECT `field` FROM `table`');
  // A conexão é automaticamente liberada quando a consulta (query) é resolvida
} catch (err) {
  console.log(err);
}

Alternativamente, também existe a possibilidade de adquirir manualmente uma conexão do pool e liberá-la posteriormente:

// Para a inicialização do "pool", veja acima
const conn = await pool.getConnection();

// Fazer algo com a conexão
await conn.query(/* ... */);

// Não se esqueça de liberar a conexão quando terminar!
pool.releaseConnection(conn);

  • Adicionalmente, você pode liberar a conexão usando o objeto connection:

    conn.release();

Usando o Promise Wrapper​

O MySQL2 também suporta Promise API. O que funciona muito bem com o ES7 async await.

import mysql from 'mysql2/promise';

async function main() {
  // Cria a conexão com o Banco de Dados
  const connection = await mysql.createConnection({
    host: 'localhost',
    user: 'root',
    database: 'test',
  });

  // Consulta no Banco de Dados
  const [rows, fields] = await connection.execute(
    'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
    ['Morty', 14]
  );
}

O MySQL2 usa o objeto Promise padrão disponível no escopo. Mas você pode escolher qual implementação de Promise deseja usar.

// Obtém o cliente
import mysql from 'mysql2/promise';

// Obtém a implementação de "Promise" (nós usaremos o "bluebird")
import bluebird from 'bluebird';

// Cria a conexão, especificando o "bluebird" como "Promise"
const connection = await mysql.createConnection({
  host: 'localhost',
  user: 'root',
  database: 'test',
  Promise: bluebird,
});

// Consulta no Banco de Dados
const [rows, fields] = await connection.execute(
  'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
  ['Morty', 14]
);

MySQL2 also exposes a .promise() function on Pools, so you can create a promise/non-promise connections from the same pool.

import mysql from 'mysql2';

async function main() {
  // create the pool
  const pool = mysql.createPool({
    host: 'localhost',
    user: 'root',
    database: 'test',
  });

  // now get a Promise wrapped instance of that pool
  const promisePool = pool.promise();

  // query database using promises
  const [rows, fields] = await promisePool.query('SELECT 1');
}

O MySQL2 também expõe o método .promise() em Pools, então você pode criar conexões "promise/non-promise" para o mesmo pool.

const mysql = require('mysql2');

// Cria a conexão
const conn = mysql.createConnection({
  host: 'localhost',
  user: 'root',
  database: 'test',
});

conn
  .promise()
  .query('SELECT 1')
  .then(([rows, fields]) => {
    console.log(rows);
  })
  .catch(console.log)
  .then(() => conn.end());

Resultados em Array​

Se você tiver duas colunas com o mesmo nome, pode preferir receber os resultados como um array, em vez de um objeto, para evitar conflitos. Isso é uma divergência da biblioteca Node MySQL.

Por exemplo: SELECT 1 AS `foo`, 2 AS `foo`.

Você pode habilitar essa configuração tanto no nível de conexão (aplica-se a todas as consultas), quanto no nível de consulta (aplica-se apenas a essa consulta específica).

Connection Level​

const conn = await mysql.createConnection({
  host: 'localhost',
  database: 'test',
  user: 'root',
  rowsAsArray: true,
});

Query Level​

try {
  const [results, fields] = await conn.query({
    sql: 'SELECT 1 AS `foo`, 2 AS `foo`',
    rowsAsArray: true,
  });

  console.log(results); // nessa consulta, "results" contêm um array de arrays ao invés de um array de objetos
  console.log(fields); // "fields" mantêm-se inalterados
} catch (err) {
  console.log(err);
}
Obtendo Ajuda

Precisa de ajuda? Faça sua pergunta no Stack Overflow ou GitHub. Se você encontrou um erro, registre-o no GitHub.