原文地址:https://github.com/mysqljs/mysql

安装

$ npm install mysql

有关前述0.9.x版本的版本信息,请访问V0.9分支

当有bug修正时,建议从Github上拉取最新版本代码,可执行如下命令:

$ npm install mysqljs/mysql

介绍

这是MySQL的一个node.js驱动程序,用JavaScript编写,不需要编译,并且100%遵循MIT协议。

下面是一个如何使用本程序的示例:

var mysql      = require('mysql');
var connection = mysql.createConnection({
  host     : 'localhost',
  user     : 'me',
  password : 'secret',
  database : 'my_db'
});

connection.connect();

connection.query('SELECT 1 + 1 AS solution', function(err, rows, fields) {
  if (err) throw err;

  console.log('The solution is: ', rows[0].solution);
});

connection.end();

从这个例子里,可以了解到:

  • 在connection上调用的每个方法都会加入队列,并按顺序执行;
  • 关闭connection可使用end()方法。它可以确保在发送数据包到mysql服务器之前将剩下的所有查询执行完成。

建立连接

推荐使用如下方法建立连接:

var mysql      = require('mysql');
var connection = mysql.createConnection({
  host     : 'example.org',
  user     : 'bob',
  password : 'secret'
});

connection.connect(function(err) {
  if (err) {
    console.error('error connecting: ' + err.stack);
    return;
  }

  console.log('connected as id ' + connection.threadId);
});

还可以通过调用查询,来隐式建立连接:

var mysql      = require('mysql');
var connection = mysql.createConnection(...);

connection.query('SELECT 1', function(err, rows) {
  // connected! (unless `err` is set)
});

可以根据你处理错误的习惯,来选择更合适的方法。任何类型的连接错误(握手或网络)都是致命的错误。

connection选项

建立连接时,可以设置以下选项:

  • host: 要连接的数据库的主机名。(默认: localhost);
  • port: 连接的端口号。 (默认:3306);
  • localAddress: TCP连接的IP地址。(可选的);
  • socketPath: 连接到 Unix域套接字的路径。当使用时hostport被忽略;
  • user:作为身份验证的MySQL的用户名;
  • password:MySQL用户的密码;
  • database: 用于练级的数据库名称(可选);
  • charset:用于连接的字符集。这就是在MySQL中所谓的“collation”级的字符集(如utf8_general_ci)。如果指定了一个SQL级字符集(如utf8mb4),则使用该字符集的默认collation值。(默认:”UTF8_GENERAL_CI’`);
  • timezone:用来存放本地日期的时区。(默认:”local’`);
  • connectTimeout:MySQL服务器连接超时时间,单位为毫秒。 (默认:10000);
  • stringifyObjects:字符串化对象,而不是转化为字面量。可查看issues[#501](https://github.com/mysqljs/mysql/issues/501)。 (默认:false);
  • insecureAuth:允许连接到使用(不安全的)旧版本的身份验证方法的MySQL实例 。(默认:false);
  • typeCast:column值是否应转换为本地JavaScript类型。 (默认:true);
  • queryFormat:自定义查询格式功能;
  • supportBigNumbers:当对数据库中的大数字(BIGINTDECIMAL columns)进行处理时,应启用该选项(默认:false);
  • bigNumberStrings:可同时将supportBigNumbersbigNumberStrings转换成大数字。 (BIGINTDECIMAL columns)总是返回的JavaScript字符串对象(默认:false)。 启用supportBigNumbers且禁止bigNumberStrings,只有在不能精确地表示JavaScript Number对象(当他们超出[-2^53, 2^53]范围)时,返回大数字为String对象,否则返回Number对象。如果supportBigNumbers已禁用,该选项被忽略。
  • dateStrings:强制日期类型(TIMESTAMP,DATETIME,DATE)转换为字符串,而不是JavaScript Date对象。(默认:false);
  • debug:打印协议细节到stdout。 (默认:false
  • trace:生成包含函数库调用位置的Error 的堆栈跟踪(“长堆栈跟踪”)。大多数情况下会有轻微的性能损失。(默认:true);
  • multipleStatements:允许一个查询中含有多个MySQL语句。但须谨慎使用,因为它会增加SQL注入攻击的范围。 (默认:false);
  • flags:使用的连接标记的列表,而不是默认值。它也可以将默认值列入黑名单;
  • ssl:含有ssl参数中的对象,或ssl配置文件名称的字符串。

除了将这些选项作为对象传入,你也可以使用一个url字符串。例如:

var connection = mysql.createConnection('mysql://user:pass@host/db?debug=true&charset=BIG5_CHINESE_CI&timezone=-0700');

注意:查询值会首先尝试解析为JSON,如果失败,则将其假定为明文字符串。

SSL 选项

在连接选项中,ssl选项是一个字符串或对象。当给定一个字符串,他会使用其中一个引入的预定义SSL配置文件。

引入的配置文件如下:

  • "Amazon RDS" :该配置文件用于连接到亚马逊RDS服务器,并包含 https://rds.amazonaws.com/doc/rds-ssl-ca-cert.pem和 https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem的证书。

当连接到其他服务器时,您需要提供一个options对象。该options对象的格式与crypto.createCredentials相同。

请注意,参数为证书字符串,而不是文件名的 证书。下面是一个简单的例子:

var connection = mysql.createConnection({
  host : 'localhost',
  ssl  : {
    ca : fs.readFileSync(__dirname + '/mysql-ca.crt')
  }
});

您还可以连接到一个没有提供适当的 CA信任的MySQL服务器。 建议这么做

var connection = mysql.createConnection({
  host : 'localhost',
  ssl  : {
    // DO NOT DO THIS
    // set up your ca correctly to trust the connection
    rejectUnauthorized: false
  }
});

终止连接

有两种方法终止连接。

终止连接是可以调用end() 方法来实现:

connection.end(function(err) {
  // The connection is terminated now
});

这将确保所有队列中的查询在发送 COM_QUIT包到MySQL服务器之前执行。如果在COM_QUIT包发送前出现致命错误,err参数将被传到回调函数中,连接将终止。

断开连接的另一种方法,是调用destroy()方法。 这会导致潜在的基础socket立即终止。

另外destroy()保证没有更多的事件或回调函数来 触发连接。

connection.destroy();

end()不同的是,destroy()不需要传入一个回调参数。

池连接

直接使用连接池。

var mysql = require('mysql');
var pool  = mysql.createPool({
  connectionLimit : 10,
  host            : 'example.org',
  user            : 'bob',
  password        : 'secret',
  database        : 'my_db'
});

pool.query('SELECT 1 + 1 AS solution', function(err, rows, fields) {
  if (err) throw err;

  console.log('The solution is: ', rows[0].solution);
});

连接可以汇聚到连接池中,以缓解共享一个连接,或管理 多个连接。

var mysql = require('mysql');
var pool  = mysql.createPool({
  host     : 'example.org',
  user     : 'bob',
  password : 'secret',
  database : 'my_db'
});

pool.getConnection(function(err, connection) {
  // connected! (unless `err` is set)
});

当完成一个连接时,只需要调用connection.release(), 连接将返回到连接池中,准备要由别人再次使用。

var mysql = require('mysql');
var pool  = mysql.createPool(...);

pool.getConnection(function(err, connection) {
  // Use the connection
  connection.query( 'SELECT something FROM sometable', function(err, rows) {
    // And done with the connection.
    connection.release();

    // Don't use the connection here, it has been returned to the pool.
  });
});

如果想关闭连接,并从连接池中移除它,可使用 connection.destroy()来代替。连接池将在下一次调用时创建一个新的连接。

连接在连接池中是懒连接的。如果配置池允许 多达100个连接,但只同时使用5个,那么只有5个连接 将被创建。连接使用循环模式,从连接池的顶部开始调用,并返回到底部。

当先前的连接从池中移出时,ping数据包被发送 到服务器,检查连接是否仍然良好。

连接池选项

连接池接受所有与connection相同的options参数。 当创建一个新连接时,options参数将被简单地传递给connection构造函数。除了这些options参数,连接池还接受一些额外的参数:

  • acquireTimeout: 连接超时的时间,单位为毫秒。这与connectTimeout略有不同,因为回收连接不总是涉及建立连接。(默认:10000);
  • waitForConnections: 确定连接池的操作时,是否没有可用的连接并且已达到限制。如果是true,连接池将请求加入队列,并当其可用时进行调用调用。如果是false,连接池将立即返回一个错误。(默认:true);
  • connectionLimit: 一次性创建的最大连接数。(默认:10);
  • queueLimit: 从getConnection返回一个错误之前,连接池中加入队列的最大连接请求数。如果设置为0,则不限制队列中的连接请求数目。(默认:0);

连接池 事件

… … 未完待续 … …


本文作者:子匠_Zijor,转载请注明出处:http://www.dengzhr.com/node-js/908