{"id":13483766,"url":"https://github.com/onyxframework/sql","last_synced_at":"2025-08-24T18:35:16.373Z","repository":{"id":94994869,"uuid":"104816583","full_name":"onyxframework/sql","owner":"onyxframework","description":"A delightful SQL ORM ☺️","archived":false,"fork":false,"pushed_at":"2020-03-31T12:27:05.000Z","size":821,"stargazers_count":91,"open_issues_count":27,"forks_count":7,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-10T19:16:54.280Z","etag":null,"topics":["crystal","crystal-db","onyxframework","orm","query-builder","sql","sql-orm"],"latest_commit_sha":null,"homepage":"https://api.onyxframework.com/sql","language":"Crystal","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/onyxframework.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}},"created_at":"2017-09-26T00:40:20.000Z","updated_at":"2024-05-31T11:53:53.000Z","dependencies_parsed_at":"2023-06-11T12:30:34.294Z","dependency_job_id":null,"html_url":"https://github.com/onyxframework/sql","commit_stats":null,"previous_names":["vladfaust/core.cr"],"tags_count":39,"template":false,"template_full_name":null,"purl":"pkg:github/onyxframework/sql","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onyxframework%2Fsql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onyxframework%2Fsql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onyxframework%2Fsql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onyxframework%2Fsql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onyxframework","download_url":"https://codeload.github.com/onyxframework/sql/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onyxframework%2Fsql/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271922545,"owners_count":24844227,"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","status":"online","status_checked_at":"2025-08-24T02:00:11.135Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["crystal","crystal-db","onyxframework","orm","query-builder","sql","sql-orm"],"created_at":"2024-07-31T17:01:15.083Z","updated_at":"2025-08-24T18:35:16.342Z","avatar_url":"https://github.com/onyxframework.png","language":"Crystal","readme":"\u003ca href=\"https://onyxframework.org\"\u003e\u003cimg width=\"100\" height=\"100\" src=\"https://onyxframework.org/img/logo.svg\"\u003e\u003c/a\u003e\n\n# Onyx::SQL\n\n[![Built with Crystal](https://img.shields.io/badge/built%20with-crystal-000000.svg?style=flat-square)](https://crystal-lang.org/)\n[![Travis CI build](https://img.shields.io/travis/onyxframework/sql/master.svg?style=flat-square)](https://travis-ci.org/onyxframework/sql)\n[![Docs](https://img.shields.io/badge/docs-online-brightgreen.svg?style=flat-square)](https://docs.onyxframework.org/sql)\n[![API docs](https://img.shields.io/badge/api_docs-online-brightgreen.svg?style=flat-square)](https://api.onyxframework.org/sql)\n[![Latest release](https://img.shields.io/github/release/onyxframework/sql.svg?style=flat-square)](https://github.com/onyxframework/sql/releases)\n\nA deligtful SQL ORM.\n\n## About 👋\n\nOnyx::SQL is a deligthful database-agnostic SQL ORM for [Crystal language](https://crystal-lang.org/). It features a convenient schema definition DSL, type-safe SQL query builder, clean architecture with Repository and more!\n\n## Installation 📥\n\nAdd these lines to your application's `shard.yml`:\n\n```yaml\ndependencies:\n  onyx:\n    github: onyxframework/onyx\n    version: ~\u003e 0.6.0\n  onyx-sql:\n    github: onyxframework/sql\n    version: ~\u003e 0.9.0\n```\n\nThis shard follows [Semantic Versioning v2.0.0](http://semver.org/), so check [releases](https://github.com/onyxframework/rest/releases) and change the `version` accordingly.\n\n\u003e Note that until Crystal is officially released, this shard would be in beta state (`0.*.*`), with every **minor** release considered breaking. For example, `0.1.0` → `0.2.0` is breaking and `0.1.0` → `0.1.1` is not.\n\nYou'd also need to add a database dependency conforming to the [crystal-db](https://github.com/crystal-lang/crystal-db) interface. For example, [pg](https://github.com/will/crystal-pg):\n\n```diff\ndependencies:\n  onyx:\n    github: onyxframework/onyx\n    version: ~\u003e 0.6.0\n  onyx-sql:\n    github: onyxframework/sql\n    version: ~\u003e 0.9.0\n+ pg:\n+   github: will/crystal-pg\n+   version: ~\u003e 0.18.0\n```\n\n## Usage 💻\n\nFor this PostgreSQL table:\n\n```sql\nCREATE TABLE users (\n  id          SERIAL      PRIMARY KEY,\n  name        TEXT        NOT NULL\n  created_at  TIMESTAMPTZ NOT NULL  DEFAULT now()\n);\n```\n\nDefine the user schema:\n\n```crystal\nrequire \"onyx/sql\"\n\nclass User\n  include Onyx::SQL::Model\n\n  schema users do\n    pkey id : Int32\n    type name : String, not_null: true\n    type created_at : Time, not_null: true, default: true\n  end\nend\n```\n\nInsert a new user instance:\n\n```crystal\nuser = User.new(name: \"John\")\nuser = Onyx::SQL.query(user.insert.returning(\"*\")).first\n\npp user # =\u003e #\u003cUser @id=1, @name=\"John\", @created_at=#\u003cTime ...\u003e\u003e\n```\n\nQuery the user:\n\n```crystal\nuser = Onyx::SQL.query(User.where(id: 1)).first?\n```\n\nWith another PostgreSQL table:\n\n```sql\nCREATE TABLE posts (\n  id          SERIAL      PRIMARY KEY,\n  author_id   INT         NOT NULL  REFERENCES  users(id),\n  content     TEXT        NOT NULL\n  created_at  TIMESTAMPTZ NOT NULL  DEFAULT now()\n);\n```\n\nDefine the post schema:\n\n```crystal\nclass Post\n  include Onyx::SQL::Model\n\n  schema posts do\n    pkey id : Int32\n    type author : User, not_null: true, key: \"author_id\"\n    type content : String, not_null: true\n    type created_at : Time, not_null: true, default: true\n  end\nend\n```\n\nAdd the posts reference to the user schema:\n\n```diff\nclass User\n  include Onyx::SQL::Model\n\n  schema users do\n    pkey id : Int32\n    type name : String, not_null: true\n    type created_at : Time, not_null: true, default: true\n+   type authored_posts : Array(Post), foreign_key: \"author_id\"\n  end\nend\n```\n\nCreate a new post:\n\n```crystal\nuser = User.new(id: 1)\npost = Post.new(author: user, content: \"Hello, world!\")\nOnyx::SQL.exec(post.insert)\n```\n\nQuery all the posts by a user with name \"John\":\n\n```crystal\nposts = Onyx::SQL.query(Post\n  .join(author: true) do |x|\n    x.select(:id, :name)\n    x.where(name: \"John\")\n  end\n)\n\nposts.first # =\u003e #\u003cPost @id=1, @author=#\u003cUser @id=1 @name=\"John\"\u003e, @content=\"Hello, world!\"\u003e\n```\n\n## Documentation 📚\n\nThe documentation is available online at [docs.onyxframework.org/sql](https://docs.onyxframework.org/sql).\n\n## Community 🍪\n\nThere are multiple places to talk about Onyx:\n\n* [Gitter](https://gitter.im/onyxframework)\n* [Twitter](https://twitter.com/onyxframework)\n\n## Support 🕊\n\nThis shard is maintained by me, [Vlad Faust](https://vladfaust.com), a passionate developer with years of programming and product experience. I love creating Open-Source and I want to be able to work full-time on Open-Source projects.\n\nI will do my best to answer your questions in the free communication channels above, but if you want prioritized support, then please consider becoming my patron. Your issues will be labeled with your patronage status, and if you have a sponsor tier, then you and your team be able to communicate with me privately in [Twist](https://twist.com). There are other perks to consider, so please, don't hesistate to check my Patreon page:\n\n\u003ca href=\"https://www.patreon.com/vladfaust\"\u003e\u003cimg height=\"50\" src=\"https://onyxframework.org/img/patreon-button.svg\"\u003e\u003c/a\u003e\n\nYou could also help me a lot if you leave a star to this GitHub repository and spread the word about Crystal and Onyx! 📣\n\n## Contributing\n\n1. Fork it ( https://github.com/onyxframework/sql/fork )\n2. Create your feature branch (git checkout -b my-new-feature)\n3. Commit your changes (git commit -am 'feat: some feature') using [Angular style commits](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit)\n4. Push to the branch (git push origin my-new-feature)\n5. Create a new Pull Request\n\n## Contributors\n\n- [Vlad Faust](https://github.com/vladfaust) - creator and maintainer\n\n## Licensing\n\nThis software is licensed under [MIT License](LICENSE).\n\n[![Open Source Initiative](https://upload.wikimedia.org/wikipedia/commons/thumb/4/42/Opensource.svg/100px-Opensource.svg.png)](https://opensource.org/licenses/MIT)\n","funding_links":["https://www.patreon.com/vladfaust"],"categories":["ORM/ODM Extensions","\u003ca name=\"Crystal\"\u003e\u003c/a\u003eCrystal"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonyxframework%2Fsql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonyxframework%2Fsql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonyxframework%2Fsql/lists"}