quickpostgres/README.md

An easy, beginner-friendly PostgreSQL database wrapper similar to quick.db.

# [Quickpostgres](https://npmjs.com/package/quickpostgres)

[![Test](https://github.com/GodderE2D/quickpostgres/actions/workflows/test.yml/badge.svg)](https://github.com/GodderE2D/quickpostgres/actions/workflows/test.yml)
[![NPM Publish (Release)](https://github.com/GodderE2D/quickpostgres/actions/workflows/publish.yml/badge.svg)](https://github.com/GodderE2D/quickpostgres/actions/workflows/publish.yml)
[![NPM Publish (Dev)](https://github.com/GodderE2D/quickpostgres/actions/workflows/publish-dev.yml/badge.svg)](https://github.com/GodderE2D/quickpostgres/actions/workflows/publish-dev.yml)

An easy, beginner-friendly [PostgreSQL](https://www.postgresql.org/) database wrapper similar to [quick.db](https://github.com/lorencerri/quick.db).

## Features

- Near identical syntax to [quick.db](https://github.com/lorencerri/quick.db)
- Never worry about constant database corruptions again
- Fully flexible, uses [pg](https://github.com/brianc/node-postgres) internally
- Relies on [ES6 promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) (`async`/`await`, `.then()`)

If you don't know about [quick.db](https://github.com/lorencerri/quick.db), quickpostgres also has:

- **Persistent storage** - all data is stored on your PostgreSQL database
- **Easy to setup** - All you need is a PostgreSQL database to setup
- **Beginner friendly** - Use simple syntax with dot notation
- **No learning curve** - 0 learning curve if you're coming from [quick.db](https://github.com/lorencerri/quick.db) or [quickmongo](https://github.com/DevSnowflake/quickmongo)

## Installation

You can easily install quickpostgres using your preferred package manager.

```bash
npm install quickpostgres
# or
yarn add quickpostgres
# or
pnpm add quickpostgres
```

## Requirements

- Node.js 14 or above
- A PostgreSQL database

## Usage

Quickpostgres has similar (if not almost identical) syntax to [quick.db](https://github.com/lorencerri/quick.db). You can refer to their [documentation](https://quickdb.js.org/) if you are getting stuck.

> Note: Quickpostgres is built on top of promises, meaning you need to resolve them first using `.then()` or `await` to get their returned data.

```js
// Import quickpostgres
const { Client } = require("quickpostgres");

// Create a new client using the default values on localhost
const dbUrl = "postgresql://postgres:<password>@localhost:5432/postgres";
const db = new Client(dbUrl);

(async () => {
  // Connect to your client
  await db.connect();

  // Setting an object in the database:
  await db.set("userInfo", { difficulty: "Easy" });
  // => { difficulty: "Easy" }

  // Pushing an element to an array (that doesn't exist yet) in an object:
  await db.push("userInfo.items", "Sword");
  // => { difficulty: "Easy", items: ["Sword"] }

  // Adding to a number (that doesn't exist yet) in an object:
  await db.add("userInfo.balance", 500);
  // => { difficulty: "Easy", items: ["Sword"], balance: 500 }

  // Repeating previous examples:
  await db.push("userInfo.items", "Watch");
  // => { difficulty: "Easy", items: ["Sword", "Watch"], balance: 500 }
  await db.add("userInfo.balance", 500);
  // => { difficulty: "Easy", items: ["Sword", "Watch"], balance: 1000 }

  // Fetching individual properties
  await db.get("userInfo.balance"); // => 1000
  await db.get("userInfo.items"); // ["Sword", "Watch"]

  // End the database connection
  await db.end();
})();
```

## Support

For now, please use [GitHub discussions](https://github.com/GodderE2D/quickpostgres/discussions) if you need any support.

I may consider opening a Discord support server soon, but this is not guranteed.

## Contributing

You must adhere to the [code of conduct](https://github.com/GodderE2D/quickpostgres/blob/main/.github/CODE_OF_CONDUCT.md) when interacting within the quickpostgres repository.

If you spot a bug or you have a feature request, please open a [GitHub issue](https://github.com/GodderE2D/quickpostgres/issues), or if you'd like to write some code, you can open a [pull request](https://github.com/GodderE2D/quickpostgres/pulls).

If you spot a security vulnerability, please [contact me](mailto:main@godder.xyz).

## Notes

- Some users consider [quick.db](https://github.com/lorencerri/quick.db) non-suitable in the long term, reason being it uses [SQLite](https://www.sqlite.org/index.html), and is not easily scalable. However, since quickpostgres uses [PostgreSQL](https://www.postgresql.org/), one of the best production-grade database system out there, quickpostgres is suitable for production usage, in terms of performance.
- Quickpostgres is meant for beginners, and uses a JSON-feeling database. If you want to use the full advantages of [PostgreSQL](https://www.postgresql.org/), we highly recommend you switching to something else.

## License

[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)