{"id":21298014,"url":"https://github.com/orangemug/sql-stamp","last_synced_at":"2025-07-11T18:32:38.843Z","repository":{"id":31875041,"uuid":"35443350","full_name":"orangemug/sql-stamp","owner":"orangemug","description":"The tiny SQL templating library","archived":false,"fork":false,"pushed_at":"2016-07-13T09:22:28.000Z","size":161,"stargazers_count":5,"open_issues_count":6,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-01T00:37:44.328Z","etag":null,"topics":["sql"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"projectstorm/react-diagrams","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/orangemug.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2015-05-11T18:53:13.000Z","updated_at":"2018-04-27T16:40:59.000Z","dependencies_parsed_at":"2022-08-17T19:30:54.060Z","dependency_job_id":null,"html_url":"https://github.com/orangemug/sql-stamp","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/orangemug/sql-stamp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orangemug%2Fsql-stamp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orangemug%2Fsql-stamp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orangemug%2Fsql-stamp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orangemug%2Fsql-stamp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orangemug","download_url":"https://codeload.github.com/orangemug/sql-stamp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orangemug%2Fsql-stamp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262923701,"owners_count":23385428,"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":["sql"],"created_at":"2024-11-21T14:43:18.018Z","updated_at":"2025-07-11T18:32:38.282Z","avatar_url":"https://github.com/orangemug.png","language":"JavaScript","readme":"# sql-stamp\nThe tiny SQL templating library, with the aim to be as simple as possible so to not get in the way of you writing SQL.\n\n[![stability-unstable](https://img.shields.io/badge/stability-unstable-yellow.svg)][stability]\n[![Build Status](https://circleci.com/gh/orangemug/sql-stamp.png?style=shield)][circleci]\n[![Test Coverage](https://codeclimate.com/github/orangemug/sql-stamp/badges/coverage.svg)][codeclimate]\n[![Dependency Status](https://david-dm.org/orangemug/sql-stamp.svg)][dm-prod]\n[![Dev Dependency Status](https://david-dm.org/orangemug/sql-stamp/dev-status.svg)][dm-dev]\n\n[stability]:   https://github.com/orangemug/stability-badges#unstable\n[circleci]:    https://circleci.com/gh/orangemug/sql-stamp\n[codeclimate]: https://codeclimate.com/github/orangemug/sql-stamp/coverage\n[dm-prod]:     https://david-dm.org/orangemug/sql-stamp\n[dm-dev]:      https://david-dm.org/orangemug/sql-stamp#info=devDependencies\n\n\nIt supports the following conditionals:\n\n * `{=key, optionalDefault}`  - Turns args into `?` with an optional default\n * `{!key, optionalDefault}` - Passed raw into the SQL\n * `{?key, replaceTruthy, replaceFalsey}` - Ternary switch, the defaults are replaceTruthy/replaceFalsey === true/false\n * `{\u003epath, optionalDataKeys*}` - Require file from the templates, the data keys can take on the format\n   * `{\u003epath id:user.id}` - pass `user.id` as `id`\n   * `{\u003epath user.id}` - pass `user.id` as `id`\n   * `{\u003epath ...user}` - object spread, in the same way as javascript [ES6 spread operator](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Operators/Spread_operator)\n\n\n## Why?\nI guess the best way to answer that is why not a HTML templating language like mustache? Basically these support loops and conditionals sql-stamp doesn't because I want the SQL to be kept clean and readable. It does however support a limited ternary switch for feature switches. Also it'll add in `?` as params so you can use your SQL libraries injection protection.\n\n\n## Install\n\n```sh\nnpm install sql-stamp --save\n```\n\n## API\nThe API is as follows\n\n```js\nvar sqlStamp = require(\"sql-stamp\");\nvar tmpl = sqlStamp([\n  /* Pass a list of SQL templates */\n  __dirname+\"/friends.sql\",\n  __dirname+\"/example.sql\"\n]).then(function(sql) {\n  // 'sql' call with 'sql(pathToFile, args)' to exec the template\n});\n\nvar files = glob.sync(\"./sql/**/*.sql\")\nsqlStamp(files).then(function(sql) {\n  sql(__dirname+\"../lib/sql/foo.sql\", {foo: \"bar\"});\n  // =\u003e {sql: \"select...\", args: [\"bar\"]}\n});\n```\n\nSo for example given the following SQL file which selects all friend requests you've accepted\n\n```sql\n/* ./friends.sql */\nselect * from friends where status = \"accepted\"\n```\n\nThe following file can **require** this as a CTE (\u003chttp://www.postgresql.org/docs/9.1/static/queries-with.html\u003e) via a require directive `{\u003e ./file/path.sql}`\n\n```sql\n/* ./example.sql */\nWITH friend AS (\n  {\u003e ./friends.sql}\n)\nselect\n  *\nfrom\n  account\nwhere\n  account.id = friend.toId\n  AND friend.fromId = {accountId}\n  AND (\n    {?filterDisabled} OR {!filterKey} = {filterVal}\n  )\n```\n\nWhen we run the following\n\n```js\nvar out = tmpl(__dirname+\"/example.sql\", {\n  accountId: 1,\n  filterDisabled: false,\n  filterKey: \"role\",\n  filterVal: \"dev\"\n});\n```\n\nThe following will be returned\n\n```js\n{\n  args: [1, \"dev\"],\n  sql: SQL\n}\n```\n\nWhere `SQL` is\n\n```sql\nWITH friend AS (\n  select * from friends where status = \"active\"\n)\nselect\n  *\nfrom\n  account\nwhere\n  account.id = friend.toId\n  AND friend.fromId = ?\n  AND (\n    /*feature:filterDisabled*/ false AND role = ?\n  )\n```\n\n## Errors\nYou'll get more descriptive errors about where the error happened in your source SQL. This can be disabled with `{prettyErrors: false}`\n\n```\nSQLError: Too many args\n\nselect\n  *\nfrom\n  account\nwhere\n  foo = {too, many, args}\n--------^\n```\n\nYou can see some more examples in the tests here [here](test/errors/index.js)\n\n\n## Test\nRun the unit tests\n\n```\nnpm test\n```\n\nUnit tests with code coverage\n\n```\nnpm run coverage\n```\n\nAnd some really simple benchmarks\n\n```\nnpm run benchmark\n```\n\n## Thanks\nThanks to [Pearlshare](http://www.pearlshare.com) for supporting development and [Oliver Brooks](https://github.com/oliverbrooks/) for help with design.\n\n\n## License\n[MIT](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forangemug%2Fsql-stamp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forangemug%2Fsql-stamp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forangemug%2Fsql-stamp/lists"}