compact_sql 0.0.5

Compact SQL
===========

A simple macros allows to write SQL queries for Postgres which will be compacted
(and optionally checked) at compile-time.

## Dependency

```toml
[dependencies]
compact_sql = "0.0.5"
```

### Pretty error

Use `pretty-errors` feature (requires unstable Rust version) if you can get better errors with pointing to a concrete error span.

```toml
[dependencies]
compact_sql = { version = "0.0.5", features = ["pretty-errors"] }
```

## Using Compact SQL

### Generate just an SQL string
```rust
use compact_sql::pg_sql;

fn main() {
    let sql = pg_sql! {
        SELECT
            relname,
            relnamespace,
            format("%I", oid),
        FROM
            pg_catalog.pg_class
        WHERE
            oid = {var_oid}::oid
    };
    assert_eq!(
        sql,
        "SELECT relname,relnamespace,format('%I',oid)FROM pg_catalog.pg_class WHERE oid=$1::oid"
    );
}
```

Note! There are allowed commas between keywords (more convenient for VCS), named parameters in curly
braces are replaced with "$x" Postgres numbered parameters (the same number for the same names).

Common keywords like "SELECT", "AS", etc. are required (as warnings) to be uppercase.

### Generate SQL string and struct with SQL params

The macros replaces "named parameters" with numbered parameters for Postgres, and it is reasonably
to create struct where attributes names are the same as names parameters. Moreover it is easy to
constraint such parameters with Rust's types.

```rust
use compact_sql::pg_sql;

pg_sql! {
    impl OidFromPgClass {
        SELECT
            oid,
            relkind,
        FROM
            pg_catalog.pg_class
        WHERE
            relname = {name: String}
            AND
            relnamespace = {nsp: u32}
    }
}


fn main() {
    let name: String = "pg_attribute".to_string();
    let params = OidFromPgClass {
        nsp:  &11,
        name: &name,
    };
    assert_eq!(OidFromPgClass::PARAM_NAMES, &["name", "nsp"]);
    assert_eq!(
        OidFromPgClass::SQL_TEXT,
        concat!(
            "-- OidFromPgClass\n",
            "SELECT oid,relkind FROM pg_catalog.pg_class WHERE relname=$1 AND relnamespace=$2",
        ),
    );
    assert_eq!(params.params().len(), 2);
}
```

### Generate SQL, struct with SQL params and traits implementation
This library can generate trait implementation bodies for those who want to build a library
(or internal functions) that work with generated structs. Not all user structs are designed
to be public, which is why the generated trait implementations are not referenced in a public
crate. Instead, trait names are used from the local scope. However, you can still use traits
from the public `compact_sql_traits` crate.

You can specify the expected number of rows, and different traits will be used accordingly.
Additionally, you must declare the return row type. You can use the
`PgResultRow` derive macro to generate the necessary implementation.

```rust
use compact_sql::{pg_sql, PgResultRow};
use compact_sql_traits::*;
use futures_util::{pin_mut, StreamExt, TryStreamExt};
use tokio_postgres::Client;

type PgResult<T> = Result<T, tokio_postgres::Error>;

#[derive(Debug, PgResultRow)]
struct PgClassItem {
    relname:      String,
    relnamespace: u32,
}

#[derive(Debug)]
enum QueriesId {
    GetPgClassItem,
}

pg_sql! {
        // You can add container attributes like derive to the generated struct:
        #[derive(Debug)]
        impl QueriesId::GetPgClassItem for ?PgClassItem {
            SELECT
                relname,
                relnamespace,
            FROM
                pg_catalog.pg_class
            WHERE
                oid = {class_oid}
        }
}

async fn query_opt<Q: QueryMaybeOne>(db: &Client, params: Q) -> PgResult<Option<Q::ResultRow>>
where <Q as QueryMaybeOne>::SqlIdType: std::fmt::Debug
{
    dbg!(Q::SQL_ID);
    let query_result = db
        .query_raw(Q::SQL_TEXT, params.params())
        .await?;
    let future = query_result.map_ok(Q::ResultRow::from_row);
    pin_mut!(future);

    Ok(match future.next().await {
        None => None,
        Some(v) => Some(v??),
    })
}

async fn func(db: &Client) -> PgResult<()> {
    let name: String = "pg_attribute".to_string();
    let params = GetPgClassItem {
        class_oid: &11,
    };
    let res: Option<PgClassItem> = query_opt(db, params).await?;
    dbg!(res);

    Ok(())
}
```

You can see more examples in the `test_trait_impl.rs`.


### Test SQL queries

If you want to check queries (via "prepare") you can define ENVs for the DBMS:
* `TEST_PG_HOST`
* `TEST_PG_PORT` (optional; default: 5432)
* `TEST_PG_USER` (optional; default: "postgres")
* `TEST_PG_PASS` (optional; default: "")
* `TEST_PG_DATB`

## License

Licensed under either of

* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally
submitted for inclusion in the work by you, as defined in the Apache-2.0
license, shall be dual licensed as above, without any additional terms or
conditions.