node-query/README.md

79 lines
2.8 KiB
Markdown
Raw Normal View History

2016-02-01 18:55:53 -05:00
# CI-Node-query
2016-01-12 15:46:37 -05:00
2016-01-26 20:23:52 -05:00
A node query builder for various SQL databases, based on [CodeIgniter](http://www.codeigniter.com/user_guide/database/query_builder.html)'s query builder.
2016-01-12 15:46:37 -05:00
[![Build Status](https://jenkins.timshomepage.net/buildStatus/icon?job=node-query)](https://jenkins.timshomepage.net/job/node-query/)
[![Build Status](https://travis-ci.org/timw4mail/node-query.svg?branch=master)](https://travis-ci.org/timw4mail/node-query)
[![Code Climate](https://codeclimate.com/github/timw4mail/node-query/badges/gpa.svg)](https://codeclimate.com/github/timw4mail/node-query)
[![Test Coverage](https://codeclimate.com/github/timw4mail/node-query/badges/coverage.svg)](https://codeclimate.com/github/timw4mail/node-query/coverage)
### Supported adapters
* mysql
* mysql2
* pg
* dblite
2016-01-26 20:23:52 -05:00
* node-firebird (Not supported as of version 3.1.0, as the adapter is very difficult to test)
2016-01-12 15:46:37 -05:00
### Installation
npm install ci-node-query
2016-01-26 20:23:52 -05:00
[![NPM](https://nodei.co/npm/ci-node-query.png?downloads=true&downloadRank=true)](https://nodei.co/npm/ci-node-query/)
2016-01-12 15:46:37 -05:00
### Basic use
2016-02-01 18:55:53 -05:00
```javascript
var nodeQuery = require('ci-node-query');
var connection = ... // Database module connection
// Three arguments: database type, database connection, database connection library
var query = nodeQuery.init('mysql', connection, 'mysql2');
// The third argument is optional if the database connection library has the same name as the adapter, eg..
nodeQuery.init('mysql', connection, 'mysql');
// Can be instead
nodeQuery.init('mysql', connection);
// You can also retrieve the instance later
query = nodeQuery.getQuery();
query.select('foo')
.from('bar')
.where('x', 3)
.orWhere({y: 2})
.join('baz', 'baz.boo = bar.foo', 'left')
.orderBy('x', 'DESC')
.limit(2, 3)
.get(function(/* Adapter dependent arguments */) {
// Database module result handling
2016-01-26 20:23:52 -05:00
});
2016-02-01 18:55:53 -05:00
// As of version 3.1.0, you can also get promises
var queryPromise = query.select('foo')
.from('bar')
.where('x', 3)
.orWhere({y: 2})
.join('baz', 'baz.boo = bar.foo', 'left')
.orderBy('x', 'DESC')
.limit(2, 3)
.get();
queryPromise.then(function(res) {
// Handle query results
});
```
2016-01-12 15:46:37 -05:00
### Security notes
As of version 2, `where` and `having` type methods parse the values passed to look for function calls. While values passed are still passed as query parameters, take care to avoid passing these kinds of methods unfiltered input. SQL function arguments are not currently parsed, so they need to be properly escaped for the current database.
### Additional help
* Generated documentation is in the docs/ folder
2016-01-26 20:23:52 -05:00
* The API is documented in [API.md](./API.md)
2016-01-12 15:46:37 -05:00
* `tests/query-builder-base.js` contains a lot of usage examples
* The `tests/adapters` folder contains examples of how to set up a connection for the appropriate database library
* The documentation generated for the latest dev build is also [Available](https://github.timshomepage.net/node-query/docs/)