KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #typescript #codex #cli #claude-code #mcp #rust #deepseek-harness #ai-agent

postgrejs

★ 67 Open GitHub ↗

Professional PostgreSQL client for NodeJS

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<p align="center">¨
  <a href="https://postgrejs.panates.com/" target="blank">
    <img src="https://postgrejs.panates.com/img/postgrejs-header-block.png" width="800" alt="PostgreJS Logo" />
  </a>
</p>
  
[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![CI Tests][ci-test-image]][ci-test-url]
[![Test Coverage][coveralls-image]][coveralls-url]

PostgreJS is an enterprise-level PostgreSQL client for Node.js.
It is designed to provide a robust and efficient interface to PostgreSQL databases,
ensuring high performance and reliability for enterprise applications.
Written entirely in TypeScript, it leverages modern JavaScript features to deliver a seamless development experience.

## Library Overview

PostgreJS is a pure JavaScript library, meticulously crafted with TypeScript to offer a strictly typed, well-structured,
and highly maintainable codebase.
Key highlights include:

- **Language:** Pure modern JavaScript library.
- **Strictly Typed:** Completely written in TypeScript, offering strong typing and enhanced development experience.
- **Compatibility:** Works seamlessly with both CommonJS and ESM module systems, ensuring flexibility in various project setups.
- **Comprehensive Testing:** Rigorously tested to ensure stability and reliability in production environments.
- **Promise-Based API:** Asynchronous operations are handled with a Promise-based API, promoting clean and efficient asynchronous code.

## Features

- **Connection Management:** Supports both single connection and advanced pooling, providing scalability and efficient resource management.
- **Binary Wire Protocol:** Implements the full binary wire protocol for all PostgreSQL data types, ensuring robust and efficient data handling.
- **Prepared Statements:** Named prepared statements for optimized query execution.
- **Cursors:** Features fast double-link cache cursors for efficient data retrieval.
- **Notifications:**  High-level implementation for PostgreSQL notifications (LISTEN/NOTIFY), enabling real-time data updates.
- **Extensibility:** Extensible data-types and type mapping to accommodate custom requirements.
- **Parameter Binding:**  Bind parameters with OID mappings for precise and efficient query execution.
- **Array Handling:** Supports multidimensional arrays with fast binary encoding/decoding.
- **Performance Optimization:**  Low memory utilization and boosted performance through the use of shared buffers.
- **Authorization:** SSupports various password algorithms including Clear text, MD5, and SASL, ensuring secure authentication.
- **Flexible Data Retrieval:**  Can return both array and object rows to suit different data processing needs.
- **Resource Management:** Auto disposal of resources with the "using" syntax ([TC30 Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management)), ensuring efficient resource cleanup.

Whether you're building a simple application or a complex enterprise system,
PostgreJS provides the features and performance you need to succeed.
Explore the capabilities of the library and elevate your PostgreSQL integration to the next level.

## Installation

```bash
$ npm install postgrejs --save
```

## Documentation
Please read :small_orange_diamond: [DOCUMENTATION](https://postgrejs.panates.com/) :small_orange_diamond: for detailed usage.

## Example usage

### Establish a single connection, execute a simple query

```ts
import { Connection } from 'postgrejs';
// Create connection
const connection = new Connection('postgres://localhost');
// Connect to database server
await connection.connect();

// Execute query and fetch rows
const result = await connection.query(
    'select * from cities where name like $1',
    {params: ['%york%']});
const rows: any[] = result.rows;
// Do what ever you want with rows

// Disconnect from server
await connection.close(); 
```

### Establish a pooled connection, create a cursor
```ts
import { Pool } from 'postgrejs';

// Create connection pool
const db = new Pool({
    host: 'postgres://localhost',
    pool: {
       min: 1,
       max: 10,
       idleTimeoutMillis: 5000
    }
});

// Execute query and fetch cursor
const result = await db.query(
    'select * from cities where name like $1',
    {params: ['%york%'], cursor: true});

// Walk through the cursor, and do whatever you want with fetched rows
const cursor = result.cursor;
let row;
while ((row = await cursor.next())) {
  console.log(row);
}
// Close cursor, (Send connection back to the pool)
await cursor.close();

// Disconnect all connections and shutdown pool
await db.close(); 
```

### Using prepared statements
```ts
import { DataTypeOIDs } from 'postgrejs';

// .....
const statement = await connection.prepare( 
    'insert into my_table(id, name) values ($1, $2)', {
        paramTypes: [DataTypeOIDs.Int4, DataTypeOIDs.Varchar]
    });

for (let i = 0; i < 100; i++) {
    await statement.execute({params: [i, ('name' + i)]});
}
await statement.close(); // When you done, close the statement to relase resources
```

#### Check [DOCUMENTATION](https://postgrejs.panates.com/) for other examples.

## Type mappings
The table below lists builtin data type mappings.

| PosgtreSQL type | JS type     | Receive     | Send   | 
|-----------------|:------------|-------------|--------|
| bool            | boolean     | text,binary | binary | 
| int2            | number      | text,binary | binary | 
| int4            | number      | text,binary | binary | 
| int8            | BigInt      | text,binary | binary | 
| float4          | number      | text,binary | binary | 
| float8          | number      | text,binary | binary | 
| char            | string      | text,binary | binary | 
| bpchar          | string      | text,binary | binary | 
| varchar         | string      | text,binary | binary | 
| date            | Date        | text,binary | binary | 
| time            | Date        | text,binary | binary | 
| timestamp       | Date        | text,binary | binary | 
| timestamptz     | Date        | text,binary | binary | 
| oid             | number      | text,binary | binary | 
| bytea           | Buffer      | text,binary | binary | 
| uuid            | string      | text,binary | binary | 
| json            | object      | text,binary | binary | 
| jsonb           | object      | text,binary | binary | 
| xml             | string      | text,binary | binary | 
| point           | Point       | text,binary | binary | 
| circle          | Circle      | text,binary | binary | 
| lseg            | Rectangle   | text,binary | binary | 
| box             | Rectangle   | text,binary | binary | 
| int2Vector      | number[]    | text,binary | binary | 
| _bool           | boolean[]   | text,binary | binary | 
| _int2           | number[]    | text,binary | binary | 
| _int4           | number[]    | text,binary | binary | 
| _int8           | BigInt[]    | text,binary | binary | 
| _float4         | number[]    | text,binary | binary | 
| _float8         | number[]    | text,binary | binary | 
| _char           | string[]    | text,binary | binary | 
| _bpchar         | string[]    | text,binary | binary | 
| _varchar        | string[]    | text,binary | binary | 
| _date           | Date[]      | text,binary | binary | 
| _time           | Date[]      | text,binary | binary | 
| _timestamp      | Date[]      | text,binary | binary | 
| _timestamptz    | Date[]      | text,binary | binary | 
| _uuid           | string[]    | text,binary | binary | 
| _oid            | number[]    | text,binary | binary | 
| _bytea          | Buffer[]    | text,binary | binary | 
| _json           | object[]    | text,binary | binary | 
| _jsonb          | object[]    | text,binary | binary | 
| _xml            | string[]    | text,binary | binary | 
| _point          | Point[]     | text,binary | binary | 
| _circle         | Circle[]    | text,binary | binary | 
| _lseg           | Rectangle[] | text,binary | binary | 
| _box            | Rectangle[] | text,binary | binary | 
| _int2Vector     | number[][]  | text,binary | binary |

## Support
You can report bugs and discuss features on the [GitHub issues](https://github.com/panates/postgrejs/issues) page
When you open an issue please provide version of NodeJS and PostgreSQL server.

## Node Compatibility
- node >= 16.x
 
  
## License
PostgreJS is available under [MIT](LICENSE) license.

[npm-image]: https://img.shields.io/npm/v/postgrejs
[npm-url]: https://npmjs.org/package/postgrejs
[ci-test-image]: https://github.com/panates/postgrejs/actions/workflows/test.yml/badge.svg
[ci-test-url]: https://github.com/panates/postgrejs/actions/workflows/test.yml
[coveralls-image]: https://img.shields.io/coveralls/panates/postgrejs/master.svg
[coveralls-url]: https://coveralls.io/r/panates/postgrejs
[downloads-image]: https://img.shields.io/npm/dm/postgrejs.svg
[downloads-url]: https://npmjs.org/package/postgrejs
[gitter-image]: https://badges.gitter.im/panates/postgrejs.svg
[gitter-url]: https://gitter.im/panates/postgrejs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
[dependencies-image]: https://david-dm.org/panates/postgrejs/status.svg
[dependencies-url]:https://david-dm.org/panates/postgrejs
[devdependencies-image]: https://david-dm.org/panates/postgrejs/dev-status.svg
[devdependencies-url]:https://david-dm.org/panates/postgrejs?type=dev
[quality-image]: http://npm.packagequality.com/shield/postgrejs.png
[quality-url]: http://packagequality.com/#?package=postgrejs

postgrejs

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README