Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@bombillazo
bombillazo authored Feb 7, 2024
1 parent d0bd5ca commit c7aac91
Showing 1 changed file with 47 additions and 51 deletions.
98 changes: 47 additions & 51 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@
[![Documentation](https://img.shields.io/github/v/release/denodrivers/postgres?color=yellow&label=Documentation&logo=deno&style=flat-square)](https://doc.deno.land/https/deno.land/x/postgres/mod.ts)
[![License](https://img.shields.io/github/license/denodrivers/postgres?color=yellowgreen&label=License&style=flat-square)](LICENSE)

A lightweight PostgreSQL driver for Deno focused on user experience
A lightweight PostgreSQL driver for Deno focused on user experience.

`deno-postgres` is being developed based on excellent work of
`deno-postgres` is being developed inspired by the excellent work of
[node-postgres](https://github.com/brianc/node-postgres) and
[pq](https://github.com/lib/pq).

Expand All @@ -32,8 +32,8 @@ await client.connect();
}

{
const result = await client
.queryArray`SELECT ID, NAME FROM PEOPLE WHERE ID = ${1}`;
const result =
await client.queryArray`SELECT ID, NAME FROM PEOPLE WHERE ID = ${1}`;
console.log(result.rows); // [[1, 'Carlos']]
}

Expand All @@ -43,50 +43,52 @@ await client.connect();
}

{
const result = await client
.queryObject`SELECT ID, NAME FROM PEOPLE WHERE ID = ${1}`;
const result =
await client.queryObject`SELECT ID, NAME FROM PEOPLE WHERE ID = ${1}`;
console.log(result.rows); // [{id: 1, name: 'Carlos'}]
}

await client.end();
```

For more examples visit the documentation available at
For more examples, visit the documentation available at
[https://deno-postgres.com/](https://deno-postgres.com/)

## Documentation

The documentation is available on the deno-postgres website
[https://deno-postgres.com/](https://deno-postgres.com/)

Join me on [Discord](https://discord.gg/HEdTCvZUSf) as well! It's a good place
to discuss bugs and features before opening issues
Join the [Discord](https://discord.gg/HEdTCvZUSf) as well! It's a good place
to discuss bugs and features before opening issues.

## Contributing

### Prerequisites

- You must have `docker` and `docker-compose` installed in your machine
- You must have `docker` and `docker-compose` installed on your machine

- https://docs.docker.com/get-docker/
- https://docs.docker.com/compose/install/

- You don't need `deno` installed in your machine to run the tests, since it
will be installed in the Docker container when you build it. However you will
need it in order to run the linter and formatter locally
- You don't need `deno` installed in your machine to run the tests since it
will be installed in the Docker container when you build it. However, you will
need it to run the linter and formatter locally

- https://deno.land/
- `deno upgrade --version 1.7.1`
- `dvm install 1.7.1 && dvm use 1.7.1`

- You don't need to install Postgres locally in your machine in order to test
- You don't need to install Postgres locally on your machine to test
the library, it will run as a service in the Docker container when you build
it

### Running the tests

The tests are found under the `./tests` folder, and they are based on query
result assertions
result assertions.

In order to run the tests run the following commands
To run the tests, run the following commands:

1. `docker-compose build tests`
2. `docker-compose run tests`
Expand All @@ -95,20 +97,16 @@ The build step will check linting and formatting as well and report it to the
command line

It is recommended that you don't rely on any previously initialized data for
your tests, instead of that create all the data you need at the moment of
your tests instead create all the data you need at the moment of
running the tests

For example, the following test will create a temporal table that will disappear
once the test has been completed

```ts
Deno.test("INSERT works correctly", async () => {
await client.queryArray(
`CREATE TEMP TABLE MY_TEST (X INTEGER);`,
);
await client.queryArray(
`INSERT INTO MY_TEST (X) VALUES (1);`,
);
await client.queryArray(`CREATE TEMP TABLE MY_TEST (X INTEGER);`);
await client.queryArray(`INSERT INTO MY_TEST (X) VALUES (1);`);
const result = await client.queryObject<{ x: number }>({
text: `SELECT X FROM MY_TEST`,
fields: ["x"],
Expand All @@ -119,8 +117,8 @@ Deno.test("INSERT works correctly", async () => {

### Setting up an advanced development environment

More advanced features such as the Deno inspector, test and permission
filtering, database inspection and test code lens can be achieved by setting up
More advanced features, such as the Deno inspector, test, and permission
filtering, database inspection, and test code lens can be achieved by setting up
a local testing environment, as shown in the following steps:

1. Start the development databases using the Docker service with the command\
Expand All @@ -134,44 +132,43 @@ a local testing environment, as shown in the following steps:
all environments

The `DENO_POSTGRES_DEVELOPMENT` variable will tell the testing pipeline to
use the local testing settings specified in `tests/config.json`, instead of
the CI settings
use the local testing settings specified in `tests/config.json` instead of
the CI settings.

3. Run the tests manually by using the command\
`deno test -A`

## Deno compatibility

Due to breaking changes introduced in the unstable APIs `deno-postgres` uses,
there has been some fragmentation regarding what versions of Deno can be used
alongside the library

This situation will become more stable as `std` and `deno-postgres` approach 1.0

| Deno version | Min driver version | Max driver version |
| ----------------------------------------------------- | ------------------ | ------------------ |
| 1.8.x | 0.5.0 | 0.10.0 |
| 1.9.0 | 0.11.0 | 0.11.1 |
| 1.9.1 and up | 0.11.2 | 0.11.3 |
| 1.11.0 and up | 0.12.0 | 0.12.0 |
| 1.14.0 and up | 0.13.0 | 0.13.0 |
| 1.15.0 | 0.13.0 | |
| 1.16.0 | 0.14.0 | 0.14.3 |
| 1.17.0 | 0.15.0 | |
| 1.40.0 | 0.17.2 | |
| This module is available on JSR starting from 0.17.2. | | |
alongside the driver.

This situation will stabilize as `std` and `deno-postgres` approach version 1.0.

| Deno version | Min driver version | Max driver version | Note |
| ------------- | ------------------ | ------------------ | -------------------- |
| 1.8.x | 0.5.0 | 0.10.0 | |
| 1.9.0 | 0.11.0 | 0.11.1 | |
| 1.9.1 and up | 0.11.2 | 0.11.3 | |
| 1.11.0 and up | 0.12.0 | 0.12.0 | |
| 1.14.0 and up | 0.13.0 | 0.13.0 | |
| 1.16.0 | 0.14.0 | 0.14.3 | |
| 1.17.0 | 0.15.0 | 0.17.1 | |
| 1.40.0 | 0.17.2 | | Now available on JSR |

## Contributing guidelines

When contributing to repository make sure to:
When contributing to the repository, make sure to:

1. All features and fixes must have an open issue in order to be discussed
2. All public interfaces must be typed and have a corresponding JS block
1. All features and fixes must have an open issue to be discussed
2. All public interfaces must be typed and have a corresponding JSDoc block
explaining their usage
3. All code must pass the format and lint checks enforced by `deno fmt` and
`deno lint` respectively. The build will not pass the tests if these
conditions are not met. Ignore rules will be accepted in the code base when
`deno lint` respectively. The build will only pass the tests if these
conditions are met. Ignore rules will be accepted in the code base when
their respective justification is given in a comment
4. All features and fixes must have a corresponding test added in order to be
4. All features and fixes must have a corresponding test added to be
accepted

## Maintainers guidelines
Expand All @@ -186,5 +183,4 @@ preserved their individual licenses and copyrights.

Everything is licensed under the MIT License.

All additional work is copyright 2018 - 2022 — Bartłomiej Iwańczuk and Steven
Guerrero — All rights reserved.
All additional work is copyright 2018 - 2022 — Bartłomiej Iwańczuk and Steven Guerrero — All rights reserved.

0 comments on commit c7aac91

Please sign in to comment.