@nuvix/pg/README.md

PostgreSQL integration for Nuvix

# Nuvix PostgreSQL Library

**Nuvix PG Lib** - A high-performance PostgreSQL library with a fully featured Query Builder. Inspired by Knex.js but with extra 🔥.

## Features

- Query Builder that feels like home (yes, it's from Knex, don't ask how 🤫)
- Supports dynamic JSON-based schema management
- Built-in Role-Based Access Control (RBAC) with **Row-Level Security (RLS)** and **Column-Level Security (CLS)**
- Computed fields with security rules
- Event system using **LISTEN / NOTIFY** & Redis Pub/Sub
- Supports both **Managed** and **Unmanaged** schema modes
- Full TypeScript support (because we know you love types)

---

## Installation

```sh
npm install @nuvix/pg
```

or if you're a yarn enjoyer:

```sh
yarn add @nuvix/pg
```

---

## Usage

### Connecting to DB

```ts
import { DataSource } from "@nuvix/pg";
import { Pool } from "pg";

const pool = new Pool({
  host: "localhost",
  user: "postgres",
  password: "password",
  database: "nuvix_db",
});

const db = new DataSource(pool);
```

### Query Builder

```ts
const users = await db
  .table("users")
  .select("id", "name", "email")
  .where("status", "active");

console.log(users);
```

### Insert Data

```ts
await db.table("users").insert({ name: "John Doe", email: "john@example.com" });
```

### Update Data

```ts
await db.table("users").where("id", 1).update({ status: "inactive" });
```

### Delete Data

```ts
await db.table("users").where("id", 1).delete();
```

### Raw Queries (for when you feel like living on the edge)

```ts
await db.raw("SELECT * FROM users WHERE status = ?", ["active"]);
```

---

## Event System

Listen to database changes in real-time:

```ts
db.listen("user_created", (payload) => {
  console.log("New user:", payload);
});
```

---

## Schema Management

Managed schema with JSON-based structure:

```ts
await db.createTable({
  name: "users",
  schema: "auth",
  columns: {
    id: { type: "uuid", primary: true },
    name: { type: "string", required: true },
    email: { type: "string", unique: true },
  },
  rls: true,
  $permissions: ["read(user:00000)"],
});
```

---

## Why Use This?

- Because raw SQL is too mainstream
- Because we got **real** security (RLS + CLS)
- Because you like your queries builder-style but don't want to use Knex.js directly (we got you 😉)
- Because we **copied Knex but made it better**

---

## License

BSD 3-Clause (yes, you can use this in your billion-dollar startup, just don't blame us if you mess up your queries)