{"id":20557053,"url":"https://github.com/vitaminjs/query-builder","last_synced_at":"2026-02-27T11:15:49.722Z","repository":{"id":57393035,"uuid":"63987297","full_name":"vitaminjs/query-builder","owner":"vitaminjs","description":"A query builder for SQL databases","archived":false,"fork":false,"pushed_at":"2020-05-01T06:46:26.000Z","size":488,"stargazers_count":7,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-28T02:24:11.162Z","etag":null,"topics":["mssql","mysql","postgresql","query-builder","sql","sqlite"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vitaminjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-07-22T22:31:17.000Z","updated_at":"2021-06-14T17:27:23.000Z","dependencies_parsed_at":"2022-09-15T02:10:48.758Z","dependency_job_id":null,"html_url":"https://github.com/vitaminjs/query-builder","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitaminjs%2Fquery-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitaminjs%2Fquery-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitaminjs%2Fquery-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitaminjs%2Fquery-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vitaminjs","download_url":"https://codeload.github.com/vitaminjs/query-builder/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248774988,"owners_count":21159534,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mssql","mysql","postgresql","query-builder","sql","sqlite"],"created_at":"2024-11-16T03:34:27.689Z","updated_at":"2026-02-27T11:15:44.702Z","avatar_url":"https://github.com/vitaminjs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/vitaminjs/query-builder.svg?branch=master)](https://travis-ci.org/vitaminjs/query-builder)\r\n\r\nA fluent SQL query builder for Node.js\r\nIt provides support for:\r\n- **PostgreSQL** (v9.5+)\r\n- **SQLite** (v3.15.0+)\r\n- **MySQL** (v5.7+)\r\n- **MSSQL** (2012+)\r\n\r\n## Installing\r\n\r\n```bash\r\n$ npm install --save vitamin-query\r\n```\r\n\r\n## Getting started\r\n\r\n`vitamin-query` is composed of a set of useful expressions and helpers to build SQL queries easily\r\n\r\n### building queries\r\n\r\n```js\r\n// import the query builder\r\nimport qb from 'vitamin-query'\r\n\r\n// Select query\r\nlet query = qb('employees').select('count(*)').where('salary between ? and (?1 * 2)', 1500).toQuery('pg')\r\nassert.equal(query.sql, 'select count(*) from employees where salary between $1 and ($2 * 2)')\r\nassert.deepEqual(query.params, [ 1500, 1500 ])\r\n\r\n// Compound query\r\nlet query = qb('t').where('a is null').union(qb('t').where('b is null')).toQuery('pg')\r\nassert.equal(query.sql, 'select * from t where a is null union select * from t where b is null')\r\n\r\n// Insert query\r\nlet fred = { name: \"Fred\", score: 30 }\r\nlet query = qb('players').insert(fred).returning('*').toQuery('mssql')\r\nassert.equal(query.sql, 'insert into players (name, score) output inserted.* values (?, ?)')\r\nassert.deepEqual(query.params, [ 'Fred', 30 ])\r\n\r\n// Update query\r\nlet query = qb('books').update({ status: 'archived' }).where('publish_date \u003c= ?', 2000).toQuery('mysql')\r\nassert.equal(query.sql, 'update books set status = ? where publish_date \u003c= ?')\r\nassert.deepEqual(query.params, [ 'archived', 2000 ])\r\n\r\n// Delete query\r\nlet query = qb('accounts').delete().where({ activated: false, deleted: true }).toQuery('sqlite')\r\nassert.equal(query.sql, 'delete from accounts where activated = ? and deleted = ?')\r\nassert.deepEqual(query.params, [ false, true ])\r\n```\r\n\r\n### Custom compiler\r\n\r\nIf you may use a custom query compiler instead of the built-in ones, you can pass its instance to `toQuery()`\r\n\r\n```js\r\n// in path/to/maria-compiler.js\r\nimport MysqlCompiler from 'vitamin-query/compiler/mysql'\r\n\r\nclass MariaCompiler extends MysqlCompiler { ... }\r\n\r\n// later, you can use its instance with any query instance\r\nimport qb from 'vitamin-query'\r\n\r\nlet query = qb().select().from('foo').toQuery(new MariaCompiler({ /* options */ }))\r\n```\r\n\r\n## API\r\n\r\nFor examples of usage, please refer to the tests\r\n\r\n### Expression helpers\r\n\r\nThese Helpers are functions that return Expression instances:\r\n\r\n- **alias**(expr, name: string; ...columns: string[]): IAlias\r\n- **table**(value: string | IExpression): ITable\r\n- **func**(name: string, ...args): IFunction\r\n- **raw**(expr: string, ...args): ILiteral\r\n- **values**(...data: any[][]): IValues\r\n- **id**(name: string): IIdentifier\r\n- **esc**(value: string): ILiteral\r\n- **val**(value): ILiteral\r\n- **desc**(expr): IOrder\r\n- **asc**(expr): IOrder\r\n\r\n### Function helpers\r\n\r\nHelpers to emulate the SQL built-in functions\r\n\r\n- **substr | substring**(expr, start: number, length?: number): IFunction\r\n- **replace**(expr, pattern, replacement): IFunction\r\n- **strpos | position**(str, substr): IFunction\r\n- **repeat**(expr, count: number): IFunction\r\n- **right**(expr, length: number): IFunction\r\n- **left**(expr, length: number): IFunction\r\n- **round**(expr, n: number): IFunction\r\n- **space**(length: number): IFunction\r\n- **upper | ucase**(expr): IFunction\r\n- **lower | lcase**(expr): IFunction\r\n- **len | length**(expr): IFunction\r\n- **today | curdate**(): IFunction\r\n- **clock | curtime**(): IFunction\r\n- **concat**(...parts): IFunction\r\n- **now | datetime**(): IFunction\r\n- **rand | random**(): IFunction\r\n- **minute**(expr): IFunction\r\n- **second**(expr): IFunction\r\n- **ltrim**(expr): IFunction\r\n- **rtrim**(expr): IFunction\r\n- **month**(expr): IFunction\r\n- **date**(expr): IFunction\r\n- **time**(expr): IFunction\r\n- **trim**(expr): IFunction\r\n- **year**(expr): IFunction\r\n- **hour**(expr): IFunction\r\n- **abs**(expr): IFunction\r\n- **day**(expr): IFunction\r\n- **utc**(): IFunction\r\n\r\n## Testing\r\n\r\n```bash\r\n$ npm test\r\n```\r\n\r\n## Change log\r\n\r\n- **v1.0.0-alpha** - _TypeScript version of the library_\r\n  - Breaking changes and many API are unsupported\r\n  - Supports\r\n    - sql functions\r\n    - Clonable expressions\r\n    - Join precedences (#21)\r\n    - common table expressions\r\n    - order by nulls first or last\r\n    - compound queries using unions\r\n  - drop support for multiple tables in select queries\r\n\r\n- **v0.2.1** - _Add support for common table expressions_\r\n  - Deprecate `Query::toSQL()` and add `Query::build()` instead\r\n  - Add Support for named parameters within `raw` helper (issue #6)\r\n  - Add Support for common table expressions using `Query::with()`\r\n  - Minor fixes\r\n\r\n- **v0.2.0** - _API breaking changes_\r\n  - Remove the operator argument from `Criteria.where()` (issue #4)\r\n  - Lowcase all the helper functions\r\n  - Use class mixin to keep the code DRY\r\n  - Fix minor bugs and typos\r\n\r\n- **v0.1.2** - _Add new datetime helpers_\r\n\r\n- **v0.1.1** - _Add helpers for SQL functions_\r\n  - Configure Travis CI\r\n  - Update README.md\r\n  - Add helpers for SQL functions\r\n  - Fix minor bugs\r\n  \r\n- **v0.1.0** - _Intial release_\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvitaminjs%2Fquery-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvitaminjs%2Fquery-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvitaminjs%2Fquery-builder/lists"}