# common_sql_postgresql

PostgreSQL driver for [`common_sql`](../common_sql), implemented with [`pog`](https://hex.pm/packages/pog).

**For usage documentation, examples, and the full API reference, see the [`common_sql` README](../common_sql/README.md).**

This package exposes a single `driver()` function. Add it alongside `common_sql`:

```sh
gleam add common_sql common_sql_postgresql
```

```gleam
import common_sql as sql
import common_sql_postgresql

pub fn main() {
  let driver = common_sql_postgresql.driver()
  use conn <- sql.with_connection(driver, "postgres://user:pass@localhost/mydb")
  // see common_sql README for full examples
}
```

## SQL placeholders

Both `sql.Sql("… WHERE id = $1")` and `sql.Portable("… WHERE id = $1")` work with this driver — PostgreSQL natively uses `$1, $2, …` so no conversion is applied either way.

## PostgreSQL connection URL

```
postgres://[user[:password]@][host[:port]][/database][?options]
```

```gleam
"postgres://localhost/mydb"                          // local, no auth
"postgres://alice:secret@db.example.com:5432/mydb"  // with credentials
"postgres://localhost/mydb?sslmode=verify-full"      // with SSL
```

## Notes

- `pog` manages connections as an OTP pool. Call `driver()` once at startup — not in a loop.
- `common_sql.close/2` is a no-op for this driver. Use `pog.supervised/1` to manage the pool lifecycle via a supervision tree.

## Development

Integration tests require a live PostgreSQL instance on `localhost:5432` (user `postgres`, password `postgres`, database `testdb`). A Docker one-liner:

```sh
docker run --rm --name test_pg -e POSTGRES_PASSWORD=postgres -e POSTGRES_USER=postgres \
  -e POSTGRES_DB=testdb -p 5432:5432 -d postgres:16-alpine
```

```sh
gleam test   # run the integration tests
gleam build  # compile the package
```

## Licence

MIT