Skip to content

Commit 519575a

Browse files
porsagerporsager
committed
build
1 parent 8b8a133 commit 519575a

File tree

7 files changed

+57
-13
lines changed

7 files changed

+57
-13
lines changed

‎cf/src/connection.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -131,7 +131,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
131131
try {
132132
x = options.socket
133133
? (await Promise.resolve(options.socket(options)))
134-
: net.Socket()
134+
: new net.Socket()
135135
} catch (e) {
136136
error(e)
137137
return

‎cjs/src/connection.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
129129
try {
130130
x = options.socket
131131
? (await Promise.resolve(options.socket(options)))
132-
: net.Socket()
132+
: new net.Socket()
133133
} catch (e) {
134134
error(e)
135135
return

‎cjs/tests/index.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -2352,7 +2352,7 @@ t('Custom socket', {}, async() => {
23522352
let result
23532353
const sql = postgres({
23542354
socket: () => new Promise((resolve, reject) => {
2355-
const socket = net.Socket()
2355+
const socket = new net.Socket()
23562356
socket.connect(5432)
23572357
socket.once('data', x => result = x[0])
23582358
socket.on('error', reject)

‎deno/README.md

+46-8
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ async function insertUser({ name, age }) {
7575
* [Teardown / Cleanup](#teardown--cleanup)
7676
* [Error handling](#error-handling)
7777
* [TypeScript support](#typescript-support)
78+
* [Reserving connections](#reserving-connections)
7879
* [Changelog](./CHANGELOG.md)
7980

8081

@@ -171,14 +172,23 @@ const user = {
171172
age: 68
172173
}
173174

174-
sql`
175+
await sql`
175176
insert into users ${
176177
sql(user, 'name', 'age')
177178
}
178179
`
179180

180181
// Which results in:
181182
insert into users ("name", "age") values ($1, $2)
183+
184+
// The columns can also be given with an array
185+
const columns = ['name', 'age']
186+
187+
await sql`
188+
insert into users ${
189+
sql(user, columns)
190+
}
191+
`
182192
```
183193

184194
**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.
@@ -218,7 +228,7 @@ const user = {
218228
age: 68
219229
}
220230

221-
sql`
231+
await sql`
222232
update users set ${
223233
sql(user, 'name', 'age')
224234
}
@@ -227,10 +237,20 @@ sql`
227237

228238
// Which results in:
229239
update users set "name" = $1, "age" = $2 where user_id = $3
240+
241+
// The columns can also be given with an array
242+
const columns = ['name', 'age']
243+
244+
await sql`
245+
update users set ${
246+
sql(user, columns)
247+
}
248+
where user_id = ${ user.id }
249+
`
230250
```
231251

232252
### Multiple updates in one query
233-
It's possible to create multiple udpates in a single query. It's necessary to use arrays intead of objects to ensure the order of the items so that these correspond with the column names.
253+
To create multiple updates in a single query, it is necessary to use arrays instead of objects to ensure that the order of the items correspond with the column names.
234254
```js
235255
const users = [
236256
[1, 'John', 34],
@@ -575,6 +595,7 @@ const [user, account] = await sql.begin(async sql => {
575595
) values (
576596
'Murray'
577597
)
598+
returning *
578599
`
579600

580601
const [account] = await sql`
@@ -583,12 +604,15 @@ const [user, account] = await sql.begin(async sql => {
583604
) values (
584605
${ user.user_id }
585606
)
607+
returning *
586608
`
587609

588610
return [user, account]
589611
})
590612
```
591613

614+
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.
615+
592616
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:
593617

594618
```js
@@ -634,9 +658,9 @@ sql.begin('read write', async sql => {
634658
```
635659

636660

637-
#### PREPARE `await sql.prepare([name]) -> fn()`
661+
#### PREPARE TRANSACTION `await sql.prepare([name]) -> fn()`
638662

639-
Indicates that the transactions should be prepared using the `PREPARED TRANASCTION [NAME]` statement
663+
Indicates that the transactions should be prepared using the [`PREPARE TRANSACTION [NAME]`](https://www.postgresql.org/docs/current/sql-prepare-transaction.html) statement
640664
instead of being committed.
641665

642666
```js
@@ -653,8 +677,6 @@ sql.begin('read write', async sql => {
653677
})
654678
```
655679

656-
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.
657-
658680
## Data Transformation
659681

660682
Postgres.js allows for transformation of the data passed to or returned from a query by using the `transform` option.
@@ -937,7 +959,7 @@ const sql = postgres('postgres://username:password@host:port/database', {
937959
connect_timeout : 30, // Connect timeout in seconds
938960
prepare : true, // Automatic creation of prepared statements
939961
types : [], // Array of custom types, see more below
940-
onnotice : fn, // Defaults to console.log
962+
onnotice : fn, // Default console.log, set false to silence NOTICE
941963
onparameter : fn, // (key, value) when server param change
942964
debug : fn, // Is called with (connection, query, params, types)
943965
socket : fn, // fn returning custom socket to use
@@ -1147,6 +1169,22 @@ prexit(async () => {
11471169
})
11481170
```
11491171

1172+
## Reserving connections
1173+
1174+
### `await sql.reserve()`
1175+
1176+
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.
1177+
1178+
```ts
1179+
const reserved = await sql.reserve()
1180+
await reserved`select * from users`
1181+
await reserved.release()
1182+
```
1183+
1184+
### `reserved.release()`
1185+
1186+
Once you have finished with the reserved connection, call `release` to add it back to the pool.
1187+
11501188
## Error handling
11511189

11521190
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.

‎deno/src/connection.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
132132
try {
133133
x = options.socket
134134
? (await Promise.resolve(options.socket(options)))
135-
: net.Socket()
135+
: new net.Socket()
136136
} catch (e) {
137137
error(e)
138138
return

‎deno/tests/index.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -2354,7 +2354,7 @@ t('Custom socket', {}, async() => {
23542354
let result
23552355
const sql = postgres({
23562356
socket: () => new Promise((resolve, reject) => {
2357-
const socket = net.Socket()
2357+
const socket = new net.Socket()
23582358
socket.connect(5432)
23592359
socket.once('data', x => result = x[0])
23602360
socket.on('error', reject)

‎deno/types/index.d.ts

+6
Original file line numberDiff line numberDiff line change
@@ -685,6 +685,8 @@ declare namespace postgres {
685685
file<T extends readonly any[] = Row[]>(path: string | Buffer | URL | number, options?: { cache?: boolean | undefined } | undefined): PendingQuery<T>;
686686
file<T extends readonly any[] = Row[]>(path: string | Buffer | URL | number, args: (ParameterOrJSON<TTypes[keyof TTypes]>)[], options?: { cache?: boolean | undefined } | undefined): PendingQuery<T>;
687687
json(value: JSONValue): Parameter;
688+
689+
reserve(): Promise<ReservedSql<TTypes>>
688690
}
689691

690692
interface UnsafeQueryOptions {
@@ -701,6 +703,10 @@ declare namespace postgres {
701703

702704
prepare<T>(name: string): Promise<UnwrapPromiseArray<T>>;
703705
}
706+
707+
interface ReservedSql<TTypes extends Record<string, unknown> = {}> extends Sql<TTypes> {
708+
release(): void;
709+
}
704710
}
705711

706712
export = postgres;

0 commit comments

Comments
 (0)