chore: add postgres template caching for tests (#15336)

This PR is the first in a series aimed at closing
[#15109](https://github.com/coder/coder/issues/15109).

### Changes

- **Template Database Creation:**  
`dbtestutil.Open` now has the ability to create a template database if
none is provided via `DB_FROM`. The template database’s name is derived
from a hash of the migration files, ensuring that it can be reused
across tests and is automatically updated whenever migrations change.

- **Optimized Database Handling:**  
Previously, `dbtestutil.Open` would spin up a new container for each
test when `DB_FROM` was unset. Now, it first checks for an active
PostgreSQL instance on `localhost:5432`. If none is found, it creates a
single container that remains available for subsequent tests,
eliminating repeated container startups.

These changes address the long individual test times (10+ seconds)
reported by some users, likely due to the time Docker took to start and
complete migrations.

coderd/database/dbtestutil/postgres_test.go

@@ -11,25 +11,19 @@ import (
 	"go.uber.org/goleak"
 
 	"github.com/coder/coder/v2/coderd/database/dbtestutil"
+	"github.com/coder/coder/v2/coderd/database/migrations"
 )
 
 func TestMain(m *testing.M) {
 	goleak.VerifyTestMain(m)
 }
 
-// nolint:paralleltest
-func TestPostgres(t *testing.T) {
-	// postgres.Open() seems to be creating race conditions when run in parallel.
-	// t.Parallel()
+func TestOpen(t *testing.T) {
+	t.Parallel()
 
-	if testing.Short() {
-		t.SkipNow()
-		return
-	}
-
-	connect, closePg, err := dbtestutil.Open()
+	connect, err := dbtestutil.Open(t)
 	require.NoError(t, err)
-	defer closePg()
+
 	db, err := sql.Open("postgres", connect)
 	require.NoError(t, err)
 	err = db.Ping()
@@ -37,3 +31,74 @@ func TestPostgres(t *testing.T) {
 	err = db.Close()
 	require.NoError(t, err)
 }
+
+func TestOpen_InvalidDBFrom(t *testing.T) {
+	t.Parallel()
+
+	_, err := dbtestutil.Open(t, dbtestutil.WithDBFrom("__invalid__"))
+	require.Error(t, err)
+	require.ErrorContains(t, err, "template database")
+	require.ErrorContains(t, err, "does not exist")
+}
+
+func TestOpen_ValidDBFrom(t *testing.T) {
+	t.Parallel()
+
+	// first check if we can create a new template db
+	dsn, err := dbtestutil.Open(t, dbtestutil.WithDBFrom(""))
+	require.NoError(t, err)
+
+	db, err := sql.Open("postgres", dsn)
+	require.NoError(t, err)
+	t.Cleanup(func() {
+		require.NoError(t, db.Close())
+	})
+
+	err = db.Ping()
+	require.NoError(t, err)
+
+	templateDBName := "tpl_" + migrations.GetMigrationsHash()[:32]
+	tplDbExistsRes, err := db.Query("SELECT 1 FROM pg_database WHERE datname = $1", templateDBName)
+	if err != nil {
+		require.NoError(t, err)
+	}
+	require.True(t, tplDbExistsRes.Next())
+	require.NoError(t, tplDbExistsRes.Close())
+
+	// now populate the db with some data and use it as a new template db
+	// to verify that dbtestutil.Open respects WithDBFrom
+	_, err = db.Exec("CREATE TABLE my_wonderful_table (id serial PRIMARY KEY, name text)")
+	require.NoError(t, err)
+	_, err = db.Exec("INSERT INTO my_wonderful_table (name) VALUES ('test')")
+	require.NoError(t, err)
+
+	rows, err := db.Query("SELECT current_database()")
+	require.NoError(t, err)
+	require.True(t, rows.Next())
+	var freshTemplateDBName string
+	require.NoError(t, rows.Scan(&freshTemplateDBName))
+	require.NoError(t, rows.Close())
+	require.NoError(t, db.Close())
+
+	for i := 0; i < 10; i++ {
+		db, err := sql.Open("postgres", dsn)
+		require.NoError(t, err)
+		require.NoError(t, db.Ping())
+		require.NoError(t, db.Close())
+	}
+
+	// now create a new db from the template db
+	newDsn, err := dbtestutil.Open(t, dbtestutil.WithDBFrom(freshTemplateDBName))
+	require.NoError(t, err)
+
+	newDb, err := sql.Open("postgres", newDsn)
+	require.NoError(t, err)
+	t.Cleanup(func() {
+		require.NoError(t, newDb.Close())
+	})
+
+	rows, err = newDb.Query("SELECT 1 FROM my_wonderful_table WHERE name = 'test'")
+	require.NoError(t, err)
+	require.True(t, rows.Next())
+	require.NoError(t, rows.Close())
+}