{"id":15024879,"url":"https://github.com/zerodaycode/canyon-sql","last_synced_at":"2025-05-16T10:07:24.211Z","repository":{"id":42625213,"uuid":"401119459","full_name":"zerodaycode/Canyon-SQL","owner":"zerodaycode","description":"A full asyncronous Rust ORM and query builder for multiple databases","archived":false,"fork":false,"pushed_at":"2025-05-09T10:57:22.000Z","size":4815,"stargazers_count":107,"open_issues_count":10,"forks_count":7,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-09T11:56:13.415Z","etag":null,"topics":["database","orm","postgres","rust","sql","tiberius"],"latest_commit_sha":null,"homepage":"https://zerodaycode.github.io/canyon-book/","language":"Rust","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/zerodaycode.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-08-29T18:56:56.000Z","updated_at":"2025-03-14T23:22:18.000Z","dependencies_parsed_at":"2024-01-14T12:47:30.357Z","dependency_job_id":"8cbf2c11-b2ad-40fe-8fbe-054661b6cacf","html_url":"https://github.com/zerodaycode/Canyon-SQL","commit_stats":{"total_commits":447,"total_committers":10,"mean_commits":44.7,"dds":0.5324384787472036,"last_synced_commit":"b855518f62afde744528927bcb117b008aa226f8"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodaycode%2FCanyon-SQL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodaycode%2FCanyon-SQL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodaycode%2FCanyon-SQL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodaycode%2FCanyon-SQL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zerodaycode","download_url":"https://codeload.github.com/zerodaycode/Canyon-SQL/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254509476,"owners_count":22082891,"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":["database","orm","postgres","rust","sql","tiberius"],"created_at":"2024-09-24T20:01:06.894Z","updated_at":"2025-05-16T10:07:19.203Z","avatar_url":"https://github.com/zerodaycode.png","language":"Rust","readme":"\u003cdiv align=\"center\"\u003e\n\u003ch1\u003eCANYON-SQL\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ch3\u003e\u003cstrong\u003eA full written in `Rust` ORM for multiple databases\u003c/strong\u003e\u003c/h3\u003e\n    \u003ch4\u003e`Canyon-SQL` is a high level abstraction for working with multiple databases concurrently. Is build on top of the `async` language features\nto provide a high speed, high performant library to handling data access for consumers.\u003c/h4\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n\u003c/div\u003e\n\u003cdiv align=\"center\"\u003e\n\n![Rust](https://img.shields.io/badge/rust-%23000000.svg?style=for-the-badge\u0026logo=rust\u0026logoColor=white)\n\n![crates.io](https://img.shields.io/crates/v/canyon_sql?style=for-the-badge)\n\n[![Continuous Integration](https://github.com/zerodaycode/Canyon-SQL/actions/workflows/continuous-integration.yml/badge.svg)](https://github.com/zerodaycode/Canyon-SQL/actions/workflows/continuous-integration.yml)\n[![Code Quality](https://github.com/zerodaycode/Canyon-SQL/actions/workflows/code-quality.yml/badge.svg)](https://github.com/zerodaycode/Canyon-SQL/actions/workflows/code-quality.yml)\n[![Code Coverage Measure](https://zerodaycode.github.io/Canyon-SQL/badges/flat.svg)](https://zerodaycode.github.io/Canyon-SQL)\n[![Code Coverage Status](https://github.com/zerodaycode/Canyon-SQL/actions/workflows/code-coverage.yml/badge.svg)](https://github.com/zerodaycode/Canyon-SQL/actions/workflows/code-coverage.yml)\n\u003c/div\u003e\n\n## Early stage disclaimer\n\nThe library it's still on an `early stage` state.\nAny contrib via `fork` + `PR` it's really appreciated. Currently we are involved in a really active development on the project.\n\n## :memo: Full documentation resources\n\nThere is a `work-in-progress` web page, build with `mdBook` containing the official documentation.\nHere is where you will find all the technical documentation for `Canyon-SQL`.\nYou can read it [by clicking this link](https://zerodaycode.github.io/canyon-book/)\nIf you want to contribute in some section of the documentation [canyon-book repository](https://github.com/zerodaycode/canyon-book):\n\n## :pushpin: Most important features\n\n- **Async** by default. Almost every functionality provided is ready to be consumed concurrently.\n- Use of multiple datasources. You can query multiple databases at the same time, even different ones! This means that you will be able to query concurrently a `PostgreSQL` database and a `SqlServer` or `MySql` one in the same project.\n- Is macro based. With a few annotations and a configuration file, you are ready to write your data access.\n- Allows **migrations**. `Canyon-SQL` comes with a *god-mode* that will manage every table on your database for you. You can modify in `Canyon` code your tables internally, altering columns, setting up constraints... Also, in the future, we have plans to allow you to manipulate the whole server, like creating databases, altering configurations... everything, but in a programmatically approach with `Canyon`!\n\n## Supported databases\n\n`Canyon-SQL` currently has support for work with the following databases:\n\n- PostgreSQL (via `tokio-postgres` crate)\n- SqlServer (via `tiberius` crate)\n- MySql (via `mysql-async` crate)\n\nEvery crate listed above is an `async` based crate, in line with the guidelines of the `Canyon-SQL` design.\n\nThere are plans to include more databases engines.\n\n## Better by example\n\nLet's take a look to see how the `Canyon` code looks like!\n\n### The classical SELECT * FROM {table_name}\n\n```rust\nlet find_all_result: Result\u003cVec\u003cLeague\u003e, Box\u003cdyn Error + Send + Sync\u003e\u003e =  League::find_all().await;\n\n// Connection doesn't return an error\nassert!(find_all_result.is_ok());\n// We retrieved elements from the League table\nassert!(!find_all_result.unwrap().is_empty());\n```\n\n### :mag_right: Performing a search over the primary key column\n\n```rust\nlet find_by_pk_result: Result\u003cOption\u003cLeague\u003e, Box\u003cdyn Error + Send + Sync\u003e\u003e = League::find_by_pk(\u00261).await;\n\nassert!(find_by_pk_result.as_ref().unwrap().is_some());\n\nlet some_league = find_by_pk_result.unwrap().unwrap();\nassert_eq!(some_league.id, 1);\nassert_eq!(some_league.ext_id, 100695891328981122_i64);\nassert_eq!(some_league.slug, \"european-masters\");\nassert_eq!(some_league.name, \"European Masters\");\nassert_eq!(some_league.region, \"EUROPE\");\nassert_eq!(\n    some_league.image_url,\n    \"http://static.lolesports.com/leagues/EM_Bug_Outline1.png\"\n);\n```\n\nNote the leading reference on the `find_by_pk(...)` parameter. This associated function receives an `\u0026dyn QueryParameter\u003c'_\u003e` as argument, not a value.\n\n### :wrench: Building more complex queries\n\nTo exemplify the capabilities of `Canyon`, we will use `SelectQueryBuilder\u003cT\u003e`, which implements the `QueryBuilder\u003cT\u003e` trait\nto build a more complex where, filtering data and joining tables.\n\n```rust\nlet mut select_with_joins = LeagueTournament::select_query();\n    select_with_joins\n        .inner_join(\"tournament\", \"league.id\", \"tournament.league_id\")\n        .left_join(\"team\", \"tournament.id\", \"player.tournament_id\")\n        .r#where(LeagueFieldValue::id(\u00267), Comp::Gt)\n        .and(LeagueFieldValue::name(\u0026\"KOREA\"), Comp::Eq)\n        .and_values_in(LeagueField::name, \u0026[\"LCK\", \"STRANGER THINGS\"]);\n    // NOTE: We don't have in the docker the generated relationships\n    // with the joins, so for now, we are just going to check that the\n    // generated SQL by the SelectQueryBuilder\u003cT\u003e is the spected\n    assert_eq!(\n        select_with_joins.read_sql(),\n        \"SELECT * FROM league INNER JOIN tournament ON league.id = tournament.league_id LEFT JOIN team ON tournament.id = player.tournament_id WHERE id \u003e $1 AND name = $2  AND name IN ($2, $3) \"\n    )\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e For now, when you use joins, you will need to create a new model with the columns in both tables (in case that you desire the data in such columns), but just follows the usual process with the CanyonMapper.\nIt will try to retrieve the data for every field declared. If you don't declare a field that is in the open clause, in this case (*), that field won't be retrieved. No problem. But if you have fields that aren't mapable with some column in the database, the program will panic.\n\n## More examples\n\nIf you want to see more examples, you can take a look into the `tests` folder, at the root of this repository. Every available database operation is tested there, so you can use it to find the usage of the described operations in the documentation mentioned above.\n\n## :octocat: Contributing to CANYON-SQL\n\nFirst of all, thanks for taking in consideration helping us with the project.\nYou can take a look to our [templated guide](./CONTRIBUTING.md).\n\nBut, to summarize:\n\n- Take a look at the already opened issues, to verify if it already exists or if someone is already taking care about solving it. Even though, you can enter to participate and explain your point of view, or even help to accomplish the task.\n- Make a fork of `Canyon-SQL`\n- If you opened an issue, create a branch from the base branch of the repo (that's the default), and point it to your fork.\n- After completing your changes, open a `PR` to the default branch. Fill the template provided in the best way possible.\n- Wait for the approval. In most of cases, a test over the feature will be required before approving your changes.\n\n## :question: What about the tests?\n\nTypically in `Canyon`, isolated unit tests are written as doc-tests, and the integration ones are under the folder `./tests`\n\nIf you want to run the tests (because this is the first thing that you want to do after fork the repo), before moving forward, there are a couple of things that have to be considered.\n\n- You will need Docker installed in the target machine.\n- If you have Docker, and `Canyon-SQL` cloned of forked, you can run our docker-compose file `(docker/docker-compose.yml)`, which will initialize a `PostgreSQL` and `MySql` database and will put content on it to make the tests able to work.\n- Finally, some tests run against `MSSQL`. We didn't found a nice way of inserting data directly when the Docker wakes up, but instead, we run a very special test located at `tests/crud/mod.rs`, that is named `initialize_sql_server_docker_instance`. When you run this one, initial data will be inserted into the tables that are created when this test run.\n(If you know a better way of doing this, please, open an issue to let us know, and improve this process!)\n\n## Known issues\n\n### Missing dependency: OpenSSL\n\nThere's a certain set of common issues while building `Canyon-SQL` in development or in client code. Those building issues\nare related with missing packages or dependencies that `Cargo` doesn't resolves automatically depending on the underlying OS.\n\n```\nopenssl-sys@0.9.104: Could not find directory of OpenSSL installation, and this `-sys` crate cannot proceed without this knowledge.\nIf OpenSSL is installed and this crate had trouble finding it,  you can set the `OPENSSL_DIR` environment variable for the compilation process.\nSee stderr section below for further information.\n```\n\nThis means that the `OpenSSL` package isn't installed on your system or not in *PATH*.\n\nIn a Debian based system, you can just `sudo apt install libssl-dev`. For others, just use your package manager\nto solve it by install it.\n\n### Missing dependency: pkg-config\n\n```\nCould not find openssl via pkg-config:\n  Could not run `PKG_CONFIG_ALLOW_SYSTEM_CFLAGS=1 pkg-config --libs --cflags openssl`\n  The pkg-config command could not be found.\n```\n`Cargo` may try to discover the `OpenSSL` package via `pkg-config`. If you find this error, you can\n`sudo apt install pkg-config` on *apt* based systems. For other systems, you must read your package manager\ndocs and install it.\n\n### failed to run custom build command for `libgssapi-sys vX.X.X`\n\nThe problem is missing a *C* header `gssapi.h`.\n\n- Alpine: `apk --update add krb5-pkinit krb5-dev krb5`\n- Ubuntu: `apt-get -y install gcc libgssapi-krb5-2 libkrb5-dev libsasl2-modules-gssapi-mit`\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzerodaycode%2Fcanyon-sql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzerodaycode%2Fcanyon-sql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzerodaycode%2Fcanyon-sql/lists"}