@freemework/sql.postgres/README.md

Postgres SQL Facade library of the Freemework Project.

# Freemework's PostgreSQL Facade
[![npm version badge](https://img.shields.io/npm/v/@freemework/sql.postgres.svg)](https://www.npmjs.com/package/@freemework/sql.postgres)
[![downloads badge](https://img.shields.io/npm/dm/@freemework/sql.postgres.svg)](https://www.npmjs.org/package/@freemework/sql.postgres)
[![commit activity badge](https://img.shields.io/github/commit-activity/m/freemework/sql.postgres)](https://github.com/freemework/sql.postgres/pulse)
[![last commit badge](https://img.shields.io/github/last-commit/freemework/freemework)](https://github.com/freemework/freemework/graphs/commit-activity)

## Version table
```sql
CREATE TABLE "__dbVersion" (
	"version" VARCHAR(64) NOT NULL PRIMARY KEY,
	"utc_deployed_at" TIMESTAMP WITHOUT TIME ZONE NOT NULL DEFAULT (now() AT TIME ZONE 'utc'),
	"log" TEXT NOT NULL
)
```
NOTE: Name of table may be overridden via migration's opts

## Connection URL

### Format

```
postgres://[${user}[:${password}]]@${host}[:${port}]/${databaseName}[?app=${applicationName}&schema=${defaultSchema}]
postgres+ssl://[${user}[:${password}]]@${host}[:${port}]/${databaseName}[?app=${applicationName}&schema=${defaultSchema}]
```
TBD: Example URL for unix socket

### Examples

#### Localhost

```
postgres://localhost:5432/postgres
```

#### Remote PostgreSQL server `my_pg_host` with SSL prefer mode (no certificate validation, just for encryption)

```
postgres+ssl://my_pg_host:5432/postgres
```

Note: For full SSL mode you need to pass `opts.ssl` programmatically. Passing certificates via URL does not supported.

## Development Notes

1. Make sure your have PostgreSQL instance or launch it as Docker container
    ```shell
    docker run --name postgres --rm --interactive --publish 5432:5432 theanurin/devel.postgres-13
    ```
1. Launch tests via VSCode's launch configuration or via command line
    ```shell
    TEST_DB_URL="postgres://devadmin@localhost:5432/devdb" npm run test
    ```
1. Look inside DB to see SQL objects generated by tests. For the purpose you may use VSCode's plugins provided by [Matheus Teixeira](https://marketplace.visualstudio.com/publishers/mtxr): [SQLTools](https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools) and [SQLTools PostgreSQL/Cockroach Driver](https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools-driver-pg)