Fix docs

README.md

@@ -148,40 +148,56 @@ 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.
 
-### "Nested" `beforeTemplateIsBaked` calls
+### Manual template creation
 
-In some cases, if you do extensive setup in your `beforeTemplateIsBaked` hook, you might want to obtain a separate, additional database within it if your application uses several databases for different purposes. This is possible by using the passed `beforeTemplateIsBaked` to your hook callback:
+In some cases, if you do extensive setup in your `beforeTemplateIsBaked` hook, you might want to obtain a separate, additional database within it if your application uses several databases for different purposes. This is possible by using the `manuallyBuildAdditionalTemplate()` function passed to your hook callback:
 
 ```ts
-type DatabaseParams = {
-  type: "foo" | "bar"
-}
+import test from "ava"
 
-const getTestServer = getTestPostgresDatabaseFactory<DatabaseParams>({
+const getTestDatabase = getTestPostgresDatabaseFactory<DatabaseParams>({
   beforeTemplateIsBaked: async ({
     params,
     connection: { pool },
-    beforeTemplateIsBaked,
+    manuallyBuildAdditionalTemplate,
   }) => {
-    if (params.type === "foo") {
-      await pool.query(`CREATE TABLE "foo" ("id" SERIAL PRIMARY KEY)`)
-      // Important: return early to avoid infinite loop
-      return
-    }
-
     await pool.query(`CREATE TABLE "bar" ("id" SERIAL PRIMARY KEY)`)
-    // This created database will be torn down at the end of the top-level `beforeTemplateIsBaked` call
-    const fooDatabase = await beforeTemplateIsBaked({
-      params: { type: "foo" },
-    })
 
-    // This works now
-    await fooDatabase.pool.query(`INSERT INTO "foo" DEFAULT VALUES`)
+    const fooTemplateBuilder = await manuallyBuildAdditionalTemplate()
+    await fooTemplateBuilder.connection.pool.query(
+      `CREATE TABLE "foo" ("id" SERIAL PRIMARY KEY)`
+    )
+    const { templateName: fooTemplateName } = await fooTemplateBuilder.finish()
+
+    return { fooTemplateName }
   },
 })
+
+test("foo", async (t) => {
+  const barDatabase = await getTestDatabase({ type: "bar" })
+
+  // the "bar" database has the "bar" table...
+  await t.notThrowsAsync(async () => {
+    await barDatabase.pool.query(`SELECT * FROM "bar"`)
+  })
+
+  // ...but not the "foo" table...
+  await t.throwsAsync(async () => {
+    await barDatabase.pool.query(`SELECT * FROM "foo"`)
+  })
+
+  // ...and we can obtain a separate database with the "foo" table
+  const fooDatabase = await getTestDatabase.fromTemplate(
+    t,
+    barDatabase.beforeTemplateIsBakedResult.fooTemplateName
+  )
+  await t.notThrowsAsync(async () => {
+    await fooDatabase.pool.query(`SELECT * FROM "foo"`)
+  })
+})
 ```
 
-Be very careful when using this to avoid infinite loops.
+Although it's not shown in the above example, because of `ava-postgres`'s automatic de-duping by parameter combinations, any returned template name is "linked" to the parameters passed to the `getTestDatabase()` function.
 
 ### Bind mounts & `exec`ing in the container
 

src/public-types.ts

@@ -92,6 +92,56 @@ export interface GetTestPostgresDatabaseFactoryOptions<
      * })
      * ```
      */
+
+    /**
+     * In some cases, if you do extensive setup in your `beforeTemplateIsBaked` hook, you might want to obtain a separate, additional database within it if your application uses several databases for different purposes.
+     *
+     * @example
+     * ```ts
+     * import test from "ava"
+     *
+     * const getTestDatabase = getTestPostgresDatabaseFactory<DatabaseParams>({
+     *   beforeTemplateIsBaked: async ({
+     *     params,
+     *     connection: { pool },
+     *     manuallyBuildAdditionalTemplate,
+     *   }) => {
+     *     await pool.query(`CREATE TABLE "bar" ("id" SERIAL PRIMARY KEY)`)
+     *
+     *     const fooTemplateBuilder = await manuallyBuildAdditionalTemplate()
+     *     await fooTemplateBuilder.connection.pool.query(
+     *       `CREATE TABLE "foo" ("id" SERIAL PRIMARY KEY)`
+     *     )
+     *     const { templateName: fooTemplateName } = await fooTemplateBuilder.finish()
+     *
+     *     return { fooTemplateName }
+     *   },
+     * })
+     *
+     * test("foo", async (t) => {
+     *   const barDatabase = await getTestDatabase({ type: "bar" })
+     *
+     *   // the "bar" database has the "bar" table...
+     *   await t.notThrowsAsync(async () => {
+     *     await barDatabase.pool.query(`SELECT * FROM "bar"`)
+     *   })
+     *
+     *   // ...but not the "foo" table...
+     *   await t.throwsAsync(async () => {
+     *     await barDatabase.pool.query(`SELECT * FROM "foo"`)
+     *   })
+     *
+     *   // ...and we can obtain a separate database with the "foo" table
+     *   const fooDatabase = await getTestDatabase.fromTemplate(
+     *     t,
+     *     barDatabase.beforeTemplateIsBakedResult.fooTemplateName
+     *   )
+     *   await t.notThrowsAsync(async () => {
+     *     await fooDatabase.pool.query(`SELECT * FROM "foo"`)
+     *   })
+     * })
+     * ```
+     */
     manuallyBuildAdditionalTemplate: () => Promise<{
       connection: ConnectionDetails
       finish: () => Promise<{ templateName: string }>

src/tests/hooks.test.ts

@@ -147,10 +147,10 @@ test("beforeTemplateIsBaked (result isn't serializable)", async (t) => {
   )
 })
 
-test("beforeTemplateIsBaked, get nested database", async (t) => {
+test("beforeTemplateIsBaked with manual template build", async (t) => {
   const getTestDatabase = getTestPostgresDatabaseFactory({
     postgresVersion: process.env.POSTGRES_VERSION,
-    workerDedupeKey: "beforeTemplateIsBakedHookNestedDatabase",
+    workerDedupeKey: "beforeTemplateIsBakedHookManualTemplateBuild",
     beforeTemplateIsBaked: async ({
       connection: { pool },
       manuallyBuildAdditionalTemplate,
@@ -178,7 +178,7 @@ test("beforeTemplateIsBaked, get nested database", async (t) => {
 
   await t.notThrowsAsync(async () => {
     await fooDatabase.pool.query('SELECT * FROM "foo"')
-  })
+  }, "foo table should exist on database manually created from template")
 
   await t.throwsAsync(async () => {
     await fooDatabase.pool.query('SELECT * FROM "bar"')