- v0.19.3Latest
- v0.19.2
- v0.19.1
- v0.19.0
- v0.18.1
- v.0.18.1
- v0.18.0
- v0.17.2
- ls
- v0.17.1
- v0.17.0
- v0.16.1
- v0.16.0
- v0.15.0
- v0.14.3
- v0.14.2
- v0.14.1
- v0.14.0
- v0.13.0
- v0.12.0
- v0.11.3
- 0.11.3
- v0.11.2
- v0.11.1
- 0.10.0
- v0.11.0
- v0.10.0
- v0.9.0
- v0.8.0
- v0.7.1
- v0.7.0
- v0.6.0
- v0.5.0
- v0.4.6
- v0.4.5
- v0.4.4
- v0.4.3
- v0.4.2
- v0.4.1
- v0.4.0
- v0.3.11
- v0.3.10
- v0.3.9
- v0.3.8
- v0.3.7
- v0.3.6
- v0.3.5
- v0.3.4
- v0.3.3
- v0.3.2
- v0.3.1
- v0.3.0
- v0.2.0
- v0.1.2
- v0.1.1
- v0.1
deno-postgres
A lightweight PostgreSQL driver for Deno focused on developer experience.
deno-postgres
is being developed inspired by the excellent work of
node-postgres and
pq.
Example
// deno run --allow-net --allow-read mod.ts
import { Client } from "https://deno.land/x/postgres/mod.ts";
const client = new Client({
user: "user",
database: "test",
hostname: "localhost",
port: 5432,
});
await client.connect();
{
const result = await client.queryArray("SELECT ID, NAME FROM PEOPLE");
console.log(result.rows); // [[1, 'Carlos'], [2, 'John'], ...]
}
{
const result = await client
.queryArray`SELECT ID, NAME FROM PEOPLE WHERE ID = ${1}`;
console.log(result.rows); // [[1, 'Carlos']]
}
{
const result = await client.queryObject("SELECT ID, NAME FROM PEOPLE");
console.log(result.rows); // [{id: 1, name: 'Carlos'}, {id: 2, name: 'Johnru'}, ...]
}
{
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 https://deno-postgres.com/
Documentation
The documentation is available on the deno-postgres website https://deno-postgres.com/
Join the Discord as well! It’s a good place to discuss bugs and features before opening issues.
Contributing
Prerequisites
You must have
docker
anddocker-compose
installed on your machineYou 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.40.0
dvm install 1.40.0 && dvm use 1.40.0
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.
To run the tests, run the following commands:
docker-compose build tests
docker-compose run tests
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 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
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);`);
const result = await client.queryObject<{ x: number }>({
text: `SELECT X FROM MY_TEST`,
fields: ["x"],
});
assertEquals(result.rows[0].x, 1);
});
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 a local testing environment, as shown in the following steps:
Start the development databases using the Docker service with the command
docker-compose up postgres_clear postgres_md5 postgres_scram
Though using the detach (-d
) option is recommended, this will make the databases run in the background unless you use docker itself to stop them. You can find more info about this hereSet the
DENO_POSTGRES_DEVELOPMENT
environmental variable to true, either by prepending it before the test command (on Linux) or setting it globally for all environmentsThe
DENO_POSTGRES_DEVELOPMENT
variable will tell the testing pipeline to use the local testing settings specified intests/config.json
instead of the CI settings.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 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 the repository, make sure to:
- All features and fixes must have an open issue to be discussed
- All public interfaces must be typed and have a corresponding JSDoc block explaining their usage
- All code must pass the format and lint checks enforced by
deno fmt
anddeno 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 - All features and fixes must have a corresponding test added to be accepted
Maintainers guidelines
When publishing a new version, ensure that the version
field in deno.json
has been updated to match the new version.
License
There are substantial parts of this library based on other libraries. They have preserved their individual licenses and copyrights.
Everything is licensed under the MIT License.
All additional work is copyright 2018 - 2024 — Bartłomiej Iwańczuk, Steven Guerrero, Hector Ayala — All rights reserved.