add docs and types for .reserve() (#667)

Author: tim-smart

README.md

@@ -79,6 +79,7 @@ async function insertUser({ name, age }) {
 * [Teardown / Cleanup](#teardown--cleanup)
 * [Error handling](#error-handling)
 * [TypeScript support](#typescript-support)
+* [Reserving connections](#reserving-connections)
 * [Changelog](./CHANGELOG.md)
 
 
@@ -1151,6 +1152,22 @@ prexit(async () => {
 })
 ```
 
+## Reserving connections
+
+### `await sql.reserve()`
+
+The `reserve` method pulls out a connection from the pool, and returns a client that wraps the single connection. This can be used for running queries on an isolated connection.
+
+```ts
+const reserved = await sql.reserve()
+await reserved`select * from users`
+await reserved.release()
+```
+
+### `reserved.release()`
+
+Once you have finished with the reserved connection, call `release` to add it back to the pool.
+
 ## Error handling
 
 Errors are all thrown to related queries and never globally. Errors coming from database itself are always in the [native Postgres format](https://www.postgresql.org/docs/current/errcodes-appendix.html), and the same goes for any [Node.js errors](https://nodejs.org/api/errors.html#errors_common_system_errors) eg. coming from the underlying connection.

types/index.d.ts

@@ -683,6 +683,8 @@ declare namespace postgres {
     file<T extends readonly any[] = Row[]>(path: string | Buffer | URL | number, options?: { cache?: boolean | undefined } | undefined): PendingQuery<T>;
     file<T extends readonly any[] = Row[]>(path: string | Buffer | URL | number, args: (ParameterOrJSON<TTypes[keyof TTypes]>)[], options?: { cache?: boolean | undefined } | undefined): PendingQuery<T>;
     json(value: JSONValue): Parameter;
+
+    reserve(): Promise<ReservedSql<TTypes>>
   }
 
   interface UnsafeQueryOptions {
@@ -699,6 +701,10 @@ declare namespace postgres {
 
     prepare<T>(name: string): Promise<UnwrapPromiseArray<T>>;
   }
+
+  interface ReservedSql<TTypes extends Record<string, unknown> = {}> extends Sql<TTypes> {
+    release(): void;
+  }
 }
 
 export = postgres;