mirror of
https://github.com/brianc/node-postgres.git
synced 2025-12-08 20:16:25 +00:00
0c1629bea2
* Update docs - start * Add logo & discord * Start updating docs for esm style imports * Update docs with logo & info on pooling * Update more import statements --------- Co-authored-by: Brian Carlson <brian.carlson@getcruise.com>
77 lines
2.3 KiB
Plaintext
77 lines
2.3 KiB
Plaintext
---
|
|
title: pg.Cursor
|
|
slug: /apis/cursor
|
|
---
|
|
|
|
A cursor can be used to efficiently read through large result sets without loading the entire result-set into memory ahead of time. It's useful to simulate a 'streaming' style read of data, or exit early from a large result set. The cursor is passed to `client.query` and is dispatched internally in a way very similar to how normal queries are sent, but the API it presents for consuming the result set is different.
|
|
|
|
## install
|
|
|
|
```
|
|
$ npm install pg pg-cursor
|
|
```
|
|
|
|
## constructor
|
|
|
|
### `new Cursor(text: String, values: Any[][, config: CursorQueryConfig])`
|
|
|
|
Instantiates a new Cursor. A cursor is an instance of `Submittable` and should be passed directly to the `client.query` method.
|
|
|
|
```js
|
|
import { Pool } from 'pg'
|
|
import Cursor from 'pg-cursor'
|
|
|
|
const pool = new Pool()
|
|
const client = await pool.connect()
|
|
const text = 'SELECT * FROM my_large_table WHERE something > $1'
|
|
const values = [10]
|
|
|
|
const cursor = client.query(new Cursor(text, values))
|
|
|
|
const { rows } = await cursor.read(100)
|
|
console.log(rows.length) // 100 (unless the table has fewer than 100 rows)
|
|
client.release()
|
|
```
|
|
|
|
```ts
|
|
type CursorQueryConfig {
|
|
// by default rows come out as a key/value pair for each row
|
|
// pass the string 'array' here to receive rows as an array of values
|
|
rowMode?: string;
|
|
|
|
// custom type parsers just for this query result
|
|
types?: Types;
|
|
}
|
|
```
|
|
|
|
## read
|
|
|
|
### `cursor.read(rowCount: Number) => Promise<pg.Result>`
|
|
|
|
Read `rowCount` rows from the cursor instance. The callback will be called when the rows are available, loaded into memory, parsed, and converted to JavaScript types.
|
|
|
|
If the cursor has read to the end of the result sets all subsequent calls to cursor#read will return a 0 length array of rows. Calling `read` on a cursor that has read to the end.
|
|
|
|
Here is an example of reading to the end of a cursor:
|
|
|
|
```js
|
|
import { Pool } from 'pg'
|
|
import Cursor from 'pg-cursor'
|
|
|
|
const pool = new Pool()
|
|
const client = await pool.connect()
|
|
const cursor = client.query(new Cursor('select * from generate_series(0, 5)'))
|
|
|
|
let rows = await cursor.read(100)
|
|
assert(rows.length == 6)
|
|
|
|
rows = await cursor.read(100)
|
|
assert(rows.length == 0)
|
|
```
|
|
|
|
## close
|
|
|
|
### `cursor.close() => Promise<void>`
|
|
|
|
Used to close the cursor early. If you want to stop reading from the cursor before you get all of the rows returned, call this.
|