{"id":14563584,"url":"https://github.com/blakeembrey/sql-template-tag","last_synced_at":"2025-05-16T04:00:54.056Z","repository":{"id":44674152,"uuid":"132335766","full_name":"blakeembrey/sql-template-tag","owner":"blakeembrey","description":"ES2015 tagged template string for preparing SQL statements, works with `pg`, `mysql`, `sqlite` and `oracledb`","archived":false,"fork":false,"pushed_at":"2024-04-21T00:21:20.000Z","size":1188,"stargazers_count":371,"open_issues_count":5,"forks_count":20,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-09T10:11:24.932Z","etag":null,"topics":["mysql","oracle-db","pg","postgresql","sql","sql-query","sql-query-builder","sqlite","template-tags"],"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/blakeembrey.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-06T12:21:16.000Z","updated_at":"2025-05-07T09:37:34.000Z","dependencies_parsed_at":"2024-06-18T13:50:07.101Z","dependency_job_id":"88caead4-20c7-4499-acdf-b12a7793e4b5","html_url":"https://github.com/blakeembrey/sql-template-tag","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakeembrey%2Fsql-template-tag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakeembrey%2Fsql-template-tag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakeembrey%2Fsql-template-tag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakeembrey%2Fsql-template-tag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blakeembrey","download_url":"https://codeload.github.com/blakeembrey/sql-template-tag/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253973616,"owners_count":21993132,"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":["mysql","oracle-db","pg","postgresql","sql","sql-query","sql-query-builder","sqlite","template-tags"],"created_at":"2024-09-07T02:03:54.013Z","updated_at":"2025-05-16T04:00:53.969Z","avatar_url":"https://github.com/blakeembrey.png","language":"TypeScript","readme":"# SQL Template Tag\n\n[![NPM version][npm-image]][npm-url]\n[![NPM downloads][downloads-image]][downloads-url]\n[![Build status][build-image]][build-url]\n[![Build coverage][coverage-image]][coverage-url]\n\n\u003e ES2015 tagged template string for preparing SQL statements.\n\n## Installation\n\n```\nnpm install sql-template-tag --save\n```\n\n## Usage\n\n```js\nimport sql, { empty, join, raw } from \"sql-template-tag\";\n\nconst query = sql`SELECT * FROM books WHERE id = ${id}`;\n\nquery.sql; //=\u003e \"SELECT * FROM books WHERE id = ?\"\nquery.text; //=\u003e \"SELECT * FROM books WHERE id = $1\"\nquery.statement; //=\u003e \"SELECT * FROM books WHERE id = :1\"\nquery.values; //=\u003e [id]\n\npg.query(query); // Uses `text` and `values`.\nmysql.query(query); // Uses `sql` and `values`.\noracledb.execute(query); // Uses `statement` and `values`.\n\n// Embed SQL instances inside SQL instances.\nconst nested = sql`SELECT id FROM authors WHERE name = ${\"Blake\"}`;\nconst query = sql`SELECT * FROM books WHERE author_id IN (${nested})`;\n\n// Join and \"empty\" helpers (useful for nested queries).\nsql`SELECT * FROM books ${hasIds ? sql`WHERE ids IN (${join(ids)})` : empty}`;\n```\n\n### Join\n\nAccepts an array of values or SQL, and returns SQL with the values joined together using the separator.\n\n```js\nconst query = join([1, 2, 3]);\n\nquery.sql; //=\u003e \"?,?,?\"\nquery.values; //=\u003e [1, 2, 3]\n```\n\n**Tip:** You can set the second argument to change the join separator, for example:\n\n```js\njoin(\n  [sql`first_name LIKE ${firstName}`, sql`last_name LIKE ${lastName}`],\n  \" AND \",\n); // =\u003e \"first_name LIKE ? AND last_name LIKE ?\"\n```\n\n### Raw\n\nAccepts a string and returns a SQL instance, useful if you want some part of the SQL to be dynamic.\n\n```js\nraw(\"SELECT\"); // == sql`SELECT`\n```\n\n**Do not** accept user input to `raw`, this will create a SQL injection vulnerability.\n\n### Empty\n\nSimple placeholder value for an empty SQL string. Equivalent to `raw(\"\")`.\n\n### Bulk\n\nAccepts an array of arrays, and returns the SQL with the values joined together in a format useful for bulk inserts.\n\n```js\nconst query = sql`INSERT INTO users (name) VALUES ${bulk([\n  [\"Blake\"],\n  [\"Bob\"],\n  [\"Joe\"],\n])}`;\n\nquery.sql; //=\u003e \"INSERT INTO users (name) VALUES (?),(?),(?)\"\nquery.values; //=\u003e [\"Blake\", \"Bob\", \"Joe\"]\n```\n\n## Recipes\n\nThis package \"just works\" with [`pg`](https://www.npmjs.com/package/pg), [`mysql`](https://www.npmjs.com/package/mysql), [`sqlite`](https://www.npmjs.com/package/sqlite) and [`oracledb`](https://www.npmjs.com/package/node-oracledb).\n\n### [MSSQL](https://www.npmjs.com/package/mssql)\n\n```js\nmssql.query(query.strings, ...query.values);\n```\n\n### Stricter TypeScript\n\nThe default value is `unknown` to support [every possible input](https://github.com/blakeembrey/sql-template-tag/pull/26). If you want stricter TypeScript values you can create a new `sql` template tag function.\n\n```ts\nimport { Sql } from \"sql-template-tag\";\n\ntype SupportedValue =\n  | string\n  | number\n  | SupportedValue[]\n  | { [key: string]: SupportedValue };\n\nfunction sql(\n  strings: ReadonlyArray\u003cstring\u003e,\n  ...values: Array\u003cSupportedValue | Sql\u003e\n) {\n  return new Sql(strings, values);\n}\n```\n\n## Related\n\nSome other modules exist that do something similar:\n\n- [`sql-template-strings`](https://github.com/felixfbecker/node-sql-template-strings): promotes mutation via chained methods and lacks nesting SQL statements. The idea to support `sql` and `text` properties for dual `mysql` and `pg` compatibility came from here.\n- [`pg-template-tag`](https://github.com/XeCycle/pg-template-tag): missing TypeScript and MySQL support. This is the API I envisioned before writing this library, and by supporting `pg` only it has the ability to [dedupe `values`](https://github.com/XeCycle/pg-template-tag/issues/5#issuecomment-386875336).\n\n## License\n\nMIT\n\n[npm-image]: https://img.shields.io/npm/v/sql-template-tag\n[npm-url]: https://npmjs.org/package/sql-template-tag\n[downloads-image]: https://img.shields.io/npm/dm/sql-template-tag\n[downloads-url]: https://npmjs.org/package/sql-template-tag\n[build-image]: https://img.shields.io/github/actions/workflow/status/blakeembrey/sql-template-tag/ci.yml?branch=main\n[build-url]: https://github.com/blakeembrey/sql-template-tag/actions/workflows/ci.yml?query=branch%3Amain\n[coverage-image]: https://img.shields.io/codecov/c/gh/blakeembrey/sql-template-tag\n[coverage-url]: https://codecov.io/gh/blakeembrey/sql-template-tag\n","funding_links":[],"categories":["sql"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblakeembrey%2Fsql-template-tag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblakeembrey%2Fsql-template-tag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblakeembrey%2Fsql-template-tag/lists"}