The library it's still on an early stage state. Any contrib via fork + PR it's really appreciated. Currently we are involved in a really active development on the project.

There is a work-in-progress web page, build with mdBook containing the official documentation. Here is where you will find all the technical documentation for Canyon-SQL. You can read it by clicking this link If you want to contribute in some section of the documentation canyon-book repository:

• Async by default. Almost every functionality provided is ready to be consumed concurrently.
• 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.
• Is macro based. With a few annotations and a configuration file, you are ready to write your data access.
• 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!

Canyon-SQL currently has support for work with the following databases:

• PostgreSQL (via tokio-postgres crate)
• SqlServer (via tiberius crate)
• MySql (via mysql-async crate)

Every crate listed above is an async based crate, in line with the guidelines of the Canyon-SQL design.

There are plans to include more databases engines.

Let's take a look to see how the Canyon code looks like!

let find_all_result: Result<Vec<League>, Box<dyn Error + Send + Sync>> =  League::find_all().await;

// Connection doesn't return an error
assert!(find_all_result.is_ok());
// We retrieved elements from the League table
assert!(!find_all_result.unwrap().is_empty());

let find_by_pk_result: Result<Option<League>, Box<dyn Error + Send + Sync>> = League::find_by_pk(&1).await;

assert!(find_by_pk_result.as_ref().unwrap().is_some());

let some_league = find_by_pk_result.unwrap().unwrap();
assert_eq!(some_league.id, 1);
assert_eq!(some_league.ext_id, 100695891328981122_i64);
assert_eq!(some_league.slug, "european-masters");
assert_eq!(some_league.name, "European Masters");
assert_eq!(some_league.region, "EUROPE");
assert_eq!(
    some_league.image_url,
    "http://static.lolesports.com/leagues/EM_Bug_Outline1.png"
);

Note the leading reference on the find_by_pk(...) parameter. This associated function receives an &dyn QueryParameter as argument, not a value.

To exemplify the capabilities of Canyon, we will use SelectQueryBuilder<T>, which implements the QueryBuilder<T> trait to build a more complex where, filtering data and joining tables.

let mut select_with_joins = LeagueTournament::select_query();
    select_with_joins
        .inner_join("tournament", "league.id", "tournament.league_id")
        .left_join("team", "tournament.id", "player.tournament_id")
        .r#where(LeagueFieldValue::id(&7), Operator::Gt)
        .and(LeagueFieldValue::name(&"KOREA"), Operator::Eq)
        .and_values_in(LeagueField::name, &["LCK", "STRANGER THINGS"]);
    // NOTE: We don't have in the docker the generated relationships
    // with the joins, so for now, we are just going to check that the
    // generated SQL by the SelectQueryBuilder<T> is the spected
    assert_eq!(
        select_with_joins.read_sql(),
        "SELECT * FROM league INNER JOIN tournament ON league.id = tournament.league_id LEFT JOIN team ON tournament.id = player.tournament_id WHERE id > $1 AND name = $2  AND name IN ($2, $3) "
    )

If 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.

First of all, thanks for taking in consideration helping us with the project. You can take a look to our templated guide.

But, to summarize:

• 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.
• Make a fork of Canyon-SQL
• 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.
• After completing your changes, open a PR to the default branch. Fill the template provided in the best way possible.
• Wait for the approval. In most of cases, a test over the feature will be required before approving your changes.

Typically in Canyon, isolated unit tests are written as doc-tests, and the integration ones are under the folder ./tests

If 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.

• You will need Docker installed in the target machine.
• 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.
• 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. (If you know a better way of doing this, please, open an issue to let us know, and improve this process!)

There's a certain set of common issues while building Canyon-SQL in development or in client code. Those building issues are related with missing packages or dependencies that Cargo doesn't resolves automatically depending on the underlying OS.

openssl-sys@0.9.104: Could not find directory of OpenSSL installation, and this `-sys` crate cannot proceed without this knowledge.
If OpenSSL is installed and this crate had trouble finding it,  you can set the `OPENSSL_DIR` environment variable for the compilation process.
See stderr section below for further information.

This means that the OpenSSL package isn't installed on your system or not in PATH.

In a Debian based system, you can just sudo apt install libssl-dev. For others, just use your package manager to solve it by install it.

Could not find openssl via pkg-config:
  Could not run `PKG_CONFIG_ALLOW_SYSTEM_CFLAGS=1 pkg-config --libs --cflags openssl`
  The pkg-config command could not be found.

Cargo may try to discover the OpenSSL package via pkg-config. If you find this error, you can sudo apt install pkg-config on apt based systems. For other systems, you must read your package manager docs and install it.