complete docs

Author: Hexilee

Cargo.toml

@@ -10,6 +10,10 @@ readme = "../README.md"
 keywords = ["database", "postgres", "postgresql", "sql", "async"]
 categories = ["database"]
 
+[package.metadata.docs.rs]
+features = ["docs"]
+rustdoc-args = ["--cfg", "feature=\"docs\""]
+
 [badges]
 codecov = { repository = "Hexilee/async-postgres" }
 
@@ -32,6 +36,7 @@ postgres-native-tls = "0.3.0"
 native-tls = "0.2.4"
 
 [features]
+docs = ["all-types"]
 all-types = [
     "with-bit-vec-0_6",
     "with-chrono-0_4",

README.md

@@ -15,13 +15,68 @@
 </div>
 <br>
 
-This crate is an out-of-the-box wrapper of [tokio-postgres](https://crates.io/crates/tokio-postgres).
+This crate is a wrapper of [tokio-postgres](https://crates.io/crates/tokio-postgres).
 
 ### Pros
 
-- runtime-independent, can be used on any async runtime.
-- build-in tls support, based on [tokio-rustls](https://github.com/quininer/tokio-rustls).
+Runtime-independent, can be used on any async runtime.
+
+### Usage
+
+Almost the same with tokio-postgres.
+
+- TCP or UDS
+
+```rust
+use async_postgres::connect;
+use std::error::Error;
+use async_std::task::spawn;
+
+async fn play() -> Result<(), Box<dyn Error>> {
+    let url = "host=localhost user=postgres";
+    let (client, conn) = connect(url.parse()?).await?;
+    spawn(conn);
+    let row = client.query_one("SELECT * FROM user WHERE id=$1", &[&0]).await?;
+    let value: &str = row.get(0);
+    println!("value: {}", value);
+    Ok(())
+}
+```
+
+- TLS
+
+```rust
+use async_postgres::connect_tls;
+use native_tls::{Certificate, TlsConnector};
+use postgres_native_tls::MakeTlsConnector;
+use std::fs;
+use std::error::Error;
+use async_std::task::spawn;
+
+async fn play() -> Result<(), Box<dyn Error>> {
+    let cert = fs::read("database_cert.pem")?;
+    let cert = Certificate::from_pem(&cert)?;
+    let connector = TlsConnector::builder()
+        .add_root_certificate(cert)
+        .build()?;
+    let connector = MakeTlsConnector::new(connector);
+    let url = "host=localhost user=postgres sslmode=require";
+    let (client, conn) = connect_tls(url.parse()?, connector).await?;
+    spawn(conn);
+    let row = client.query_one("SELECT * FROM user WHERE id=$1", &[&0]).await?;
+    let value: &str = row.get(0);
+    println!("value: {}", value);
+    Ok(())
+}
+```
 
 ### Performance
 
+Almost the same with tokio-postgres, 
+you can see a live benchmark [here](https://github.com/Hexilee/async-postgres/actions?query=workflow%3ABenchmark).
+
 ### Develop
+
+Run tests need a running postgres server and environment variables:
+- `TCP_URL="postgresql:///<db>?host=<tcp host>&port=<port>&user=<user>&password=<passwd>"`
+- `UDS_URL="postgresql:///<db>?host=<postgres uds dir>&port=<port>&user=<user>&password=<passwd>"`

src/connect.rs

@@ -99,7 +99,7 @@ async fn connect_socket(
         Host::Tcp(tcp) => {
             let fut = TcpStream::connect((tcp.as_str(), port));
             let socket = timeout(dur, fut).await?;
-            // socket.set_nodelay(true)?;
+            socket.set_nodelay(true)?;
             Ok(socket.into())
         }
     }

src/lib.rs

@@ -1,11 +1,12 @@
-//! A runtime-independent, asynchronous PostgreSQL client.
-
-#![warn(missing_docs)]
+#![cfg_attr(feature = "docs", feature(external_doc))]
+#![cfg_attr(feature = "docs", doc(include = "../README.md"))]
+#![cfg_attr(feature = "docs", warn(missing_docs))]
 
 #[doc(inline)]
 pub use connect::connect_tls;
 #[doc(inline)]
 pub use socket::Socket;
+#[doc(no_inline)]
 pub use tokio_postgres::*;
 
 use std::io;
@@ -16,7 +17,6 @@ use tokio_postgres::{Client, Connection};
 ///
 /// ```rust
 /// use async_postgres::connect;
-///
 /// use std::error::Error;
 /// use async_std::task::spawn;
 ///

tests/benchmark.rs

@@ -25,7 +25,7 @@ fn benchmark() -> Result<(), Box<dyn Error>> {
     println!("      - tcp: {} us/q", elapsed.as_micros() / queries);
     let elapsed = tokio_rr.block_on(tokio_runtime(&uds_url))?;
     println!("      - uds: {} us/q", elapsed.as_micros() / queries);
-    println!("  - tokio_postgres on tokio runtime:");
+    println!("  - tokio-postgres on tokio runtime:");
     let elapsed = tokio_rr.block_on(tokio_postgres(&tcp_url))?;
     println!("      - tcp: {} us/q", elapsed.as_micros() / queries);
     let elapsed = tokio_rr.block_on(tokio_postgres(&uds_url))?;