gem-hunter

deno-postgres

The documentation is available on the deno-postgres website.

Join the Discord as well! It's a good place to discuss bugs and features before opening issues.

// deno run --allow-net --allow-read mod.ts
import { Client } from "jsr:@db/postgres";

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();

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 deno-postgres approach version 1.0.

Although deno-postgres is reasonably stable and robust, it is a WIP, and we're still exploring the design. Expect some breaking changes as we reach version 1.0 and enhance the feature set. Please check the Releases for more info on breaking changes. Please reach out if there are any undocumented breaking changes.

Please file an issue with any problems with the driver. If you would like to help, please look at the issues as well. You can pick up one of them and try to implement it.

• 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 to run the linter and formatter locally

  • https://deno.land/
  • deno upgrade stable
  • dvm install stable && dvm use stable

• 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

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

To run the tests, run the following commands:

1. docker compose build tests
2. 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 temporary 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);
});

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
   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 here

2. Set the DENO_POSTGRES_DEVELOPMENT environmental variable to true, either by prepending it before the test command (on Linux) or setting it globally for 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.

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

When contributing to the repository, make sure to:

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 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 to be accepted

When publishing a new version, ensure that the version field in deno.json has been updated to match the new version.

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 - 2025 — Bartłomiej Iwańczuk, Steven Guerrero, Hector Ayala — All rights reserved.