Improve README with common questions on PGO

README.md

@@ -38,7 +38,7 @@ pub fn main() {
 
   // Run the query against the PostgreSQL database
   // The int `1` is given as a parameter
-  let assert Ok(response) = 
+  let assert Ok(response) =
     pgo.execute(sql, db, [pgo.int(1)], return_type)
 
   // And then do something with the returned results
@@ -57,6 +57,47 @@ pub fn main() {
 gleam add gleam_pgo
 ```
 
+## Support of connection URI
+
+Configuring a Postgres connection is done by using `Config` type in `gleam/pgo`.
+To facilitate connection, and to provide easy integration with the rest of the
+Postgres ecosystem, `gleam_pgo` provides handling of
+[connection URI as defined by Postgres](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS).
+Shape of connection URI is `postgresql://[username:password@][host:port][/dbname][?query]`.
+Call `gleam/pgo.url_config` with your connection URI, and in case it's correct
+against the Postgres standard, your `Config` will be automatically generated!
+
+Here's an example, using [`envoy`](https://github.com/lpil/envoy) to read the
+connection URI from the environment.
+
+```gleam
+import envoy
+import gleam/pgo
+
+/// Read the DATABASE_URL environment variable.
+/// Generate the pgo.Config from that database URL.
+/// Finally, connect to database.
+pub fn read_connection_uri() -> Result(pgo.Connection, Nil) {
+  use database_url <- result.try(envoy.get("DATABASE_URL"))
+  use config <- result.try(pgo.url_config(database_url))
+  Ok(pgo.connect(config))
+}
+```
+
+## About JSON
+
+In Postgres, you can define a type `json` or `jsonb`. Such a type can be query
+in SQL, but Postgres returns it a simple string, and accepts it as a simple string!
+When writing or reading a JSON, you can simply use
+`pgo.text(json.to_string(my_json))` and `dynamic.string` to respectively write
+and read them!
+
+## Rows as maps
+
+By default, `pgo` will return every selected value from your query as a tuple.
+In case you want a different output, you can activate `rows_as_maps` in `Config`.
+Once activated, every returned rows will take the form of a `Dict`.
+
 ## Atom generation
 
 Creating a connection pool with the `pgo.connect` function dynamically generates

src/gleam/pgo.gleam

@@ -22,7 +22,7 @@ pub type Config {
     user: String,
     /// Password for the user.
     password: Option(String),
-    /// (default: false): Whether to use SSL or not.
+    /// (default: False): Whether to use SSL or not.
     ssl: Bool,
     /// (default: []): List of 2-tuples, where key and value must be binary
     /// strings. You can include any Postgres connection parameter here, such as
@@ -40,14 +40,14 @@ pub type Config {
     /// (default: 1000): The database is pinged every idle_interval when the
     /// connection is idle.
     idle_interval: Int,
-    /// trace (default: false): pgo is instrumented with [OpenCensus][1] and
+    /// trace (default: False): pgo is instrumented with [OpenCensus][1] and
     /// when this option is true a span will be created (if sampled).
     ///
     /// [1]: https://opencensus.io/
     trace: Bool,
-    /// Which internet protocol to use for this connection
+    /// (default: Ipv4) Which internet protocol to use for this connection
     ip_version: IpVersion,
-    /// By default, PGO will return a n-tuple, in the order of the query.
+    /// (default: False) By default, PGO will return a n-tuple, in the order of the query.
     /// By setting `rows_as_map` to `True`, the result will be `Dict`.
     rows_as_map: Bool,
   )