Skip to content

Commit 88e4a97

Browse files
committed
Fix #5 - Add connection pool description
1 parent bc549b0 commit 88e4a97

File tree

1 file changed

+14
-2
lines changed

1 file changed

+14
-2
lines changed

README.md

+14-2
Original file line numberDiff line numberDiff line change
@@ -234,7 +234,7 @@ const [{ json }] = await sql`
234234

235235
## File query `sql.file(path, [args], [options]) -> Promise`
236236

237-
Using an `sql` file for a query. The contents will be cached in memory so that the file is only read once.
237+
Using an `.sql` file for a query. The contents will be cached in memory so that the file is only read once.
238238

239239
```js
240240

@@ -367,6 +367,18 @@ prexit(async () => {
367367

368368
```
369369

370+
## The Connection Pool
371+
372+
Connections are created lazily once a query is created. This means that simply doing const `sql = postgres(...)` won't have any effect other than instantiating a new `sql` instance.
373+
374+
> No connection will be made until a query is made.
375+
376+
This means that we get a much simpler story for error handling and reconnections. Queries will be sent over the wire immediately on the next available connection in the pool. Connections are automatically taken out of the pool if you start a transaction using `sql.begin()`, and automatically returned to the pool once your transaction is done.
377+
378+
Any query which was already sent over the wire will be rejected if the connection is lost. It'll automatically defer to the error handling you have for that query, and since connections are lazy it'll automatically try to reconnect the next time a query is made. The benefit of this is no weird generic "onerror" handler that tries to get things back to normal, and also simpler application code since you don't have to handle errors out of context.
379+
380+
There are no guarantees about queries executing in order unless using a transaction with `sql.begin()` or setting `max: 1`. Of course doing a series of queries, one awaiting the other will work as expected, but that's just due to the nature of js async/promise handling, so it's not necessary for this library to be concerned with ordering.
381+
370382
<details><summary><code>sql.unsafe</code> - Advanced unsafe use cases</summary>
371383

372384
### Unsafe queries `sql.unsafe(query, [args], [options]) -> promise`
@@ -382,7 +394,7 @@ sql.unsafe('select ' + danger + ' from users where id = ' + dragons)
382394

383395
## Errors
384396

385-
Errors are all thrown to related queries and never globally. Errors coming from Postgres 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.
397+
Errors are all thrown to related queries and never globally. Errors coming from PostgreSQL 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.
386398

387399
There are also the following errors specifically for this library.
388400

0 commit comments

Comments
 (0)