Merge pull request #32 from zerodaycode/development

Merge last changes from development to main

Author: TheRustifyer

.github/workflows/code-coverage.yml

@@ -1,7 +1,8 @@
-name: Linux CI && Code Coverage
+name: Linux CI
 
 on:
   push:
+    branches: 'development'
     tags:        
       - 'v[0-9]+.[0-9]+.[0-9]+'
       - 'v[0-9]+.[0-9]+.[0-9]+rc[0-9]+'
@@ -43,6 +44,7 @@ jobs:
 
       - name: Run tests
         run: |
+          cargo test initialize_sql_server_docker_instance -p tests --all-features --no-fail-fast -- --show-output --nocapture --include-ignored
           cargo test --all-features --no-fail-fast --target=x86_64-unknown-linux-gnu -- --show-output --test-threads=1
       
       - name: Waking up docker

.github/workflows/code-quality.yml

@@ -45,7 +45,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        crate: [canyon_connection, canyon_crud, canyon_macros, canyon_observer, canyon_observer, canyon_sql]
+        crate: [canyon_connection, canyon_crud, canyon_macros, canyon_observer, canyon_sql]
     steps:
       - uses: actions/checkout@v3
 

.github/workflows/continuous-integration.yml

@@ -2,9 +2,9 @@ name: Continuous Integration
 
 on:
   push:
-    branches: 'main'
+    branches: '*'
   pull_request:
-    branches: 'main'
+    branches: '*'
 
 env:
   CARGO_TERM_COLOR: always

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-# Contributing to CONTRIBUTING.md
+# Contributing to Canyon-SQL
 
-First off, thanks for taking the time to contribute! 
+First off, thanks for taking the time to contribute!
 
 All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. 
 
@@ -24,15 +24,13 @@ All types of contributions are encouraged and valued. See the [Table of Contents
 - [Commit Messages](#commit-messages)
 - [Join The Project Team](#join-the-project-team)
 
-
 ## Code of Conduct
 
 This project and everyone participating in it is governed by the
 [CONTRIBUTING.md Code of Conduct](blob/master/CODE_OF_CONDUCT.md).
 By participating, you are expected to uphold this code. Please report unacceptable behavior
 to <>.
 
-
 ## I Have a Question
 
 > If you want to ask a question, we assume that you have read the available [Documentation](https://github.com/zerodaycode/canyon-book).
@@ -47,16 +45,14 @@ If you then still feel the need to ask a question and need clarification, we rec
 
 We will then take care of the issue as soon as possible.
 
-
-
 ## I Want To Contribute
 
-> ### Legal Notice 
+### Legal Notice
+
 > When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license.
 
 ### Reporting Bugs
 
-
 #### Before Submitting a Bug Report
 
 A good bug report shouldn't leave others needing to chase you up for more information. Therefore, we ask you to investigate carefully, collect information and describe the issue in detail in your report. Please complete the following steps in advance to help us fix any potential bug as fast as possible.
@@ -72,12 +68,10 @@ A good bug report shouldn't leave others needing to chase you up for more inform
 - Possibly your input and the output
 - Can you reliably reproduce the issue? And can you also reproduce it with older versions?
 
-
 #### How Do I Submit a Good Bug Report?
 
 > You must never report security related issues, vulnerabilities or bugs including sensitive information to the issue tracker, or elsewhere in public. Instead sensitive bugs must be sent by email to <>.
 
-
 We use GitHub issues to track bugs and errors. If you run into an issue with the project:
 
 - Open an [Issue](/issues/new). (Since we can't be sure at this point whether it is a bug or not, we ask you not to talk about a bug yet and not to label the issue.)
@@ -93,7 +87,7 @@ Once it's filed:
 
 ### Suggesting Enhancements
 
-If you want to suggest an enhacement or new feature for the project, please [open a new issue](/issues) describing what you desire to improve, and, potentially, how you plan to contribute to the project.
+If you want to suggest an enhancement or new feature for the project, please [open a new issue](/issues) describing what you desire to improve, and, potentially, how you plan to contribute to the project.
 
 #### Before Submitting an Enhancement
 
@@ -112,6 +106,6 @@ Enhancement suggestions are tracked as [GitHub issues](/issues).
 - You may want to **include screenshots and animated GIFs** which help you demonstrate the steps or point out the part which the suggestion is related to. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux.
 - **Explain why this enhancement would be useful** to most CONTRIBUTING.md users. You may also want to point out the other projects that solved it better and which could serve as inspiration.
 
-
 ## Attribution
+
 This guide is based on the **contributing.md**. [Make your own](https://contributing.md/)!

README.md

@@ -2,8 +2,9 @@
 
 **A full written in `Rust` ORM for multiple databases.**
 
-- [![Linux CI](https://github.com/zerodaycode/Canyon-SQL/actions/workflows/code-coverage.yml/badge.svg)](https://github.com/zerodaycode/Canyon-SQL/actions/workflows/code-coverage.yml)
+- ![crates.io](https://img.shields.io/crates/v/canyon_sql.svg)
 - [![Code Coverage Measure](https://zerodaycode.github.io/Canyon-SQL/badges/flat.svg)](https://zerodaycode.github.io/Canyon-SQL)
+- [![Linux CI](https://github.com/zerodaycode/Canyon-SQL/actions/workflows/code-coverage.yml/badge.svg)](https://github.com/zerodaycode/Canyon-SQL/actions/workflows/code-coverage.yml)
 - [![Tests on macOS](https://github.com/zerodaycode/Canyon-SQL/actions/workflows/macos-tests.yml/badge.svg)](https://github.com/zerodaycode/Canyon-SQL/actions/workflows/macos-tests.yml)
 - [![Tests on Windows](https://github.com/zerodaycode/Canyon-SQL/actions/workflows/windows-tests.yml/badge.svg)](https://github.com/zerodaycode/Canyon-SQL/actions/workflows/windows-tests.yml)
 
@@ -27,8 +28,8 @@ You can read it [by clicking this link](https://zerodaycode.github.io/canyon-boo
 - 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 an `SqlServer` 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 programatically approach with `Canyon`!
+- 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`!
 
 ## Supported databases
 
@@ -40,3 +41,93 @@ Also, in the future, we have plans to allow you to manipulate the whole server,
 Every crate listed above is an `async` based crate, in line with the guidelines of the `Canyon-SQL` design.
 
 There are plans for include more databases engines.
+
+## Better by example
+
+Let's take a look to see how the `Canyon` code looks like!
+
+### The classical SELECT * FROM {table_name}
+
+```rust
+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());
+```
+
+### Performing a search over the primary key column
+
+```rust
+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.
+
+### Building more complex queries
+
+For exemplify the capabilities of `Canyon`, we will use `SelectQueryBuilder<T>`, which implements the `QueryBuilder<T>` trait
+for build a more complex where, filteing data and joining tables.
+
+```rust
+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), Comp::Gt)
+        .and(LeagueFieldValue::name(&"KOREA"), Comp::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) "
+    )
+```
+
+> Note: 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 habitual process with the CanyonMapper.
+It 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 map
+able with some column in the database, the program will panic.
+
+## More examples
+
+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
+
+## Contributing to CANYON-SQL
+
+First of all, thanks for take in consideration help us with the project.
+You can take a look to our [templated guide]((./CONTRIBUTING.md)).
+
+But, to summarize:
+
+- Take a look at the already opened issues, to see if already exists of it's someone already taking care about solving it. Even tho, 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 complete your changes, open a `PR` to the default branch. Fill the template provided in the best way you're able to do it
+- Wait for the approval. In most of cases, a test over the feature will be required before approve your changes
+
+## What about the tests?
+
+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), a couple of things have to be considered before.
+
+- 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` database and will put content on it to make the tests able to work.
+- Finally, some tests runs 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 a issue to let us know it, and improve this process!)

canyon_connection/src/canyon_database_connector.rs

@@ -61,7 +61,7 @@ impl DatabaseConnection {
 
                 tokio::spawn(async move {
                     if let Err(e) = new_connection.await {
-                        eprintln!("An error occured while trying to connect to the PostgreSQL database: {e}");
+                        eprintln!("An error occurred while trying to connect to the PostgreSQL database: {e}");
                     }
                 });
 
@@ -96,7 +96,7 @@ impl DatabaseConnection {
                 // TcpStream to connect to the server.
                 let tcp = TcpStream::connect(config.get_addr())
                     .await
-                    .expect("Error instanciating the SqlServer TCP Stream");
+                    .expect("Error instantiating the SqlServer TCP Stream");
 
                 // We'll disable the Nagle algorithm. Buffering is handled
                 // internally with a `Sink`.

canyon_connection/src/lib.rs

@@ -40,7 +40,7 @@ lazy_static! {
 /// in the configuration file.
 ///
 /// This avoids Canyon to create a new connection to the database on every query, potentially avoiding bottlenecks
-/// derivated from the instanciation of that new conn every time.
+/// derivated from the instantiation of that new conn every time.
 ///
 /// Note: We noticed with the integration tests that the [`tokio_postgres`] crate (PostgreSQL) is able to work in an async environment
 /// with a new connection per query without no problem, but the [`tiberius`] crate (MSSQL) sufferes a lot when it has continuous

canyon_crud/src/bounds.rs

@@ -45,7 +45,7 @@ where
 /// and convert it to a tuple struct formed by the column name as an String,
 /// and the dynamic value of the [`QueryParameter<'_>`] trait object contained
 /// inside the variant requested,
-/// enabling a convertion of that value into something
+/// enabling a conversion of that value into something
 /// that can be part of an SQL query.
 ///
 ///
@@ -229,7 +229,7 @@ pub trait QueryParameter<'a>: std::fmt::Debug + Sync + Send {
 /// This implementation is necessary because of the generic amplitude
 /// of the arguments of the [`Transaction::query`], that should work with
 /// a collection of [`QueryParameter<'a>`], in order to allow a workflow
-/// that is not dependant of the specific type of the argument that holds
+/// that is not dependent of the specific type of the argument that holds
 /// the query parameters of the database connectors
 impl<'a> IntoSql<'a> for &'a dyn QueryParameter<'a> {
     fn into_sql(self) -> ColumnData<'a> {

canyon_crud/src/crud.rs

@@ -210,7 +210,7 @@ mod sqlserver_query_launcher {
     where
         Z: AsRef<[&'a dyn QueryParameter<'a>]> + Sync + Send + 'a,
     {
-        // Re-generate de insert statement to adecuate it to the SQL SERVER syntax to retrieve the PK value(s) after insert
+        // Re-generate de insert statement to adequate it to the SQL SERVER syntax to retrieve the PK value(s) after insert
         if stmt.contains("RETURNING") {
             let c = stmt.clone();
             let temp = c

canyon_crud/src/query_elements/operators.rs

@@ -9,9 +9,9 @@ pub enum Comp {
     Eq,
     /// Operator "!=" not equals
     Neq,
-    /// Operator ">" greather than value
+    /// Operator ">" greater than value
     Gt,
-    /// Operator ">=" greather or equals than value
+    /// Operator ">=" greater or equals than value
     GtEq,
     /// Operator "<" less than value
     Lt,