{"id":24639453,"url":"https://github.com/sharaal/sql-pg","last_synced_at":"2025-05-09T03:27:46.472Z","repository":{"id":57368244,"uuid":"171460434","full_name":"Sharaal/sql-pg","owner":"Sharaal","description":"Complex queries can be written with normal SQL, including the values needs to be bound and prefixed with the sql tag.","archived":false,"fork":false,"pushed_at":"2021-09-15T20:13:03.000Z","size":338,"stargazers_count":9,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-19T08:37:32.059Z","etag":null,"topics":["node-postgres","nodejs","postgresql","query-builder","sql","tagged-template-literals"],"latest_commit_sha":null,"homepage":"","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/Sharaal.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":"SECURITY.md","support":null}},"created_at":"2019-02-19T11:18:05.000Z","updated_at":"2024-02-02T01:48:37.000Z","dependencies_parsed_at":"2022-09-05T20:50:58.814Z","dependency_job_id":null,"html_url":"https://github.com/Sharaal/sql-pg","commit_stats":null,"previous_names":[],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sharaal%2Fsql-pg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sharaal%2Fsql-pg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sharaal%2Fsql-pg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sharaal%2Fsql-pg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sharaal","download_url":"https://codeload.github.com/Sharaal/sql-pg/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235569460,"owners_count":19011187,"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":["node-postgres","nodejs","postgresql","query-builder","sql","tagged-template-literals"],"created_at":"2025-01-25T11:11:36.894Z","updated_at":"2025-01-25T11:11:37.402Z","avatar_url":"https://github.com/Sharaal.png","language":"JavaScript","readme":"[![Build Status](https://app.travis-ci.com/Sharaal/sql-pg.svg?branch=main)](https://app.travis-ci.com/Sharaal/sql-pg)\r\n[![Coverage Status](https://coveralls.io/repos/github/Sharaal/sql-pg/badge.svg?branch=main)](https://coveralls.io/github/Sharaal/sql-pg?branch=main)\r\n\r\nLatest Release: [v10.4.1](https://github.com/Sharaal/sql-pg/releases/tag/v10.4.1), Latest Major Release: [v10.0.0](https://github.com/Sharaal/sql-pg/releases/tag/v10.0.0), [All Releases](https://github.com/Sharaal/sql-pg/releases)\r\n\r\n# SQL-PG\r\n\r\nComplex queries can be written with normal SQL, including the values needs to be bound and prefixed with the sql tag.\r\n\r\n\u003ctable\u003e\r\n  \u003ctr\u003e\r\n    \u003ctd\u003e\u003cimg alt=\"SQL\" src=\"https://github.com/sharaal/sql-pg/raw/main/docs/sql.png\"\u003e\u003c/td\u003e\r\n    \u003ctd\u003eMake the id variable?\u003c/td\u003e\r\n    \u003ctd\u003e\u003cimg alt=\"SQL\" src=\"https://github.com/sharaal/sql-pg/raw/main/docs/sql-pg.png\"\u003e\u003c/td\u003e\r\n  \u003c/tr\u003e\r\n  \u003ctr\u003e\r\n    \u003ctd\u003e\u003c/td\u003e\r\n    \u003ctd\u003eOr even more simple?\u003c/td\u003e\r\n    \u003ctd\u003e\u003cimg alt=\"SQL\" src=\"https://github.com/sharaal/sql-pg/raw/main/docs/selection-method.png\"\u003e\u003c/td\u003e\r\n  \u003c/tr\u003e\r\n\u003c/table\u003e\r\n\r\n## Features\r\n\r\n* Built on top of `pg` as database driver\r\n* Simple data manipulation and selection methods without the need to write SQL\r\n* SQL Tag and Tag Helpers to write queries looks like native SQL and be secure by design\r\n* Write easy unit testable queries\r\n* Possibility to add own Tag Helpers to extend the functionality\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install --save pg sql-pg\r\n```\r\n\r\n## Initialisation\r\n\r\nUse it in your project:\r\n\r\n```javascript\r\nconst sql = require('sql-pg')()\r\n```\r\n\r\nThe connection use per default the env var `DATABASE_URL`. It will only establish a database connection if manipulation/selection methods are used. Alternatively it's possible to provide a `sql.js` to customize the database connecting and `sql` object initializing.\r\n\r\n## Usage\r\n\r\n### Manipulation Methods\r\n\r\nSimple data manipulation can be done without writing any SQL Statements.\r\n\r\nE.g. some user data manipulation:\r\n\r\n```javascript\r\nconst id = await sql.insert(\r\n  'users',\r\n  { name: 'Sharaal', email: 'sql-pg@sharaal.de', passwordhash: '...' }\r\n)\r\n\r\nawait sql.update('users', { validated: 1 }, { id })\r\n\r\nawait sql.delete('users', { id })\r\n```\r\n\r\nMore complex data manipulation can be done with the SQL Tag.\r\n\r\n### Selection Methods\r\n\r\nOften needed convenient methods to check and extract query results are available with the Selection Methods.\r\n\r\nE.g. select all not validated users:\r\n\r\n```javascript\r\nconst users = await sql.any('users', ['name', 'email'], { validated: 0 })\r\n```\r\n\r\nAlso the Selection Methods supports SQL Tag as parameter for more complex selections. Because they are highly inspired by `pg-promise`, there are the Selection Methods `any`/`manyOrNone`, `many`, `oneOrNone` and `one` available.\r\n\r\n### SQL Tag and Tag Helpers\r\n\r\nIf it becomes more complex the SQL Tag and Tag Helpers are the way to go.\r\n\r\nThey are as near as possible to native SQL queries to be readable and easy to write. All variables can be directly used and will be exchanged via placeholders and given to the database separately as values. For non native values like lists, for table/column names and conditions there are Tag Helpers.\r\n\r\nE.g. list of not activated users filtered by name:\r\n\r\n```javascript\r\nconst name = 'raa'\r\n\r\nconst users = await sql.any(\r\n  sql`\r\n    SELECT \"name\", \"email\" FROM \"users\"\r\n      WHERE\r\n        \"validated\" = 0\r\n        AND\r\n        \"name\" LIKE ${`%${name}%`}\r\n  `\r\n)\r\n```\r\n\r\nThere are a lot more Tag Helpers available like `.identifier`, `.table`, `.column(s)`, `.value(s)`, `.valuesList`, `.assignments`, `.conditions`, `.limit`, `.offset`, `.pagination`, `.if`, `.jsonColumnObject` and `.jsonColumnText`.\r\n\r\n## More\r\n\r\nAlternative initialization, available Tag Helpers, Nested Queries, Transaction, Writing Tag Helpers, Migrations, Syntax Highlighting in Atom... All additional documentation can be found in the [Wiki](https://github.com/Sharaal/sql-pg/wiki).\r\n\r\n## Contact\r\n\r\nFound a bug or missing a feature? -\u003e Create a new [Issue](https://github.com/Sharaal/sql-pg/issues)\r\n\r\nFound a security issue? -\u003e Look at the [Security Policy](https://github.com/Sharaal/sql-pg/security/policy)\r\n\r\nHaving questions, want to give feedback or talk to me? -\u003e E-Mail me sql-pg@sharaal.de\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsharaal%2Fsql-pg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsharaal%2Fsql-pg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsharaal%2Fsql-pg/lists"}