node-query/README.md

98 lines
2.7 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/)
### Features
* Callback and Promise API for making database calls.
2016-03-11 16:32:38 -05:00
### Supported databases
2016-01-12 15:46:37 -05:00
2016-03-11 16:32:38 -05:00
* Mysql (via `mysql2`)
* PostgreSQL (via `pg`)
* Sqlite (via `dblite`)
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
(Versions 3.x and below work differently. Their documentation is [here](https://git.timshomepage.net/timw4mail/node-query/tree/v3#README))
2016-01-12 15:46:37 -05:00
### Basic use
2016-02-01 18:55:53 -05:00
```javascript
2016-03-11 16:32:38 -05:00
// Set the database connection details
const nodeQuery = require('ci-node-query')({
"driver": "mysql",
"connection": {
"host": "localhost",
"user": "test",
"password": "",
"database": "test"
}
});
// Get the query builder
const query = nodeQuery.getQuery();
2016-02-01 18:55:53 -05:00
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(err, result) {
// Handle Results Here
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
});
```
### Result object
As of version 4, all adapters return a standard result object, which looks similar to this:
```javascript
// Result object
{
rows: [{
columnName1: value1,
columnName2: value2,
}],
columns: ['column1', 'column2'],
}
```
In addition to the rows, and columns properties,
the result object has two methods, `rowCount` and `columnCount`.
These methods return the number of rows and columns columns in the current result.
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
* 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/)