{"id":16726939,"url":"https://github.com/lpil/yesql","last_synced_at":"2025-09-10T10:37:11.400Z","repository":{"id":46095223,"uuid":"117356763","full_name":"lpil/yesql","owner":"lpil","description":"An Elixir library for using SQL.","archived":false,"fork":false,"pushed_at":"2021-03-09T23:31:35.000Z","size":33,"stargazers_count":79,"open_issues_count":2,"forks_count":7,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-02-27T16:19:31.026Z","etag":null,"topics":["elixir","postgresql","sql"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lpil.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["lpil"]}},"created_at":"2018-01-13T15:56:51.000Z","updated_at":"2024-11-08T08:35:34.000Z","dependencies_parsed_at":"2022-08-01T00:38:08.542Z","dependency_job_id":null,"html_url":"https://github.com/lpil/yesql","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lpil%2Fyesql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lpil%2Fyesql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lpil%2Fyesql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lpil%2Fyesql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lpil","download_url":"https://codeload.github.com/lpil/yesql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243836015,"owners_count":20355615,"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":["elixir","postgresql","sql"],"created_at":"2024-10-12T22:55:18.088Z","updated_at":"2025-03-17T01:31:33.289Z","avatar_url":"https://github.com/lpil.png","language":"Elixir","readme":"# Yesql\n\nYesql is an Elixir library for _using_ SQL.\n\n## Rationale\n\nYou're writing Elixir You need to write some SQL.\n\nOne option is to use [Ecto](https://github.com/elixir-ecto/ecto/),\nwhich provides a sophisticated DSL for generating database queries at\nruntime. This can be convenient for simple use, but its abstraction\nonly works with the simplest and common database features. Because of\nthis either the abstraction breaks down and we start passing raw strings\nto `Repo.query` and `fragment`, or we will neglect these database\nfeatures altogether.\n\nSo what's the solution? Keep the SQL as SQL. Have one file with your\nquery:\n\n``` sql\nSELECT *\nFROM users\nWHERE country_code = :country_code\n```\n\n...and then read that file to turn it into a regular Elixir function at\ncompile time:\n\n```elixir\ndefmodule Query do\n  use Yesql, driver: Postgrex, conn: MyApp.ConnectionPool\n\n  Yesql.defquery(\"some/where/select_users_by_country.sql\")\nend\n\n# A function with the name `users_by_country/1` has been created.\n# Let's use it:\niex\u003e Query.users_by_country(country_code: \"gbr\")\n{:ok, [%{name: \"Louis\", country_code: \"gbr\"}]}\n```\n\nBy keeping the SQL and Elixir separate you get:\n\n- No syntactic surprises. Your database doesn't stick to the SQL\n  standard - none of them do - but Yesql doesn't care. You will\n  never spend time hunting for \"the equivalent Ecto syntax\". You will\n  never need to fall back to a `fragment(\"some('funky'::SYNTAX)\")` function.\n- Better editor support. Your editor probably already has great SQL\n  support. By keeping the SQL as SQL, you get to use it.\n- Team interoperability. DBAs and developers less familiar with Ecto can\n  read and write the SQL you use in your Elixir project.\n- Easier performance tuning. Need to `EXPLAIN` that query plan? It's\n  much easier when your query is ordinary SQL.\n- Query reuse. Drop the same SQL files into other projects, because\n  they're just plain ol' SQL. Share them as a submodule.\n- Simplicity. This is a very small library, it is easier to understand\n  and review than Ecto and similar.\n\n\n### When Should I Not Use Yesql?\n\nWhen you need your SQL to work with many different kinds of\ndatabase at once. If you want one complex query to be transparently\ntranslated into different dialects for MySQL, Oracle, Postgres etc.,\nthen you genuinely do need an abstraction layer on top of SQL.\n\n\n## Alternatives\n\nWe've talked about Ecto, but how does Yesql compare to `$OTHER_LIBRARY`?\n\n### [eql](https://github.com/artemeff/eql)\n\neql is an Erlang library with similar inspiration and goals.\n\n- eql offers no solution for query execution, the library user has to\n  implement this. Yesql offers a friendly API.\n- Being an Erlang library eql has to compile the queries at runtime, Yesql\n  does this at compile time so you don't need to write initialisation code and\n  store your queries somewhere.\n- eql requires the `neotoma` PEG compiler plugin, Yesql only uses the Elixir\n  standard library.\n- Yesql uses prepared statements so query parameters are sanitised and are\n  only valid in positions that your database will accept parameters. eql\n  functions more like a templating tool so parameters can be used in any\n  position and sanitisation is left up to the user.\n- A subjective point, but I believe the Yesql's implementation is simpler than\n  eql's, while offering more features.\n\n### [ayesql](https://github.com/alexdesousa/ayesql)\n\nayesql is another Elixir library, a bit more powerful than yesql:\n\n- It offers support for various SQL statements in a single file.\n- Special constructs for [query composability](https://hexdocs.pm/ayesql/readme.html#query-composition) in SQL files.\n- Special constructs for [optional parameters](https://hexdocs.pm/ayesql/readme.html#optional-parameters) in SQL files.\n\nyesql will keep your SQL queries closer to canonical SQL, but if you start finding\nit limiting or convoluted maybe it would be a good time to check out more powerful\nabstractions like ayesql or Ecto.\n\n## Development \u0026 Testing\n\n```sh\ncreatedb yesql_test\nmix deps.get\nmix test\n```\n\n\n## Other Languages\n\nYesql ~~rips off~~ is inspired by [Kris Jenkins' Clojure Yesql](https://github.com/krisajenkins/yesql).\nSimilar libraries can be found for many languages:\n\n| Language   | Project                                            |\n| ---        | ---                                                |\n| C#         | [JaSql](https://bitbucket.org/rick/jasql)          |\n| Clojure    | [YeSPARQL](https://github.com/joelkuiper/yesparql) |\n| Clojure    | [Yesql](https://github.com/krisajenkins/yesql)     |\n| Elixir     | [ayesql](https://github.com/alexdesousa/ayesql)    |\n| Erlang     | [eql](https://github.com/artemeff/eql)             |\n| Go         | [DotSql](https://github.com/gchaincl/dotsql)       |\n| Go         | [goyesql](https://github.com/nleof/goyesql)        |\n| JavaScript | [Preql](https://github.com/NGPVAN/preql)           |\n| JavaScript | [sqlt](https://github.com/eugeneware/sqlt)         |\n| PHP        | [YepSQL](https://github.com/LionsHead/YepSQL)      |\n| Python     | [Anosql](https://github.com/honza/anosql)          |\n| Ruby       | [yayql](https://github.com/gnarmis/yayql)          |\n\n\n## License\n\nCopyright © 2018 Louis Pilfold. All Rights Reserved.\n","funding_links":["https://github.com/sponsors/lpil"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flpil%2Fyesql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flpil%2Fyesql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flpil%2Fyesql/lists"}