Improve docs

README.md

@@ -97,6 +97,57 @@ test("foo bar", async (t) => {
 
 ## Advanced Usage
 
+### Postgres container de-duping
+
+In rare cases, you may want to spawn more than one Postgres container.
+
+Internally, this library uses an AVA "shared worker". A shared worker is a singleton shared with the entire running test suite, and so one `ava-postgres` shared worker maps to exactly one Postgres container.
+
+To spawn separate shared workers and thus additional Postgres containers, you have two options:
+
+**Specify different version strings for the `postgresVersion` option in the factory function**:
+
+```ts
+const getTestPostgresDatabase = getTestPostgresDatabaseFactory({
+  postgresVersion: "14",
+})
+```
+
+Each unique version will map to a unique shared worker.
+
+**Set the `workerDedupeKey` option in the factory function**:
+
+```ts
+const getTestPostgresDatabase = getTestPostgresDatabaseFactory({
+  workerDedupeKey: "foo",
+})
+```
+
+Each unique key will map to a unique shared worker.
+
+### Database de-duping
+
+By default, `ava-postgres` will create a new database for each test. If you want to share a database between tests, you can use the `databaseDedupeKey` option:
+
+```ts
+import test from "ava"
+const getTestPostgresDatabase = getTestPostgresDatabaseFactory({})
+
+test("foo", async (t) => {
+  const connection1 = await getTestPostgresDatabase(t, null, {
+    databaseDedupeKey: "foo",
+  })
+  const connection2 = await getTestPostgresDatabase(t, null, {
+    databaseDedupeKey: "foo",
+  })
+  t.is(connection1.database, connection2.database)
+})
+```
+
+This works across the entire test suite.
+
+Note that if unique parameters are passed to the `beforeTemplateIsBaked` (`null` in the above example), separate databases will still be created.
+
 ### Bind mounts & `exec`ing in the container
 
 `ava-postgres` uses [testcontainers](https://www.npmjs.com/package/testcontainers) under the hood to manage the Postgres container.

src/public-types.ts

@@ -48,7 +48,10 @@ export interface GetTestPostgresDatabaseFactoryOptions<
   }
 
   /**
-   * Test workers will be de-duped by this key. You probably don't need to set this.
+   * In rare cases, you may want to spawn more than one Postgres container.
+   * Internally, this library uses an AVA "shared worker". A shared worker is a singleton shared with the entire running test suite, and so one `ava-postgres` shared worker maps to exactly one Postgres container.
+   * To spawn separate shared workers and thus additional Postgres containers, you can specify a custom key here.
+   * Each unique key will map to a unique shared worker/unique Postgres container.
    */
   workerDedupeKey?: string
   beforeTemplateIsBaked?: (options: {
@@ -64,7 +67,26 @@ export interface GetTestPostgresDatabaseResult extends ConnectionDetails {
 
 export type GetTestPostgresDatabaseOptions = {
   /**
-   * If `getTestPostgresDatabase()` is called multiple times with the same `key` and `params`, the same database is guaranteed to be returned.
+   * By default, `ava-postgres` will create a new database for each test. If you want to share a database between tests, you can use the `databaseDedupeKey` option.
+   * This works across the entire test suite.
+   *
+   * Note that if unique parameters are passed to the `beforeTemplateIsBaked` (`null` in the above example), separate databases will still be created.
+   * @example
+   * ```ts
+   * import test from "ava"
+   *
+   * const getTestPostgresDatabase = getTestPostgresDatabaseFactory({})
+   *
+   * test("foo", async (t) => {
+   *   const connection1 = await getTestPostgresDatabase(t, null, {
+   *     databaseDedupeKey: "foo",
+   *   })
+   *   const connection2 = await getTestPostgresDatabase(t, null, {
+   *     databaseDedupeKey: "foo",
+   *   })
+   *   t.is(connection1.database, connection2.database)
+   * })
+   * ```
    */
   databaseDedupeKey?: string
 }