✨ feat(bdd): parallel-safe schema-per-package isolation (T12 stage 2/2) — 2.85x speedup (#35)

Per-package isolated Postgres schema with migrations. Local benchmark: 12.87s sequential → 4.51s parallel = 2.85x. ADR-0025 status to Implemented. CI uses BDD_SCHEMA_ISOLATION=true.

Co-authored-by: Gabriel Radureau <arcodange@gmail.com>
Co-committed-by: Gabriel Radureau <arcodange@gmail.com>

pkg/bdd/testserver/server.go

@@ -48,11 +48,13 @@ type Server struct {
 	port               int
 	baseURL            string
 	db                 *sql.DB
-	authService        user.AuthService // Reference to auth service for cleanup
-	cacheService       cache.Service    // Reference to cache service for cleanup
-	schemaMutex        sync.Mutex       // Protects schema operations
-	currentSchema      string           // Current schema being used
-	originalSearchPath string           // Original search_path to restore
+	authService        user.AuthService         // Reference to auth service for cleanup
+	cacheService       cache.Service            // Reference to cache service for cleanup
+	isolatedRepo       *user.PostgresRepository // Per-package isolated repo (BDD_SCHEMA_ISOLATION=true)
+	isolatedSchemaName string                   // Per-package schema name to drop on Stop()
+	schemaMutex        sync.Mutex               // Protects schema operations
+	currentSchema      string                   // Current schema being used
+	originalSearchPath string                   // Original search_path to restore
 }
 
 // getDatabaseHost returns the database host from environment variable or defaults to localhost
@@ -148,9 +150,55 @@ func (s *Server) Start() error {
 	// This is the ONLY place where we check env vars for v2 configuration
 	v2Enabled := s.shouldEnableV2()
 
-	// Create real server instance from pkg/server
+	// Create real server instance from pkg/server.
+	// When BDD_SCHEMA_ISOLATION=true, each test package (process) gets its own
+	// isolated PostgreSQL schema with its own connection pool + migrations.
+	// This makes `go test ./features/...` parallel-safe because each feature
+	// package runs in its own process and gets its own schema.
 	cfg := createTestConfig(s.port, v2Enabled)
-	realServer := server.NewServer(cfg, context.Background())
+	var realServer *server.Server
+	if isSchemaIsolationEnabled() {
+		feature := os.Getenv("FEATURE")
+		if feature == "" {
+			feature = "bdd"
+		}
+		schemaName := generateSchemaName(feature, "package_root")
+		log.Info().Str("schema", schemaName).Str("feature", feature).Msg("ISOLATION: Building per-package isolated repo")
+
+		// Connect a default repo briefly just to CREATE SCHEMA (uses cfg from env vars)
+		bootstrapRepo, err := user.NewPostgresRepository(cfg)
+		if err != nil {
+			return fmt.Errorf("ISOLATION bootstrap repo failed: %w", err)
+		}
+		// Drop + recreate to ensure clean slate per process
+		_ = bootstrapRepo.Exec(fmt.Sprintf("DROP SCHEMA IF EXISTS %s CASCADE", schemaName))
+		if err := bootstrapRepo.Exec(fmt.Sprintf("CREATE SCHEMA %s", schemaName)); err != nil {
+			bootstrapRepo.Close()
+			return fmt.Errorf("ISOLATION CREATE SCHEMA failed: %w", err)
+		}
+		bootstrapRepo.Close()
+
+		// Build the per-package isolated repo (runs migrations in the new schema)
+		dsn := user.BuildSchemaIsolatedDSN(cfg, schemaName)
+		isolatedRepo, err := user.NewPostgresRepositoryFromDSN(cfg, dsn)
+		if err != nil {
+			return fmt.Errorf("ISOLATION isolated repo failed: %w", err)
+		}
+		s.isolatedRepo = isolatedRepo
+		s.isolatedSchemaName = schemaName
+
+		// Build user service backed by the isolated repo
+		jwtConfig := user.JWTConfig{
+			Secret:         cfg.GetJWTSecret(),
+			ExpirationTime: time.Hour * 24,
+			Issuer:         "dance-lessons-coach",
+		}
+		isolatedUserService := user.NewUserService(isolatedRepo, jwtConfig, cfg.GetAdminMasterPassword())
+
+		realServer = server.NewServerWithUserRepo(cfg, context.Background(), isolatedRepo, isolatedUserService)
+	} else {
+		realServer = server.NewServer(cfg, context.Background())
+	}
 
 	// Store auth service for cleanup
 	s.authService = realServer.GetAuthService()
@@ -639,6 +687,21 @@ func (s *Server) getCurrentSearchPath() (string, error) {
 }
 
 func (s *Server) Stop() error {
+	// Cleanup the per-package isolated schema + close its pool, if any.
+	// (BDD_SCHEMA_ISOLATION=true path - see Start().)
+	if s.isolatedRepo != nil {
+		if s.isolatedSchemaName != "" {
+			if err := s.isolatedRepo.Exec(fmt.Sprintf("DROP SCHEMA IF EXISTS %s CASCADE", s.isolatedSchemaName)); err != nil {
+				log.Warn().Err(err).Str("schema", s.isolatedSchemaName).Msg("ISOLATION: failed to drop schema on Stop")
+			}
+		}
+		if err := s.isolatedRepo.Close(); err != nil {
+			log.Warn().Err(err).Msg("ISOLATION: failed to close isolated repo")
+		}
+		s.isolatedRepo = nil
+		s.isolatedSchemaName = ""
+	}
+
 	if s.httpServer != nil {
 		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 		defer cancel()

pkg/server/server.go

@@ -71,7 +71,21 @@ type Server struct {
 }
 
 func NewServer(cfg *config.Config, readyCtx context.Context) *Server {
-	// Create validator instance
+	// Initialize default user repository and services (Postgres from cfg)
+	userRepo, userService, err := initializeUserServices(cfg)
+	if err != nil {
+		log.Warn().Err(err).Msg("Failed to initialize user services, user functionality will be disabled")
+	}
+	return NewServerWithUserRepo(cfg, readyCtx, userRepo, userService)
+}
+
+// NewServerWithUserRepo builds a Server with caller-provided userRepo + userService.
+// Used by BDD test infra to inject a per-scenario repository (e.g., one connected
+// to an isolated PostgreSQL schema). Pass nil for both to disable user functionality.
+//
+// The validator + cache services are still built from cfg internally; they don't
+// need per-scenario isolation today.
+func NewServerWithUserRepo(cfg *config.Config, readyCtx context.Context, userRepo user.UserRepository, userService user.UserService) *Server {
 	validator, err := validation.GetValidatorFromConfig(cfg)
 	if err != nil {
 		log.Error().Err(err).Msg("Failed to create validator, continuing without validation")
@@ -79,13 +93,6 @@ func NewServer(cfg *config.Config, readyCtx context.Context) *Server {
 		log.Trace().Msg("Validator created successfully")
 	}
 
-	// Initialize user repository and services
-	userRepo, userService, err := initializeUserServices(cfg)
-	if err != nil {
-		log.Warn().Err(err).Msg("Failed to initialize user services, user functionality will be disabled")
-	}
-
-	// Initialize cache service
 	var cacheService cache.Service
 	if cfg.GetCacheEnabled() {
 		cacheService = cache.NewInMemoryService(

pkg/user/postgres_repository.go

@@ -184,7 +184,15 @@ func BuildSchemaIsolatedDSN(cfg *config.Config, schemaName string) string {
 	)
 }
 
-// (Close already exists below; we reuse it.)
+// Exec runs a raw SQL statement against the repository's connection.
+// Used by BDD test infra for schema lifecycle (CREATE SCHEMA / DROP SCHEMA).
+// Avoid in production code paths -- prefer the typed Repository methods.
+func (r *PostgresRepository) Exec(sql string) error {
+	if r.db == nil {
+		return fmt.Errorf("Exec called on PostgresRepository with nil db")
+	}
+	return r.db.Exec(sql).Error
+}
 
 // initializeDatabase sets up the PostgreSQL database connection and runs migrations
 func (r *PostgresRepository) initializeDatabase() error {