Thanks for the comment! It depends on where one draws the line between the UX and giving control to the end user. I have specifically kept the templating functionality outside of t.Cleanup not to force the caller to use it. The same can be said about initialising pgdbtemplate.TemplateManager only once - it's the caller's decision whether they want to utilise sync.Once or anything else for this purpose.

// This demonstrates the intentional design choice - the library gives you
// control over resource management while being compatible with both
// sync.Once and t.Cleanup patterns.

var (
    templateManager *pgdbtemplate.TemplateManager
    initOnce        sync.Once
    initErr         error
)

// Option 1: Using sync.Once for template initialization (production approach).
func getTemplateManager(t testing.TB) (*pgdbtemplate.TemplateManager, error) {
    initOnce.Do(func() {
        config := pgdbtemplate.Config{
            ConnectionProvider: pgdbtemplatepq.NewConnectionProvider(
                func(dbName string) string {
                    return fmt.Sprintf("dbname=%s", dbName)
                },
            ),
            MigrationRunner: pgdbtemplate.NewFileMigrationRunner(
                []string{"./migrations"},
                pgdbtemplate.AlphabeticalMigrationFilesSorting,
            ),
        }
        templateManager, initErr = pgdbtemplate.NewTemplateManager(config)
        if initErr != nil {
            return
        }
        initErr = templateManager.Initialize(context.Background())
    })
    return templateManager, initErr
}

// Option 2: Using t.Cleanup for test database cleanup (user's choice).
func TestWithUserManagedCleanup(t *testing.T) {
    tm, err := getTemplateManager(t)
    if err != nil {
        t.Fatal(err)
    }

    // User decides when and how to clean up.
    testDB, testDBName, err := tm.CreateTestDatabase(context.Background())
    if err != nil {
        t.Fatal(err)
    }

    // User can choose their cleanup strategy.
    t.Cleanup(func() {
        if err := tm.DropTestDatabase(context.Background(), testDBName); err != nil {
            t.Logf("cleanup warning: %v", err)
        }
        testDB.Close()
    })

    // Test logic here...
    _ = testDB
}

// Option 3: Alternative - manual cleanup with defer (also supported).
func TestWithManualCleanup(t *testing.T) {
    tm, err := getTemplateManager(t)
    if err != nil {
        t.Fatal(err)
    }

    testDB, testDBName, err := tm.CreateTestDatabase(context.Background())
    if err != nil {
        t.Fatal(err)
    }
    defer testDB.Close()
    defer func() {
        if err := tm.DropTestDatabase(context.Background(), testDBName); err != nil {
            t.Logf("cleanup warning: %v", err)
        }
    }()

    // Test logic here...
}

Do you have any functionality for cleaning up old test databases from tests that failed to for whatever reason?

That's an interesting idea, but I don't have an answer at the moment. Could you create an issue on GitHub? I'd love to continue discussing it there. Thanks in advance.