Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/panates/postgrejs

Professional PostgreSQL client for NodeJS
https://github.com/panates/postgrejs

client connector driver javascript nodejs pg postgres postgresql typescript

Last synced: 6 days ago
JSON representation

Professional PostgreSQL client for NodeJS

Awesome Lists containing this project

README 

        


¨

  

    PostgreJS Logo

  



  

[![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