Readme updates (porsager#223)

ericdrobinson · web-flow · commit 9cec5be67c58 · 2021-09-07T10:39:40.000+02:00
* Add warning about quotation marks with interpolation

* Improve documentation for custom types

Provide explanations for fields and hints as to where to locate the `oid` values.
diff --git a/README.md b/README.md
@@ -187,6 +187,8 @@ All the public API is typed. Also, TypeScript support is still in beta. Feel fre
 
 Parameters are automatically inferred and handled by Postgres so that SQL injection isn't possible. No special handling is necessary, simply use JS tagged template literals as usual.
 
+Be careful with quotation marks here. Because Postgres infers the types, you don't need to wrap your interpolated parameters in quotes like `'${name}'`. In fact, this will cause an error because the tagged template replaces `${name}` with `$1` in the query string, leaving Postgres to do the interpolation. If you wrap that in a string, Postgres will see `'$1'` and interpret it as a string as opposed to a parameter.
+
 ```js
 
 let search = 'Mur'
@@ -531,20 +533,32 @@ sql.begin(async sql => {
 
 Do note that you can often achieve the same result using [`WITH` queries (Common Table Expressions)](https://www.postgresql.org/docs/current/queries-with.html) instead of using transactions.
 
-## Types
+## Custom Types
 
-You can add ergonomic support for custom types, or simply pass an object with a `{ type, value }` signature that contains the Postgres `oid` for the type and the correctly serialized value.
+You can add ergonomic support for custom types, or simply pass an object with a `{ type, value }` signature that contains the Postgres `oid` for the type and the correctly serialized value. _(`oid` values for types can be found in the `pg_catalog.pg_types` table.)_
 
 Adding Query helpers is the recommended approach which can be done like this:
 
 ```js
 
-const sql = sql({
+const sql = postgres({
   types: {
     rect: {
+      /**
+       * The pg_types oid to pass to the db along with the serialized value.
+       */
       to        : 1337,
+      /**
+       * An array of pg_types oids to handle when parsing values coming from the db.
+       */
       from      : [1337],
+      /**
+       * Function that transform values before sending them to the db.
+       */
       serialize : ({ x, y, width, height }) => [x, y, width, height],
+      /**
+       * Function that transforms values coming from the db.
+       */
       parse     : ([x, y, width, height]) => { x, y, width, height }
     }
   }
