Postgres

Author: cristianrgreco

docs/modules/postgresql.md

@@ -1,6 +1,4 @@
-# PostgreSQL Module
-
-[PostgreSQL](https://www.postgresql.org/) is a powerful, open source object-relational database system with over 30 years of active development that has earned it a strong reputation for reliability, feature robustness, and performance.
+# PostgreSQL
 
 ## Install
 
@@ -10,33 +8,46 @@ npm install @testcontainers/postgresql --save-dev
 
 ## Examples
 
+These examples use the following libraries:
+
+- [pg](https://www.npmjs.com/package/pg)
+
+        npm install pg
+        npm install @types/pg
+
+Choose an image from the [container registry](https://hub.docker.com/_/postgres) and substitute `IMAGE`.
+
+### Execute a query
+
 <!--codeinclude-->
-[Connect and execute query:](../../packages/modules/postgresql/src/postgresql-container.test.ts) inside_block:connect
+[](../../packages/modules/postgresql/src/postgresql-container.test.ts) inside_block:pgConnect
 <!--/codeinclude-->
 
+### Connect via URI
+
 <!--codeinclude-->
-[Connect and execute query using URI:](../../packages/modules/postgresql/src/postgresql-container.test.ts) inside_block:uriConnect
+[](../../packages/modules/postgresql/src/postgresql-container.test.ts) inside_block:pgUriConnect
 <!--/codeinclude-->
 
+### With database
+
 <!--codeinclude-->
-[Set database:](../../packages/modules/postgresql/src/postgresql-container.test.ts) inside_block:setDatabase
+[](../../packages/modules/postgresql/src/postgresql-container.test.ts) inside_block:pgSetDatabase
 <!--/codeinclude-->
 
+### With username
+
 <!--codeinclude-->
-[Set username:](../../packages/modules/postgresql/src/postgresql-container.test.ts) inside_block:setUsername
+[](../../packages/modules/postgresql/src/postgresql-container.test.ts) inside_block:pgSetUsername
 <!--/codeinclude-->
 
-### Using Snapshots
+### Snapshots
 
-This example shows the usage of the postgres module's Snapshot feature to give each test a clean database without having
-to recreate the database container on every test or run heavy scripts to clean your database. This makes the individual
-tests very modular, since they always run on a brand-new database.
-
-!!! tip
-    You should never pass the `"postgres"` system database as the container database name if you want to use snapshots. 
+!!! warning
+    You should never pass the `"postgres"` system database as the container database name if you want to use snapshots.
     The Snapshot logic requires dropping the connected database and using the system database to run commands, which will
     not work if the database for the container is set to `"postgres"`.
 
 <!--codeinclude-->
-[Test with a reusable Postgres container](../../packages/modules/postgresql/src/postgresql-container-snapshot.test.ts) inside_block:createAndRestoreFromSnapshot
-<!--/codeinclude-->
+[](../../packages/modules/postgresql/src/postgresql-container-snapshot.test.ts) inside_block:createAndRestoreFromSnapshot
+<!--/codeinclude-->

packages/modules/postgresql/src/postgresql-container-snapshot.test.ts

@@ -5,8 +5,8 @@ import { PostgreSqlContainer } from "./postgresql-container";
 const IMAGE = getImage(__dirname);
 
 describe("PostgreSqlContainer snapshot and restore", { timeout: 180_000 }, () => {
-  // createAndRestoreFromSnapshot {
   it("should create and restore from snapshot", async () => {
+    // createAndRestoreFromSnapshot {
     await using container = await new PostgreSqlContainer(IMAGE).start();
 
     // Connect to the database
@@ -58,8 +58,8 @@ describe("PostgreSqlContainer snapshot and restore", { timeout: 180_000 }, () =>
     expect(result.rows[0].name).toEqual("initial data");
 
     await client.end();
+    // }
   });
-  // }
 
   it("should use custom snapshot name", async () => {
     await using container = await new PostgreSqlContainer(IMAGE).start();

packages/modules/postgresql/src/postgresql-container.test.ts

@@ -5,8 +5,8 @@ import { PostgreSqlContainer } from "./postgresql-container";
 const IMAGE = getImage(__dirname);
 
 describe("PostgreSqlContainer", { timeout: 180_000 }, () => {
-  // connect {
   it("should connect and return a query result", async () => {
+    // pgConnect {
     await using container = await new PostgreSqlContainer(IMAGE).start();
 
     const client = new Client({
@@ -22,28 +22,29 @@ describe("PostgreSqlContainer", { timeout: 180_000 }, () => {
     expect(result.rows[0]).toEqual({ "?column?": 1 });
 
     await client.end();
+    // }
   });
-  // }
 
-  // uriConnect {
   it("should work with database URI", async () => {
+    // pgUriConnect {
     await using container = await new PostgreSqlContainer(IMAGE).start();
 
     const client = new Client({
       connectionString: container.getConnectionUri(),
     });
+    // }
     await client.connect();
 
     const result = await client.query("SELECT 1");
     expect(result.rows[0]).toEqual({ "?column?": 1 });
 
     await client.end();
   });
-  // }
 
-  // setDatabase {
   it("should set database", async () => {
+    // pgSetDatabase {
     await using container = await new PostgreSqlContainer(IMAGE).withDatabase("customDatabase").start();
+    // }
 
     const client = new Client({
       host: container.getHost(),
@@ -59,11 +60,11 @@ describe("PostgreSqlContainer", { timeout: 180_000 }, () => {
 
     await client.end();
   });
-  // }
 
-  // setUsername {
   it("should set username", async () => {
+    // pgSetUsername {
     await using container = await new PostgreSqlContainer(IMAGE).withUsername("customUsername").start();
+    // }
 
     const client = new Client({
       host: container.getHost(),
@@ -79,7 +80,6 @@ describe("PostgreSqlContainer", { timeout: 180_000 }, () => {
 
     await client.end();
   });
-  // }
 
   it("should work with restarted container", async () => {
     await using container = await new PostgreSqlContainer(IMAGE).start();