Table of contents

• About
  • Features
  • Protocol
  • Contact
• Installation
  • Manual install
  • Manual update
  • Automatic install
  • Automatic update
• Quick start
  • Client example
  • Pool example
• Client
  • Client options
  • Client properties
  • Client functions
  • Client events
  • Client context
  • Error
  • Task queue
  • Authentication
  • TLS
  • RSA
  • Implicit connection
  • Disconnect
  • Timeout
  • Time zone and offset
  • Multiple statement query
  • Query stream
  • Pause and resume
  • Execute
  • Lock
  • Client promise
• Pool
  • Pool options
  • Pool properties
  • Pool client properties
  • Pool functions
  • Pool client functions
  • Pool events
  • Pool context
  • Acquire
  • Pool promise
• Escaper
  • Escaper functions
  • Escaper types
  • Format syntax
  • Escaping and formatting
• Parser
  • Parser functions
  • Parser types
  • Row parsing
  • Info parsing
• Utility
  • Utility properties
  • Utility functions

About

Features

• completely free
• no dependencies
• written in JavaScript
• entirely asynchronous
• MariaDB and MySQL protocol
• TLS connection
• RSA authentication
• plugin authentication
• interactive connection
• implicit connection
• connection pool
• promise deferment
• task queue
• request queue
• client side timeouts
• multiple statement query
• query streaming
• custom row parsing
• escaping and formatting

Protocol

The library implements the text protocol of MariaDB and MySQL. The documentation is suitable for developers who want to write their own client library without the hassle of following incorrect sources.

Contact

For any problems, suggestions and questions you can send messages to elusiveorganization@gmail.com.

Installation

Manual install

Visit the repository, download the source and place it in your directory of choice.

Manual update

Remove the old library, visit the repository, download the source and place it in your directory of choice.

Automatic install

npm install anita

Automatic update

npm update anita

Quick start

Client example

var anita = require("anita");
var client = new anita.Client();

client.connect(function(error) {
	if (error !== null) {
		console.log(error);
		return;
	}
	this.query("select * from shelter.animals", function(error, result) {
		this.disconnect(function(error) {
			if (error !== null) {
				console.log(error)
			}
		});
		if (error !== null) {
			console.log(error);
			return;
		}
		console.log(result);
	});
});

Pool example

var anita = require("anita");
var pool = new anita.Pool();

pool.acquire(function(error, client) {
	if (error !== null) {
		console.log(error);
		return;
	}
	client.query("select * from shelter.animals", function(error, result) {
		this.release();
		this.pool.disconnect(function(error) {
			if (error !== null) {
				console.log(error)
			}
		});
		if (error !== null) {
			console.log(error);
			return;
		}
		console.log(result);
	});
});

Client

Client options

• charset (number) - client character set (default is Constant.charset.UTF8MB4_GENERAL_CI)
• user (string) - user (default is "root")
• password (string) - password (default is "")
• database (string) - database (default is "")
• authenticationMethod (null | string) - client default authentication method - "native_password", "sha256_password", "caching_sha2_password" or null (default is null)
• multipleStatements (boolean) - use multiple statements in the query (default is false)
• interactive (boolean) - interactive client (default is false)
• autoConnect (boolean) - automatically connect if not connected before a task (default is true)
• autoDisconnect (boolean) - automatically disconnect when no more tasks are left (default is false)
• finalizeTask (boolean) - call the callback with an error if the client is active during destroy (default is false)
• clearTasks (boolean) - remove all queued tasks after disconnect (default is false)
• idleTimeout (number) - milliseconds before idle client timeouts (default is -1)
• connectTimeout (number) - milliseconds before connecting client timeouts (default is -1)
• busyTimeout (number) - milliseconds before busy client timeouts (default is -1)
• parseRow (function) - function used to parse a row (default is parser.parseRowAsArray)
• timeOffset (null | number) - time offset in minutes for escaping and parsing dates (default is null)
• path (string) - IPC path
• port (number) - port (default is 3306)
• host (string) - host (default is "localhost")
• localAddress (string) - local address a socket should connect from
• localPort (number) - local port a socket should connect from
• family (number) - version of IP stack - 4 or 6
• hints (number) - optional dns.lookup() hints
• lookup (function) - custom lookup function
• publicKey (null | string) - RSA public key (default is null)
• secureContext (null | object) - secure context object from tls.createSecureContext() (default is null)
• rejectUnauthorized (boolean) - reject unauthorized server (default is true)

Client properties

• all client options
• client.server (null | object) - server details
  • protocol (number) - protocol version
  • version (string) - server version
  • isMaria (boolean) - is it MariaDB
  • threadId (number) - connection thread id
  • charset (number) - server character set
  • authenticationMethod (string) - server default authentication method
• client.tasks (array) - queued tasks
• client.paused (boolean) - is the client paused
• client.active (boolean) - is the client active

Client functions

• client.pause() - pauses during query streaming
• client.resume() - resumes during query streaming
• client.next() - proceeds with the next task
• client.connect([options, ]callback) - connects to the server
  • options (object) - options (optional)
    • charset (number) - client character set (optional)
    • user (string) - user (optional)
    • password (string) - password (optional)
    • database (string) - database (optional)
    • authenticationMethod (null | string) - client authentication method (optional)
    • multipleStatements (boolean) - use multiple statements in the query (optional)
    • interactive (boolean) - interactive client (optional)
    • timeout (number) - milliseconds before connecting client timeouts (optional)
  • callback (function) - callback
    • error (null | object) - error
• client.disconnect([options, ]callback) - disconnects from the server
  • options (object) - options (optional)
    • timeout (number) - milliseconds before busy client timeouts (optional)
  • callback (function) - callback
    • error (null | object) - error
• client.destroy() - abruptly disconnects from the server and stops the task execution
• client.query(text | options, callback) - executes a query
  • text (string) - query
  • options (object) - options
    • text (string) - query
    • parseRow (function) - function used to parse a row (optional)
    • timeOffset (null | number) - time offset in minutes for escaping and parsing dates (optional)
    • timeout (number) - milliseconds before busy client timeouts (optional)
  • callback (function) - callback
    • error (null | object) - error
    • result (array | object | type) - ok or table (optional)
• client.streamQuery(text | options, callback) - executes a query with callback streaming
  • text (string) - query
  • options (object) - options
    • text (string) - query
    • parseRow (function) - function used to parse a row (optional)
    • timeOffset (null | number) - time offset in minutes for escaping and parsing dates (optional)
    • timeout (number) - milliseconds before busy client timeouts (optional)
  • callback (function) - callback
    • error (null | object) - error
    • result (null | array | object | type) - row or ok (optional)
• client.emitQuery(text | options[, emitter]) - executes a query with event emitter streaming
  • text (string) - query
  • options (object) - options
    • text (string) - query
    • parseRow (function) - function used to parse a row (optional)
    • timeOffset (null | number) - time offset in minutes for escaping and parsing dates (optional)
    • timeout (number) - milliseconds before busy client timeouts (optional)
  • emitter (object) - event emitter (optional)
    • error - after an error
      • error (null | object) - error
    • result - after each row or ok
      • result (array | object | type) - row or ok
    • end - after end
  • return (object) - event emitter
    • error - after an error
      • error (null | object) - error
    • result - after each row or ok
      • result (array | object | type) - row or ok
    • end - after end
• client.changeDatabase([database | options, ]callback) - changes the database
  • database (string) - database (optional)
  • options (object) - options (optional)
    • database (string) - database (optional)
    • timeout (number) - milliseconds before busy client timeouts (optional)
  • callback (function) - callback
    • error (null | object) - error
• client.statistics([options, ]callback) - gets statistics
  • options (object) - options (optional)
    • timeout (number) - milliseconds before busy client timeouts (optional)
  • callback (function) - callback
    • error (null | object) - error
    • result (string) - statistics (optional)
• client.ping([options, ]callback) - pings the server
  • options (object) - options (optional)
    • timeout (number) - milliseconds before busy client timeouts (optional)
  • callback (function) - callback
    • error (null | object) - error
• client.changeUser([options, ]callback) - changes character set, user, password, database and authentication method
  • options (object) - options (optional)
    • charset (number) - client character set (optional)
    • user (string) - user (optional)
    • password (string) - password (optional)
    • database (string) - database (optional)
    • authenticationMethod (null | string) - client authentication method (optional)
    • timeout (number) - milliseconds before busy client timeouts (optional)
  • callback (function) - callback
    • error (null | object) - error
• client.resetConnection([options, ]callback) - reset the session state
  • options (object) - options (optional)
    • timeout (number) - milliseconds before busy client timeouts (optional)
  • callback (function) - callback
    • error (null | object) - error
• client.execute([options, ]callback) - execute a function
  • options (object) - options for the callback will be called with (optional)
    • timeout (number) - milliseconds before busy client timeouts (optional)
  • callback (function) - callback
    • error (null | object) - error
    • options (object) - execute options (optional)
• client.deferConnect([options]) - defers connect to a promise
  • all connect options without callback
  • return (object) - promise
• client.deferDisconnect([options]) - defers disconnect to a promise
  • all disconnect options without callback
  • return (object) - promise
• client.deferQuery(text | options) - defers query to a promise
  • all query options without callback
  • return (object) - promise
• client.deferChangeDatabase([database | options]) - defers change database to a promise
  • all change database options without callback
  • return (object) - promise
• client.deferStatistics([options]) - defers statistics to a promise
  • all statistics options without callback
  • return (object) - promise
• client.deferPing([options]) - defers ping to a promise
  • all ping options without callback
  • return (object) - promise
• client.deferChangeUser([options]) - defers change user to a promise
  • all change user options without callback
  • return (object) - promise
• client.deferResetConnection([options]) - defers reset connection to a promise
  • all reset connection options without callback
  • return (object) - promise
• client.deferExecute([options]) - defers execute to a promise
  • all execute options without callback
  • return (object) - promise
• client.createConnect([options, ]callback) - creates connect task
  • all connect options
  • return (object) - task
• client.createDisconnect([options, ]callback) - creates disconnect task
  • all disconnect options
  • return (object) - task
• client.createQuery(text | options, callback) - creates query task
  • all query options
  • return (object) - task
• client.createStreamQuery(text | options, callback) - creates stream query task
  • all stream query options
  • return (object) - task
• client.createChangeDatabase([database | options, ]callback) - creates change database task
  • all change database options
  • return (object) - task
• client.createStatistics([options, ]callback) - creates statistics task
  • all statistics options
  • return (object) - task
• client.createPing([options, ]callback) - creates ping task
  • all ping options
  • return (object) - task
• client.createChangeUser([options, ]callback) - creates a change user task
  • all change user options
  • return (object) - task
• client.createResetConnection([options, ]callback) - creates a reset connection task
  • all reset connection options
  • return (object) - task
• client.createExecute([options, ]callback) - creates an execute task
  • all execute options
  • return (object) - task
• client.lock([options, ]callback) - blocks the task execution indefinitely during callback
  • options (object) - options (optional)
    • timeout (number) - milliseconds before busy client timeouts (optional)
  • callback (function) - callback
    • error (null | object) - error
    • ...arguments (type) - arguments (optional)
  • return (function) - closer of the callback
    • error (null | object) - error
    • ...arguments (type) - arguments (optional)

Client events

• connect - after the connection is opened and before the callback call
• disconnect - after the connection is closed and before the callback call
• error - after an internal error and before the next task
  • error (object) - internal error

Client context

Each callback function is called with the context set to the client.

client.connect(function(error) {
	if (error !== null) {
		console.log(error);
		return;
	}
	this.query("select * from animals", function(error, result) {
		this.disconnect(function(error) {
			if (error !== null) {
				console.log(error);
			}
		});
		if (error !== null) {
			console.log(error);
			return;
		}
		console.log(result);
	});//this === client
});

Error

Every callback will take as a first argument an error which will be null or else. If the connection is lost the server will be set to null. If there is error in the internals of the library the connection will be closed and the callback will be called or the error will be emitted. If you throw an error in the callback it will not be caught.

client.statistics(function(error, result) {
	if (error !== null) {
		throw error;//uncaught exception
	}
	console.log(result);
});

Task queue

If the client is currently active the task will be queued. At the end of a task the callback will be called and then the client will continue with the next tasks. It's safe to manipulate the task queue.

client.connect(function(error) {
	if (error !== null) {
		console.log(error);
		this.tasks = [];//removes the queued tasks
	}
});//executed
client.query(function("select * from animals", function(error, result) {
	if (error !== null) {
		console.log(error);
		return;
	}
	console.log(result);
});//queued
client.disconnect(function(error) {
	if (error !== null) {
		console.log(error);
	}
});//queued

client.connect(function(error) {
	if (error !== null) {
		console.log(error);
		this.tasks = [];
		return;
	}
	this.query(function("select * from animals", function(error, result) {
		if (error !== null) {
			console.log(error);
			return;
		}
		console.log(result);
	});//executed before disconnect
});
client.disconnect(function(error) {
	if (error !== null) {
		console.log(error);
	}
});

client.connect(function(error) {
	if (error !== null) {
		console.log(error);
		this.tasks = [];
	}
});
client.query("select count(*) from animals where name = 'Anita'", function(error, result) {
	if (error !== null) {
		console.log(error);
		return;
	} else if (result[0][0] > 0) {
		this.tasks.shift();//removes the task before disconnect
	}
});
client.query("insert into animals values (0, 'Anita', true, '2009-01-22', 'cat')", function(error, result) {
	if (error !== null) {
		console.log(error);
	}
});
client.disconnect(function(error) {
	if (error !== null) {
		console.log(error);
	}
});

client.connect(function(error) {
	if (error !== null) {
		console.log(error);
		this.tasks = [];
	}
});
client.query("select count(*) from animals where name = 'Anita'", function(error, result) {
	if (error !== null) {
		console.log(error);
		return;
	} else if (result[0][0] > 0) {
		return;
	}
	this.tasks.unshift({
		callee: this.query,
		arguments: [
			"insert into animals values (0, 'Anita', true, '2009-01-22', 'cat')",
			function(error, result) {
				if (error !== null) {
					console.log(error);
				}
			}
		]
	});//adds the task before disconnect
});
client.disconnect(function(error) {
	if (error !== null) {
		console.log(error);
	}
});

Authentication

The client can connect to servers using native_password, sha256_password and caching_sha2_password plugins. Authentication using sha256_password or caching_sha2_password requires TLS credentials or RSA key pair and a server compiled with OpenSSL. If default authentication method isn't provided the one from the server is used. If a public key isn't provided the client will request it from the server.

TLS

You can connect to the server securely using the TLS protocol. For the server to be able to use TLS you have to set ssl, ssl-ca, ssl-cert and ssl-key in the options.

var fs = require("fs");
var tls = require("tls");
var anita = require("anita");
var client = new anita.Client({
	user: "user",
	password: "password",
	secureContext: tls.createSecureContext({ca: fs.readFileSync("./tls/ca_cert.pem")})
});

RSA

Providing a RSA public key spares you additional unsecure packet exchange with the server for encrypting sha256 password (sha256_password or caching_sha2_password plugins). For the server to be able to use the RSA you have to set sha256_password_private_key_path, sha256_password_public_key_path, caching_sha2_password_private_key_path and caching_sha2_password_public_key_path in the options.

var fs = require("fs");
var anita = require("anita");
var client = new anita.Client({
	user: "user",
	password: "password",
	publicKey: fs.readFileSync("./rsa/public_key.pem", "utf8")
});

Implicit connection

With automatic connection the client will connect implicitly if needed before executing a task that requires connection. With automatic disconnection the client will disconnect after there is no more tasks to execute.

//implicit connect
client.query("select * from animals where sex = false", function(error, result) {
	if (error !== null) {
		console.log(error);
		return;
	}
	console.log(result);
});
client.query("select * from animals where sex = true", function(error, result) {
	if (error !== null) {
		console.log(error);
		return;
	}
	console.log(result);
});
//implicit disconnect

//implicit connect
client.query("select * from animals where sex = false", function(error, result) {
	if (error !== null) {
		console.log(error);
		//implicit disconnect
		return;
	}
	console.log(result);
	this.query("select * from animals where sex = true", function(error, result) {
		if (error !== null) {
			console.log(error);
			//implicit disconnect
			return;
		}
		console.log(result);
		//implicit disconnect
	});
});

Disconnect

The proper way of disconnecting from the server is by using disconnect. Disconnect will be queued and will wait for the server to close the socket. Destroy will close the socket immediately and will not proceed with the next task.

client.connect(function(error) {
	if (error !== null) {
		console.log(error);
		return;
	}
	this.disconnect(function(error) {
		if (error !== null) {
			console.log(error);
		}
	});
});

Timeout

There is server and client side timeout. On the server side there is interactive_timeout and wait_timeout for the connection, lock_wait_timeout for locks, max_execution_time for select query, net_write_timeout for the server write and others. On the client side there is idle timeout for the connection, connect timeout for the connecting and task timeout for each task. It is recommended to use the server side timeout, because it's more precise, effective and leads to proper disconnecting.

client.connect({timeout: 30000}, function(error) {
	if (error !== null) {
		console.log(error);
		return;
	}
	this.disconnect(function(error) {
		if (error !== null) {
			console.log(error);
		}
	});
});

Time zone and offset

There is server and client side time zone and offset settings. On the server side there is default-time-zone for the options, time_zone global and session variable, convert_tz function and others. On the client side there is time offset in minutes for escaping and parsing dates. It is recommended to use the server side time zone and offset settings, because it's more flexible, effective and leads to better compatibility.

client.query({text: "select * from animals", timeOffset: 60}, function(error, result) {//+01:00 in minutes
	if (error !== null) {
		console.log(error);
		return;
	}
	console.log(result);
});

Multiple statement query

Multiple statement query may return more than one result grouped in an array.

client.query("select * from animals where sex = false;"
+ "select * from animals where sex = true;", function(error, result) {
	this.disconnect(function(error) {
		if (error !== null) {
			console.log(error);
		}
	});
	if (error !== null) {
		console.log(error);
		return;
	}
	console.log(result[0]);//first result
	console.log(result[1]);//second result
});

Query stream

There is callback and event emitter streaming.

client.streamQuery("select * from animals", function(error, result) {
	if (error !== null) {
		console.log(error);
	} else if (result !== null) {
		console.log(result);
	} else {
		this.disconnect(function(error) {
			if (error !== null) {
				console.log(error);
			}
		});
	}
});

client.emitQuery("select * from animals").on("error", function(error) {
	console.log(error);
}).on("result", function(result) {
	console.log(result);
}).on("end", function() {
	client.disconnect(function(error) {
		if (error !== null) {
			console.log(error);
		}
	});
});

Pause and resume

With pause and resume you can pause and resume the reading of the socket data and its handling. To prevent connection timeout set net_write_timeout to a suitable value in the options.

client.emitQuery("select * from animals").on("error", function(error) {
	console.log(error);
}).on("result", function(result) {
	console.log(result);
	client.pause();
	setTimeout(function() {
		client.resume();
	}, 100);
}).on("end", function() {
	client.disconnect(function(error) {
		if (error !== null) {
			console.log(error);
		}
	});
});

Execute

Execute gives you the ability to queue your own functions on a connected or disconnected client.

client.execute(function(error) {
	if (error !== null) {
		console.log(error);
		return;
	}
	this.database = "shelter";
});
client.changeDatabase(function(error) {
	if (error !== null) {
		console.log(error);
	}
});
client.query("select * from animals", function(error, result) {
	if (error !== null) {
		console.log(error);
		return;
	}
	console.log(result);
});

Lock

With execute and lock you can block the task execution without stalling the program. Any new tasks will be queued until you call the returned function or an error happens. The callback will be called only once even if error happens.

client.execute(function(error) {
	if (error !== null) {
		console.log(error);
		return;
	}
	setTimeout(this.lock(function(error, result) {
		if (error !== null) {
			console.log(error);
			return;
		}
		console.log(result);
	}), 100, null, "end");
});

Client promise

With the defer functions you can get a promise for a task.

client.deferConnect().then(function() {
	client.deferQuery("select * from animals").then(function(result) {
		client.deferDisconnect().catch(function(error) {
			console.log(error);
		});
		console.log(result);
	}, function(error) {
		client.deferDisconnect().catch(function(error) {
			console.log(error);
		});
		console.log(error);
	});
}, function(error) {
	console.log(error);
});

(async function() {
	try {
		await client.deferConnect();
	} catch (e) {
		console.log(e);
		return;
	}
	try {
		console.log(await client.deferQuery("select * from animals"));
	} catch (e) {
		console.log(e);
	}
	try {
		await client.deferDisconnect();
	} catch (e) {
		console.log(e);
	}
})();

Pool

Pool options

• all client options
• finalizeRequests (boolean) - call all queued requests with an error on destroy and disconnect (default is false)
• maxClients (number) - maximum clients (default is 10)
• maxRequests (number) - maximum requests (default is 4294967296)

Pool properties

• all client options
• pool.active (boolean) - is the pool active

Pool client properties

• client.free (boolean) - is the client released to the pool
• client.pool (object) - the pool the client belongs to

Pool functions

• pool.acquire(callback) - requests a client from the pool
  • callback (function) - callback
    • error (null | object) - error
    • client (object) - client (optional)
• pool.deferAcquire() - defer acquire to a promise
  • return (object) - promise
• pool.disconnect(callback) - disconnects all clients from the pool
  • callback - callback function
    • error (null | object) - error
• pool.deferDisconnect() - defer disconnect to a promise
  • return (object) - promise
• pool.destroy() - abruptly disconnects all clients from the pool

Pool client functions

• client.release() - clears all queued tasks and returns the client to the pool

Pool events

• connect - after a connection is opened and before the callback call
  • client (object) - client
• disconnect - after all connections are closed and before the callback call
• idle - after all clients are released to the pool

Pool context

Each callback function is called with the context set to the pool.

pool.acquire(function(error, client) {
	if (error !== null) {
		console.log(error);
		return;
	}
	client.release();
	this.disconnect(function(error) {
		if (error !== null) {
			console.log(error);
		}
	});//this === pool
});

Acquire

The pool creates and connects clients on demand, then reuses them for each request until they are disconnected by the user or the server.

pool.acquire(function(error, client) {
	if (error !== null) {
		console.log(error);
		return;
	}
	client.query("select * from animals where sex = false", function(error, result) {
		this.release();
		if (error !== null) {
			console.log(error);
			return;
		}
		console.log(result);
	});
});
pool.acquire(function(error, client) {
	if (error !== null) {
		console.log(error);
		return;
	}
	client.query("select * from animals where sex = true", function(error, result) {
		this.release();
		if (error !== null) {
			console.log(error);
			return;
		}
		console.log(result);
	});
});
pool.once("idle", function() {
	this.disconnect(function(error) {
		if (error !== null) {
			console.log(error);
		}
	});
});

Pool promise

With the defer functions you can get a promise for a request or a disconnect.

pool.deferAcquire().then(function(client) {
	client.deferQuery("select * from animals").then(function(result) {
		client.release();
		client.pool.deferDisconnect().catch(function(error) {
			console.log(error);
		});
		console.log(result);
	}, function(error) {
		client.release();
		client.pool.deferDisconnect().catch(function(error) {
			console.log(error);
		});
		console.log(error);
	});
}, function(error) {
	console.log(error);
});

(async function() {
	var c;
	try {
		c = await pool.deferAcquire();
	} catch (e) {
		console.log(e);
		return;
	}
	try {
		console.log(await c.deferQuery("select * from animals"));
	} catch (e) {
		console.log(e);
	}
	c.release();
	try {
		await pool.deferDisconnect();
	} catch (e) {
		console.log(e);
	}
})();

Escaper

Escaper functions

• Escaper.escapeRaw(value) - prepare any value as a string for further escaping
  • value (type) - value
  • return (object) - object
• Escaper.escapeRawId(value) - prepare a string as an identifier for further escaping
  • value (string) - string
  • return (object) - object
• Escaper.escapeRawSet(value) - prepare an array as a set literal for further escaping
  • value (array) - array
  • return (object) - object
• Escaper.escapeFormat(value) - escapes a format string
  • value (string) - string
  • return (string) - string
• Escaper.escapeId(value) - escapes a string as a identifier
  • value (string) - string
  • return (string) - string
• Escaper.escapeString(value) - escapes a string as a string literal
  • value (string) - string
  • return (string) - string
• Escaper.escapeDate(value[, timeOffset]) - escapes a date as a date and time literal
  • value (date) - date
  • timeOffset (number) - time offset in minutes (optional)
  • return (string) - string
• Escaper.escapeBuffer(value) - escapes a buffer as a hexadecimal literal
  • value (buffer) - buffer
  • return (string) - string
• Escaper.escapeSet(value) - escapes an array as a set literal
  • value (array) - array
  • return (string) - string
• Escaper.escapeArray(value[, timeOffset]) - escapes an array as a list
  • value (array) - array
  • timeOffset (number) - time offset in minutes (optional)
  • return (string) - string
• Escaper.escapeArrays(value[, timeOffset]) - escapes a two-dimensional array as a two-dimensional list
  • value (array) - two-dimensional array
  • timeOffset (number) - time offset in minutes (optional)
  • return (string) - string
• Escaper.escapeObject(value[, timeOffset]) - escapes an object as an associative list
  • value (object) - object
  • timeOffset (number) - time offset in minutes (optional)
  • return (string) - string
• Escaper.escape(value[, timeOffset]) - escapes any value to their equivalents
  • value (null | boolean | number | string | date | buffer | array | object) - value
  • timeOffset (number) - time offset in minutes (optional)
  • return (string) - string
• Escaper.format(text, values[, timeOffset]) - escapes an array of values or an object of values into a string
  • text (string) - format string
  • values (array | object) - values
  • timeOffset (number) - time offset in minutes (optional)
  • return (string) - string

Escaper types

• null - null
• boolean - boolean literal
• number - numeric literal
• string - string literal (with escaping of "\n", "'", "\\", "\t", "\r", "\0", "\b" and "\x1a")
• date - date and time literal (in the format 'yyyy-mm-dd hh:mm:ss.zzz')
• buffer - hexadecimal literal (in the format x'00')
• array - set literal if is set (in the format 'a,b,c'), two-dimensional list if is two-dimensional (in the format (0, 1, 2), (3, 4, 5), (6, 7, 8)) or list (in the format 0, 1, 2)
• object - object.toSqlString(timeOffset) if toSqlString is not undefined or associative list (in the format `key0` = 'value0', `key1` = 'value1', `key2` = 'value2')
• others - skipped

Format syntax

• ?? - escapes ?
• ? - escapes a value in an array
• ?:property - escapes a value of a property in an object if is not undefined

Escaping and formatting

You can escape and format your query for convenience, ease and safety.

console.log("select * from animals where birth >= " + anita.Escaper.escapeDate(new Date(2009)));
console.log("select * from animals where birth >= " + anita.Escaper.escape(new Date(2009)));
console.log(anita.Escaper.format("insert into ? values (?, ?, ?, ?, ?)", [
	anita.Escaper.escapeRawId("animals"),
	0,
	"Anita",
	true,
	new Date(2009, 0, 22),
	"cat"
]));
console.log(anita.Escaper.format("insert into ?table values (?id, ?name, ?sex, ?birth, ?type)", {
	table: anita.Escaper.escapeRawId("animals"),
	id: 0,
	name: "Anita",
	sex: true,
	birth: new Date(2009, 0, 22),
	type: "cat"
}));

Parser

Parser functions

• Parser.parseRowAsRaw() - parses row packet to an object with buffer and columns properties
  • return (object) - object
• Parser.parseRowAsRawArray() - parses row packet to an array with null, string or buffer
  • return (array) - array
• Parser.parseRowAsRawObject() - parses row packet to an object with null, string or buffer
  • return (object) - object
• Parser.parseRowAsArray() - parses row packet to an array
  • return (array) - array
• Parser.parseRowAsObject() - parses row packet to an object
  • return (object) - object
• Parser.parseRowAsArrayWithBool() - parses row packet to an array where tinyint(1) is treated as a boolean
  • return (array) - array
• Parser.parseRowAsObjectWithBool() - parses row packet to an object where tinyint(1) is treated as a boolean
  • return (object) - object
• Parser.parseRowAsArrayWithSet() - parses row packet to an array where set is treated as an array
  • return (array) - array
• Parser.parseRowAsObjectWithSet() - parses row packet to an object where set is treated as an array
  • return (object) - object
• Parser.parseRowAsArrayWithBoolAndSet() - parses row packet to an array where tinyint(1) is treated as a boolean and set is treated as an array
  • return (array) - array
• Parser.parseRowAsObjectWithBoolAndSet() - parses row packet to an object where tinyint(1) is treated as a boolean and set is treated as an array
  • return (object) - object
• Parser.parseInfo(value) - parses ok info and statistics to an object
  • value (string) - ok info and statistics
  • return (object) - object

Parser types

• null - null
• integer - string if is zerofilled or number
• int - string if is zerofilled or number
• smallint - string if is zerofilled or number
• tinyint - string if is zerofilled, boolean if is parsed and is tinyint(1) or number
• mediumint - string if is zerofilled or number
• bigint - string if is zerofilled or number
• decimal - string if is zerofilled or number
• float - string if is zerofilled or number
• double - string if is zerofilled or number
• bit - buffer
• year - number
• time - date
• date - date
• datetime - date
• timestamp - date
• char - buffer if character set is binary or string
• varchar - buffer if character set is binary or string
• binary - buffer
• varbinary - buffer
• tinytext - buffer if character set is binary or string
• text - buffer if character set is binary or string
• mediumtext - buffer if character set is binary or string
• longtext - buffer if character set is binary or string
• tinyblob - buffer
• blob - buffer
• mediumblob - buffer
• longblob - buffer
• enum - buffer if character set is binary or string
• set - buffer if character set is binary, array if is parsed or string
• json - null, boolean, number, string, array or object
• others - buffer

Row parsing

You can use the built-in parser to get the result rows as an array or an object. If you know the structure of your table the most effective way is parsing it yourself. The context of the parser function is the client.

function parseAnimal() {//id (int), name (varchar(120)), sex (tinyint(1)), birth (datetime(0)), type (varchar(60))
	var s;
	return [
		(s = this.packet.readLengthEncodedString()) === null ? null : +s,
		this.packet.readLengthEncodedString(),
		(s = this.packet.readLengthEncodedString()) === null ? null : s !== "0",
		(s = this.packet.readLengthEncodedString()) === null ? null : new Date(s)
		this.packet.readLengthEncodedString()
	];
}

Info parsing

You can use the built-in parser to get an object from the ok's info property or the statistics.

client.query("insert into animals values (0, 'Anita', true, '2009-01-22', 'cat')", function(error, result) {
	if (error !== null) {
		console.log(error);
		return;
	}
	console.log(anita.Parser.parseInfo(result.info));
});
client.statistics(function(error, result) {
	if (error !== null) {
		console.log(error);
		return;
	}
	console.log(anita.Parser.parseInfo(result));
});

Utility

Utility properties

• Utility.timeOffsetStrings (object) - cached time offset strings

Utility functions

• Utility.emptyFunction() - an empty function
• Utility.bindFunction(context, callee) - binds a function to a context
  • context (object) - context
  • callee (function) - function
• Utility.timeOffsetStringToNumber(value) - convert a time offset from string as Z, +-hh:mm, +-hhmm or +-hh to number in minutes
  • value (string) - time offset as string
  • return (number) - time offset as number
• Utility.timeOffsetNumberToString(value) - convert a time offset from number in minutes to string as Z or +-hh:mm
  • value (string) - time offset as number
  • return (number) - time offset as string
• Utility.convertDateToTimeOffset(value, timeOffset) - convert a date to specific time offset
  • value (object) - date
  • timeOffset (number) - time offset as number