database-js

Common database interface for JavaScript


Keywords
database-js, database-js-mysql, database-js-postgres, database-js-sqlite, database-js-adodb, database-js-firebase, database-js-ini, database-js-xlsx, database-js-csv, database-js-json, javascript, database, db, sql, query, driver, mysql, postgre, postgres, postgresql, sqlite, ado, adodb, firebase, ini, xls, xlsx, csv, json, wrapper, node, excel, javascript-library, node-module, msaccess
License
MIT
Install
npm install database-js@3.0.11

Documentation

database-js

Build Status npm version Mentioned in Awesome Node.js downloads

Wrapper for multiple databases with a JDBC-like connection

Database-js implements a common, promise-based interface for SQL database access. Inspired by Java, it uses connection strings to identify the database driver. Wrappers around native database drivers provide a unified interface to handle databases. Thus, you don't need to modify your code (except the connection string) to change your database! 😉

Database-js has built-in prepared statements, even if the underlying driver does not support them. It is built on Promises, so it works well with ES7 async code.

Contents

Install

npm install database-js

Drivers

Driver (wrapper) Note Installation
ActiveX Data Objects Windows only npm i database-js-adodb
CSV files npm i database-js-csv
Excel files npm i database-js-xlsx
Firebase npm i database-js-firebase
INI files npm i database-js-ini
JSON files npm i database-js-json
MySQL npm i database-js-mysql
MS SQL Server npm i database-js-mssql
PostgreSQL npm i database-js-postgres
SQLite npm i database-js-sqlite

See here how to add a new driver.

Usage

var Connection = require('database-js').Connection;

// CONNECTION
var conn =
	new Connection("sqlite:///path/to/test.sqlite");               // SQLite
	// new Connection("mysql://user:password@localhost/test");     // MySQL
	// new Connection("postgres://user:password@localhost/test");  // PostgreSQL
	// 👉 Change the connection string according to the database driver

// QUERY
var stmt1 = conn.prepareStatement("SELECT * FROM city WHERE name = ?");
stmt1.query("New York")
	.then( function (results) {
		console.log(results); // Display the results
	} ).catch( function (reason) {
		console.log(reason); // Some problem while performing the query
	} );

// COMMAND
var stmt2 = conn.prepareStatement("INSERT INTO city (name, population) VALUES (?, ?)");
stmt2.execute("Rio de Janeiro", 6747815)
	.then( function() { console.log( 'Inserted.' ); } )
	.catch( function(reason) { console.log('Error: ' + reason); } );

// ANOTHER COMMAND
var stmt3 = conn.prepareStatement("UPDATE city SET population = population + ? WHERE name = ?");
stmt3.execute(1, "Rio de Janeiro")
	.then( function() { console.log( 'Updated.' ); } )
	.catch( function(reason) { console.log('Error: ' + reason); } );

// CLOSING THE CONNECTION
conn.close()
	.then( function() { console.log('Closed.'); } )
	.catch( function(reason) { console.log('Error: ' + reason); } );

Async / await

Because database-js is built on Promises, it works very well with async/await. Compare the following code to the code from above. They accomplish the same thing.

const Connection = require('database-js').Connection;

(async () => {
	let conn;
	try {
		// CONNECTION
		conn = new Connection('mysql://user:password@localhost/test');

		// QUERY
		const stmt1 = conn.prepareStatement('SELECT * FROM city WHERE name = ?');
		const results = await stmt1.query('New York');
		console.log(results);

		// COMMAND 1
		const stmt2 = conn.prepareStatement('INSERT INTO city (name, population) VALUES (?,?)');
		await stmt1.execute('Rio de Janeiro', 6747815);

		// COMMAND 2
		const stmt2 = conn.prepareStatement('UPDATE city SET population = population + ? WHERE name = ?');
		await stmt1.execute(1, 'Rio de Janeiro');
	} catch (reason) {
		console.log(reason);
	} finally {
		try {
			await conn.close();
		} catch (err) {
			console.log(err);
		}
	}
})();

Basic API

See the source code for the full API.

class Connection {

	/** Creates and prepares a statement with the given SQL. */
	prepareStatement(sql: string): PreparedStatement;

	/** Closes the underlying connection. */
	close(): Promise<void>;

	/** Indicates whether the underlying driver support transactions. */
	isTransactionSupported(): boolean;

	/** Returns true if the underlying driver is in a transaction, false otherwise. */
	inTransaction(): boolean;

	/**
	 * Starts a transaction (if supported).
	 *
	 * Transactions can fail to start if another transaction is already running or
	 * if the driver does not support transactions.
	 */
	beginTransaction(): Promise<boolean>;

	/**
	 * Commits a transaction (if supported).
	 *
	 * Transactions can fail to commit if no transaction was started, or if the driver
	 * does not support transactions.
	 */
	commit(): Promise<boolean>;

	/**
	 * Cancels a transaction (if supported).
	 *
	 * Transaction can fail to be rolled back no transaction was started, or if the driver
	 * does not support transactions.
	 */
	rollback(): Promise<boolean>;
}
class PreparedStatement {
	/**
	 * Performs the prepared SQL query with the given arguments.
	 * Returns a Promise with an array of rows.
	 */
	query(...args: any): Promise<Array<any>>;

	/** Executes the prepared SQL statement with the given arguments. */
	execute(... args): Promise<any>;
}

See also

License

MIT