Update README.md (prepared transactions) (porsager#637)

paulovieira · web-flow · commit 4265251ca63c · 2023-09-12T10:02:41.000+02:00
* Update README.md (prepared statements)

- correct typo
- add link to the official docs
- change the subsection name to "PREPARE TRANSACTION" instead of "PREPARE" (because "PREPARE" is more associated with "prepared statements")

One thing that is still a bit confusing in this section is the final sentence "Do note that you can often achieve...". It seems like it is referring to the "PREPARE" subsection, but in reality it is referring to the initial "BEGIN / COMMIT" subsection, no?

* Update README.md

- moved "Do note that you can often achieve the same result" to the first subsection
- added a link to a question in dba.stackexchange.com that shows how to do it
- in the insert and update example with dynamic columns, clarify that the columns can be given as an array

* Update README.md

- remove example in stackoverflow
diff --git a/README.md b/README.md
@@ -176,14 +176,23 @@ const user = {
   age: 68
 }
 
-sql`
+await sql`
   insert into users ${
     sql(user, 'name', 'age')
   }
 `
 
 // Which results in:
 insert into users ("name", "age") values ($1, $2)
+
+// The columns can also be given with an array
+const columns = ['name', 'age']
+
+await sql`
+  insert into users ${
+    sql(user, columns)
+  }
+`
 ```
 
 **You can omit column names and simply execute `sql(user)` to get all the fields from the object as columns**. Be careful not to allow users to supply columns that you do not want to be inserted.
@@ -223,7 +232,7 @@ const user = {
   age: 68
 }
 
-sql`
+await sql`
   update users set ${
     sql(user, 'name', 'age')
   }
@@ -232,6 +241,16 @@ sql`
 
 // Which results in:
 update users set "name" = $1, "age" = $2 where user_id = $3
+
+// The columns can also be given with an array
+const columns = ['name', 'age']
+
+await sql`
+  update users set ${
+    sql(user, columns)
+  }
+  where user_id = ${ user.id }
+`
 ```
 
 ### Multiple updates in one query
@@ -596,6 +615,8 @@ const [user, account] = await 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.
+
 It's also possible to pipeline the requests in a transaction if needed by returning an array with queries from the callback function like this:
 
 ```js
@@ -641,9 +662,9 @@ sql.begin('read write', async sql => {
 ```
 
 
-#### PREPARE `await sql.prepare([name]) -> fn()`
+#### PREPARE TRANSACTION `await sql.prepare([name]) -> fn()`
 
-Indicates that the transactions should be prepared using the `PREPARED TRANASCTION [NAME]` statement
+Indicates that the transactions should be prepared using the [`PREPARE TRANSACTION [NAME]`](https://www.postgresql.org/docs/current/sql-prepare-transaction.html) statement
 instead of being committed.
 
 ```js
@@ -660,8 +681,6 @@ sql.begin('read write', 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.
-
 ## Data Transformation
 
 Postgres.js allows for transformation of the data passed to or returned from a query by using the `transform` option.
