xitca-postgres 0.4.0

an async postgres client
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

# unreleased 0.4.0
## Fix
- fix transaction save point when depth is 1

## Add
- add `error::ClosedByDriver` error type
- add `pool::PoolBuilder::cache_size` for configuring the max size of statement cache of connection pool
- add `pool::Pool::config` method for obtaining postgres configuration of connection pool
- add `dev::ClientBorrow` trait for extending client type. It's used as super trait of `ClientBorrowMut`
- add `transaction::TransactionBuilder::begin_owned` method for specialized handling of transaction with owned client type

## Change
- rename `transaction::Transaction::bind` method to `Transaction::bind_dyn`
- rename `transaction::Transaction::bind_raw` method to `Transaction::bind` 
- switch to `tokio-uring-xitca` for `io-uring` feature. IO uring driver must run in it's runtime instead of original `tokio-uring`

## Remove
- remove `error::DriverDownReceiving` error type
- remove `dev::Query` and `dev::Prepare` traits. They are replaced by alternative `dev::ClientBorrow` trait

# 0.3.0
## Add
- add `StatementNamedQuery` which can be execute by `Pool`
- add `pool::CachedStatement` which can be cloned and function the same as normal `Statement` without the ability to cancel
- export `transaction::builder::IsolationLevel` for building transaction with specific level of isolation
- add default `Prepare`, `Query` impl for `&T` and `&mut T`
- add default `ClientBorrowMut` impl for `&mut T`
- add `nightly` crate feature

## Remove 
- remove `pipeline` module
- remove `dev::Encode::size_hint` method
- remove `bool` const generic type from `dev::Encode::encode` method
- remove `ExecuteMut` trait. It's role is replaced by `impl Execute<&mut C>`
- remove `transaction::Transaction::builder` API. `transaction::TransactionBuilder::new` is a replacement with less type infer required
- remove `error::AuthenticationError` type. It's error condition is covered by `error::ConfigError`

## Change
- `TransactionBuilder::begin` accepts wider range of types where `T: Prepare + ClientBorrowMut`. `Transaction`'s type param must be changed accordingly. e.g: `Transaction<&mut Client>`
- update to Rust editon 2024
- change `Prepare::_get_type` to accept plain async trait method 
- change `pool::Pool`'s dead connection detection lifecycle
- change `AsyncLendingIterator::try_collect_into` to mirror the public API of nightly Rust's `iter_collect_into` feature
- change `FromSqlExt` trait method to mirror `postgres_types::FromSql` trait behavior. For migration move paring logic to `FromSqlExt::from_sql_ext` method and null value logic to `FromSqlExt::from_sql_null_ext`
- move and rename `compat::StatementGuarded` type to `statement::StatementGuardedOwned` so it's not gated by `compat` feature

# 0.2.1
## Fix
- relax lifetime bound on various query types 

# 0.2.0
## Remove
- remove `prepare`, `query`, `execute`, `query_raw`, `execute_raw`, `query_simple` and `execute_simple` methods from all types. Leave only `Execute` trait family as sole API  
    ```rust
    use xitca_postgres::{Client, Execute, RowSimpleStream, RowStream, Statement};
    // create a named statement and execute it. on success returns a prepared statement
    let stmt: StatementGuarded<'_, Client> = Statement::named("SELECT 1").execute(&client).await?;
    // query with the prepared statement. on success returns an async row stream.
    let stream: RowStream<'_> = stmt.query(&client).await?;
    // query with raw string sql.
    let stream: RowSimpleStream<'_> = "SELECT 1; SELECT 1".query(&client).await?;
    // execute raw string sql.
    let row_affected: u64 = "SELECT 1; SELECT 1".execute(&client).await?;
    // execute sql file.
    let row_affected: u64 = std::path::Path::new("./foo.sql").execute(&client).await?;
    ```
- remove `Client::pipeline` and `Pool::pipeline`. `pipeline::Pipeline` type can be execute with `Execute::query` method
    
  remove `pipeline::Pipeline::query` and `pipeline::Pipeline` can be queried with `ExecuteMut::query_mut` method
    ```rust
    use xitca_postgres::Execute;
    // prepare statement and create a pipeline
    let stmt = Statement::named("SELECT 1", &[]).execute(&client).await?;
    let mut pipe = Pipeline::new();
    
    // use ExecuteMut trait to add query to pipeline
    use xitca_postgres::ExecuteMut;
    stmt.query_mut(&mut pipe)?;
    stmt.query_mut(&mut pipe)?;

    // use Execute trait to start pipeline query
    let pipe_stream = pipe.query(&client)?;
    ```
- remove `dev::AsParams` trait export. It's not needed for implementing `Query` trait anymore    

## Change
- query with parameter value arguments must be bind to it's `Statement` before calling `Execute` methods.
    ```rust
    use xitca_postgres::Execute;
    // prepare a statement.
    let stmt = Statement::named("SELECT * FROM users WHERE id = $1 AND age = $2", &[Type::INT4, Type::INT4]).execute(&client).await?;
    // bind statement to typed value and start query
    let stream = stmt.bind([9527, 42]).query(&client).await?;
    ```
- query without parameter value can be queried with `Statement` alone.
    ```rust
    use xitca_postgres::Execute;
    // prepare a statement.
    let stmt = Statement::named("SELECT * FROM users", &[]).execute(&client).await?;
    // statement have no value params and can be used for query.
    let stream = stmt.query(&client).await?;
    ```
- `AsyncLendingIterator` is no longer exported from crate's root path. use `iter::AsyncLendingIterator` instead
- `query::RowStreamOwned` and `row::RowOwned` are no longer behind `compat` crate feature anymore
- `statement::Statement::unnamed` must bind to value parameters with `bind` or `bind_dyn` before calling `Execute` methods.
    ```rust
    let stmt = Statement::unnamed("SELECT * FROM users WHERE id = $1", &[Type::INT4]);
    let row_stream = stmt.bind([9527]).query(&client).await?;
    ```
- `Query::_send_encode_query` method's return type is changed to `Result<(<S as Encode>::Output, Response), Error>`. Enabling further simplify of the surface level API at the cost of more internal complexity
- `Encode` trait implementation detail change
- `IntoStream` trait is renamed to `IntoResponse` with implementation detail change

## Add
- add `Execute`, `ExecuteMut`, `ExecuteBlocking` traits for extending query customization
- add `Prepare::_get_type_blocking`
- add `iter::AsyncLendingIteratorExt` for extending async iterator APIs
- add `statement::Statement::{bind, bind_dyn}` methods for binding value parameters to a prepared statement for query
- add `query::RowSimpleStreamOwned`
- add `error::DriverIoErrorMulti` type for outputting read and write IO errors at the same time

## Fix
- remove `Clone` trait impl from `Statement`. this is a bug where `Statement` type is not meant to be duplicateable by library user