{"id":28164045,"url":"https://github.com/patrickpissurno/sqlutils","last_synced_at":"2025-08-20T10:08:10.704Z","repository":{"id":34923000,"uuid":"190630796","full_name":"patrickpissurno/sqlutils","owner":"patrickpissurno","description":"Lightweight SQL helper methods that simplify stuff (MySQL and PostgreSQL)","archived":false,"fork":false,"pushed_at":"2025-01-26T01:31:45.000Z","size":528,"stargazers_count":14,"open_issues_count":10,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-04-29T23:35:48.577Z","etag":null,"topics":["easy","helper","lightweight","mysql","nodejs","orm","postgresql","sql","utils"],"latest_commit_sha":null,"homepage":"https://npm.im/sqlutils","language":"JavaScript","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/patrickpissurno.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-06T18:31:26.000Z","updated_at":"2025-01-26T01:31:48.000Z","dependencies_parsed_at":"2024-06-18T23:40:09.652Z","dependency_job_id":null,"html_url":"https://github.com/patrickpissurno/sqlutils","commit_stats":{"total_commits":51,"total_committers":3,"mean_commits":17.0,"dds":"0.13725490196078427","last_synced_commit":"445bf0e2350ee582ceb3256169497f608134debc"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickpissurno%2Fsqlutils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickpissurno%2Fsqlutils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickpissurno%2Fsqlutils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickpissurno%2Fsqlutils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patrickpissurno","download_url":"https://codeload.github.com/patrickpissurno/sqlutils/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254328388,"owners_count":22052634,"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":["easy","helper","lightweight","mysql","nodejs","orm","postgresql","sql","utils"],"created_at":"2025-05-15T11:15:02.002Z","updated_at":"2025-05-15T11:15:28.371Z","avatar_url":"https://github.com/patrickpissurno.png","language":"JavaScript","readme":"# sqlutils\n[![npm-version](https://img.shields.io/npm/v/sqlutils.svg)](https://www.npmjs.com/package/sqlutils)\n[![coverage status](https://coveralls.io/repos/github/patrickpissurno/sqlutils/badge.svg?branch=master)](https://coveralls.io/github/patrickpissurno/sqlutils?branch=master)\n[![known vulnerabilities](https://snyk.io/test/github/patrickpissurno/sqlutils/badge.svg)](https://snyk.io/test/github/patrickpissurno/sqlutils)\n[![downloads](https://img.shields.io/npm/dt/sqlutils.svg)](https://www.npmjs.com/package/sqlutils)\n[![license](https://img.shields.io/github/license/patrickpissurno/sqlutils.svg?maxAge=1800)](https://github.com/patrickpissurno/sqlutils/blob/master/LICENSE)\n\nLightweight SQL helper methods that simplify stuff (MySQL and PostgreSQL)\n\n`sqlutils` (for MySQL) is powered by [sqlstring](https://github.com/mysqljs/sqlstring), the same library that powers [mysql2](https://www.npmjs.com/package/mysql2).\n\n`sqlutils` (for PostgreSQL) is powered by [pg-promise](https://github.com/vitaly-t/pg-promise), one of the most popular PostgreSQL libraries for Node, with more than 3.1k stars and in active development.\n\nThe aim of this library is to offer standard helper methods that behave in similar ways for PostgreSQL and MySQL. \n\n## Install\n\n```\nnpm i sqlutils\n```\n\n## How to import helpers\n\nPostgreSQL\n```js\nconst escape = require('sqlutils/pg/escape');\n// or\nconst { escape } = require('sqlutils/pg');\n// or\nconst escape = require('sqlutils/pg').escape;\n```\n\nMySQL\n```js\nconst escape = require('sqlutils/mysql/escape');\n// or\nconst { escape } = require('sqlutils/mysql');\n// or\nconst escape = require('sqlutils/mysql').escape;\n```\n\n## escape(val)\n\nPostgreSQL\n```js\nconst escape = require('sqlutils/pg/escape');\nconsole.log(escape(\"let's do it\")); //returns: 'let''s do it'\n```\n\nMySQL\n```js\nconst escape = require('sqlutils/mysql/escape');\nconsole.log(escape(\"let's do it\")); //returns: 'let\\'s do it'\n```\n\n## format(statement, obj)\n\nPostgreSQL\n```js\nconst format = require('sqlutils/pg/format');\nconsole.log(format('INSERT INTO customers ?', { name: 'John Doe', balance: 0 })); //returns: INSERT INTO customers (name, balance) VALUES ('John Doe', 0)\nconsole.log(format('UPDATE customers SET ? WHERE id = 1', { nick: 'Max', name: 'Maximus' })); //returns: UPDATE customers SET nick='Max', name='Maximus' WHERE id = 1\nconsole.log(format('UPDATE customers SET ? WHERE id = 1', { '!visits': '(SELECT COUNT(*) FROM customer_visits WHERE customer_id = 1)' })); //returns: UPDATE customers SET visits=(SELECT COUNT(*) FROM customer_visits WHERE customer_id = 1) WHERE id = 1\nconsole.log(format('INSERT INTO customers ?', [ { name: 'John Doe', balance: 0 }, { name: 'Joe', balance: 1 } ])); //returns: INSERT INTO customers (name, balance) VALUES ('John Doe', 0), ('Joe', 1)\n```\n\nMySQL\n```js\nconst format = require('sqlutils/mysql/format');\nconsole.log(format('INSERT INTO customers ?', { name: 'John Doe', balance: 0 })); //returns: INSERT INTO customers (name, balance) VALUES ('John Doe', 0)\nconsole.log(format('UPDATE customers SET ? WHERE id = 1', { nick: 'Max', name: 'Maximus' })); //returns: UPDATE customers SET nick='Max', name='Maximus' WHERE id = 1\nconsole.log(format('UPDATE customers SET ? WHERE id = 1', { '!visits': '(SELECT COUNT(*) FROM customer_visits WHERE customer_id = 1)' })); //returns: UPDATE customers SET visits=(SELECT COUNT(*) FROM customer_visits WHERE customer_id = 1) WHERE id = 1\nconsole.log(format('INSERT INTO customers ?', [ { name: 'John Doe', balance: 0 }, { name: 'Joe', balance: 1 } ])); //returns: INSERT INTO customers (name, balance) VALUES ('John Doe', 0), ('Joe', 1)\n```\n\nSome explanation about the third example: by using ```!visits``` instead of ```visits``` as the key, you tell the formatter not to escape the string value (raw mode). This way you can combine powerful SQL subqueries with the simplicity of sqlutils. I recommend reading that example carefully.\n\n## buildWhereFromQuery(queryObject)\n\nPostgreSQL\n```js\nconst buildWhereFromQuery = require('sqlutils/pg/buildWhereFromQuery');\nconsole.log('SELECT * FROM customers' + buildWhereFromQuery({ id: 1 })); //returns: SELECT * FROM customers WHERE id=1\nconsole.log('SELECT * FROM customers' + buildWhereFromQuery({ name: ['Maximus', 'John Doe'], balance: 0 })); //returns: SELECT * FROM customers WHERE (name='Maximus' OR name='John Doe') AND balance=0\nconsole.log('SELECT * FROM customers' + buildWhereFromQuery([{ name: 'John Doe' }, { age: 41 }])); //returns: SELECT * FROM customers WHERE (name='John Doe') OR (age=41)\n```\n\nMySQL\n```js\nconst buildWhereFromQuery = require('sqlutils/mysql/buildWhereFromQuery');\nconsole.log('SELECT * FROM customers' + buildWhereFromQuery({ id: 1 })); //returns: SELECT * FROM customers WHERE id=1\nconsole.log('SELECT * FROM customers' + buildWhereFromQuery({ name: ['Maximus', 'John Doe'], balance: 0 })); //returns: SELECT * FROM customers WHERE (name='Maximus' OR name='John Doe') AND balance=0\nconsole.log('SELECT * FROM customers' + buildWhereFromQuery([{ name: 'John Doe' }, { age: 41 }])); //returns: SELECT * FROM customers WHERE (name='John Doe') OR (age=41)\n```\n\n## transformer(rows, transformation)\n\n~~Do you like transformers? Then look no further.~~\n\nThis is the new Transformer\u0026trade; API. What does it do?\nIt offers a declarative way to express how your query results\nshould look like, then it does the magic for you. Sounds simple, right?\n\nYou can check out the [full documentation here](./docs/transformer.md). It will get you up and running quickly.\n\nLet's have a look:\n\nPostgreSQL and MySQL\n```js\nconst transformer = require('sqlutils/pg/transformer'); //or require('sqlutils/mysql/transformer');\n\nconst rows = [ //in real-world applications this would be the result of a database query\n    { ssn: 'abcd', name: 'John Doe', email: 'john@example.com' },\n    { ssn: 'abcd', name: 'John Doe', email: 'john@acme.com' },\n    { ssn: 'defg', name: 'Jimmy', email: 'jimmy@example.com' },\n];\n\nconst employees = transformer(rows, {\n    key: 'ssn',\n    columns: ['name'],\n    children: [{\n        key: ['email'],\n        rename: 'emails',\n        flat: true\n    }]\n});\n\nconsole.log(employees);\n/*\n[\n    { ssn: 'abcd', name: 'John Doe', emails: ['john@example.com', 'john@acme.com' ] },\n    { ssn: 'defg', name: 'Jimmy', emails: ['jimmy@example.com'] }\n]\n*/\n```\n\nEasy! Now let's see something a bit more complex:\n\nPostgreSQL and MySQL\n```js\nconst transformer = require('sqlutils/pg/transformer'); //or require('sqlutils/mysql/transformer');\n\nconst rows = [ //in real-world applications this would be the result of a database query\n    { id: 1, name: 'Alice', sale_id: 1, sale_price_paid: 10.5, sale_item_code: 1, sale_item_name: 'A' },\n    { id: 1, name: 'Alice', sale_id: 1, sale_price_paid: 10.5, sale_item_code: 2, sale_item_name: 'B' },\n    { id: 1, name: 'Alice', sale_id: 2, sale_price_paid: 5.5, sale_item_code: 3, sale_item_name: 'C' },\n    { id: 1, name: 'Alice', sale_id: 2, sale_price_paid: 5.5, sale_item_code: 4, sale_item_name: 'D' },\n    { id: 2, name: 'Bob', sale_id: 3, sale_price_paid: 7.5, sale_item_code: 5, sale_item_name: 'E' },\n    { id: 2, name: 'Bob', sale_id: 4, sale_price_paid: 15.5, sale_item_code: 6, sale_item_name: 'F' },\n];\n\nconst customers = transformer(rows, {\n    key: 'id',\n    columns: ['name'],\n    children: [{\n        key: ['sale_id', 'id'],\n        columns: [\n            ['sale_price_paid', 'price_paid'],\n        ],\n        rename: 'sales',\n        children: [{\n            key: ['sale_item_code', 'code'],\n            columns: [ ['sale_item_name', 'name'] ],\n            rename: 'items',\n        }]\n    }]\n});\n\nconsole.log(customers);\n/*\n[\n    {\n        id: 1,\n        name: 'Alice',\n        sales: [\n            { id: 1, price_paid: 10.5, items: [ { code: 1, name: 'A' }, { code: 2, name: 'B' } ] },\n            { id: 2, price_paid: 5.5, items: [ { code: 3, name: 'C' }, { code: 4, name: 'D' } ] },\n        ]\n    },\n    {\n        id: 2,\n        name: 'Bob',\n        sales: [\n            { id: 3, price_paid: 7.5, items: [ { code: 5, name: 'E' } ] },\n            { id: 4, price_paid: 15.5, items: [ { code: 6, name: 'F' } ] },\n        ]\n    }\n]\n*/\n```\n\nSee? Quite easy, right? And that's still just the tip of the iceberg.\nThis little monster can tackle a whole lot of tasks, while still being\nsimple and declarative (maybe even intuitive when you get the hang of it).\n\nI really advise you [check out the docs](./docs/transformer.md). There you'll find everything you need\nnot only to get up and running quickly, but also a complete description of\nevery feature it provides.\n\nBy the way: imagine you could even get autocomplete for your query results when using\nthis marvelous API? Sounds like magic? It sure is. But it's also true and possible,\nand I'm writing my thesis on it. Hang tight, a tool for it will be available later this year.\nSame API: just plug and play.\n\n## groupColumnsToObjects\n\n[Take a look here](./docs/groupColumnsToObjects.md).\n\n## Production-ready?\nYes. This library has a strict 100% coverage policy. Travis-CI runs for every commit, which guarantees safety. It's been in production for more than four years.\n\n## License\n\nMIT License\n\nCopyright (c) 2019-2025 Patrick Pissurno\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrickpissurno%2Fsqlutils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatrickpissurno%2Fsqlutils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrickpissurno%2Fsqlutils/lists"}