diff --git a/README.md b/README.md index b0e64a75..30f81e3d 100644 --- a/README.md +++ b/README.md @@ -1151,6 +1151,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. diff --git a/types/index.d.ts b/types/index.d.ts index ab797ee4..d76cb3b2 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -683,6 +683,8 @@ declare namespace postgres { file(path: string | Buffer | URL | number, options?: { cache?: boolean | undefined } | undefined): PendingQuery; file(path: string | Buffer | URL | number, args: (ParameterOrJSON)[], options?: { cache?: boolean | undefined } | undefined): PendingQuery; json(value: JSONValue): Parameter; + + reserve(): Promise> } interface UnsafeQueryOptions { @@ -699,6 +701,10 @@ declare namespace postgres { prepare(name: string): Promise>; } + + interface ReservedSql = {}> extends Sql { + release(): void; + } } export = postgres;