https://github.com/treeform/pg

Very simple PostgreSQL async api for nim.
https://github.com/treeform/pg

Last synced: about 1 month ago
JSON representation

Very simple PostgreSQL async api for nim.

• Host: GitHub
• URL: https://github.com/treeform/pg
• Owner: treeform
• License: mit
• Created: 2018-11-19T23:27:23.000Z (almost 6 years ago)
• Default Branch: master
• Last Pushed: 2023-11-03T18:25:34.000Z (10 months ago)
• Last Synced: 2024-05-03T00:15:48.778Z (4 months ago)
• Language: Nim
• Size: 14.6 KB
• Stars: 37
• Watchers: 4
• Forks: 8
• Open Issues: 5
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# Very simple PostgreSQL async pool api for nim

`nimble install pg`

![Github Actions](https://github.com/treeform/pg/workflows/Github%20Actions/badge.svg)

[API reference](https://nimdocs.com/treeform/pg)

This library has no dependencies other than the Nim standard libarary.

## About

To open a pool with 10 connections simply use:

```nim

let pg = newAsyncPool("localhost", "user", "password", "dbname", 10)

```

By using a connection pool, 10 connections are opened and when your application makes a query a free connection is taking from the pool. Otherwise your query will wait for a free connection to become available. This allows your application to run any number of queries at once. By default PostgreSQL will accept 100 connections. PostgreSQL can run multiple queries at once as well but they will start impacting each other especially if they read or write to same tables, or you have run out of CPU cores.

You can open a single connection with `db_postgres`'s api:

```nim

let pg = open("localhost", "user", "password", "dbname")

```

But you have to be careful to not run more then one query at once on the connection.

## Get rows

If running in `{.async.}` function use `await`:

```nim

let rows = await pg.rows(sql"SELECT 1")

for row in rows:

  echo row

```

Otherwies you can use `waitFor`:

```nim

let rows = waitFor pg.rows(sql"SELECT 1")

```

You can add multiple paramaters that will be escaped:

```nim

let rows = await pg.rows(sql"SELECT ?, pg_sleep(1);", @["foo"])

```

## Run query without results

You can also run query by ignoring results in `{.async.}` function use `await`:

```nim

await pg.exec(sql"UPDATE TABLE foo SET a=1")

```

## Concurrency:

Run 10 queries at once:

```nim

let pool = newAsyncPool("localhost", "", "", "test", 2)

var futures = newSeq[Future[seq[Row]]]()

for i in 0..<20:

  futures.add pool.rows(sql"SELECT ?, pg_sleep(1);", @[$i])

for f in futures:

  var res = await f

echo res

```

Run query but don't care about the results or when it will finish:

```nim

asyncCheck pg.exec(sql"UPDATE TABLE foo SET a=1")

```