npm package: @superdev22/pgnx
Description: High-performance PostgreSQL driver for Node.js using libpqxx and N-API
Author: Lumos-Labs-HQ
Latest version: 2.3.1

# PGNX - High-Performance PostgreSQL Driver

[![npm version](https://img.shields.io/npm/v/pgnx.svg)](https://www.npmjs.com/package/pgnx)


[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

High-performance PostgreSQL driver for Node.js using libpqxx and N-API. Drop-in replacement for `pg` with 2-5x better performance.

## Features

- 🚀 2-5x faster than node-postgres
- 🔄 Connection pooling with health checks
- ⚡ Async operations with Promises
- 🎯 Prepared statements
- 📦 Query pipelining
- 🔔 LISTEN/NOTIFY support
- 🛡️ TypeScript definitions
- ♻️ Auto cleanup (5 min idle timeout)
- 🌍 Cross-platform (Linux, macOS, Windows)
- 📦 Prebuilt binaries included

## Installation

```bash
npm install pgnx
```

That's it! Prebuilt binaries included for Linux, macOS, and Windows. No dependencies needed!

## Quick Start

```javascript
const { Connection } = require('pgnx');

// Create connection
const conn = new Connection('postgresql://user:pass@localhost/db', 10);

// Query
const users = await conn.query('SELECT * FROM users WHERE age > $1', [18]);

// Prepared statements
conn.prepare('getUser', 'SELECT * FROM users WHERE id = $1');
const user = await conn.execute('getUser', [1]);

// Pipeline
const results = await conn.pipeline([
  'UPDATE users SET active = true WHERE id = 1',
  'UPDATE users SET active = true WHERE id = 2'
]);

// LISTEN/NOTIFY
conn.listen('events', (payload) => console.log('Event:', payload));

// Cleanup
conn.close();
```

## API

### `new Connection(connectionString, poolSize?)`
Create connection pool.
- `connectionString`: PostgreSQL connection string
- `poolSize`: Pool size (default: 10)

### `query(sql, params?): Promise<Array>`
Execute query with optional parameters.

### `prepare(name, sql): void`
Prepare named statement.

### `execute(name, params?): Promise<Array>`
Execute prepared statement.

### `pipeline(queries): Promise<Array<number>>`
Execute multiple queries, returns affected row counts.

### `listen(channel, callback): void`
Listen for notifications.

### `unlisten(channel): void`
Stop listening.

### `close(): void`
Close all connections.

## TypeScript

```typescript
import { Connection } from 'pgnx';

interface User {
  id: number;
  name: string;
}

const conn = new Connection('postgresql://localhost/db');
const users = await conn.query<User>('SELECT * FROM users');
```

## Performance

| Operation | pg | pgnx | Improvement |
|-----------|-----|------|-------------|
| Simple Query | 15ms | 6ms | 2.5x |
| Prepared Statement | 12ms | 5ms | 2.4x |
| Pipeline (3 queries) | 45ms | 18ms | 2.5x |

## Migration from pg

**Before:**
```javascript
const { Client } = require('pg');
const client = new Client('postgresql://localhost/db');
await client.connect();
const result = await client.query('SELECT * FROM users');
console.log(result.rows);
await client.end();
```

**After:**
```javascript
const { Connection } = require('pgnx');
const conn = new Connection('postgresql://localhost/db');
const users = await conn.query('SELECT * FROM users');
console.log(users);
conn.close();
```

## Requirements

- Node.js >= 18.0.0
- PostgreSQL server (for runtime connection)

No build tools or system dependencies required!

## License

Apache License 2.0

## Links

- [GitHub](https://github.com/Lumos-Labs-HQ/pgnx)
- [npm](https://www.npmjs.com/package/pgnx)
- [Issues](https://github.com/Lumos-Labs-HQ/pgnx/issues)