Port SQLCDEBUG to a registry-style package modeled after Go's GODEBUG

Replace the monolithic opts.Debug snapshot with internal/sqlcdebug, which
exposes a master Settings table and per-call-site Setting handles via
sqlcdebug.New("name"). Each consumer reads its setting independently
through Setting.Value(), removing the need to thread a Debug struct
through cmd.Env, opts.Parser, and the analyzer constructors.

Migrated readers:
- cmd: trace, processplugins, dumpcatalog, dumpvetenv, dumpexplain, databases
- compiler: dumpast
- postgresql/sqlite analyzers: databases
- tracer: trace (now via tracer.Path())

The endtoend test fixture process_plugin_disabled now installs the
SQLCDEBUG override via sqlcdebug.Update for the duration of the subtest;
TestReplay subtests run sequentially, so no synchronization is needed.

Author: claude

internal/cmd/cmd.go

@@ -18,12 +18,14 @@ import (
 	"gopkg.in/yaml.v3"
 
 	"github.com/sqlc-dev/sqlc/internal/config"
-	"github.com/sqlc-dev/sqlc/internal/debug"
 	"github.com/sqlc-dev/sqlc/internal/info"
 	"github.com/sqlc-dev/sqlc/internal/opts"
+	"github.com/sqlc-dev/sqlc/internal/sqlcdebug"
 	"github.com/sqlc-dev/sqlc/internal/tracer"
 )
 
+var debugProcessPlugins = sqlcdebug.New("processplugins")
+
 func init() {
 	createDBCmd.Flags().StringP("queryset", "", "", "name of the queryset to use")
 	pushCmd.Flags().BoolP("dry-run", "", false, "dump push request (default: false)")
@@ -55,7 +57,7 @@ func Do(args []string, stdin io.Reader, stdout io.Writer, stderr io.Writer) int
 	rootCmd.SetErr(stderr)
 
 	ctx := context.Background()
-	if debug.Debug.Trace != "" {
+	if tracer.Path() != "" {
 		tracectx, cleanup, err := tracer.Start(ctx)
 		if err != nil {
 			fmt.Printf("failed to start trace: %v\n", err)
@@ -137,15 +139,13 @@ var initCmd = &cobra.Command{
 
 type Env struct {
 	DryRun     bool
-	Debug      opts.Debug
 	Experiment opts.Experiment
 }
 
 func ParseEnv(c *cobra.Command) Env {
 	dr := c.Flag("dry-run")
 	return Env{
 		DryRun:     dr != nil && dr.Changed,
-		Debug:      opts.DebugFromEnv(),
 		Experiment: opts.ExperimentFromEnv(),
 	}
 }
@@ -154,7 +154,7 @@ var ErrPluginProcessDisabled = errors.New("plugin: process-based plugins disable
 
 func (e *Env) Validate(cfg *config.Config) error {
 	for _, plugin := range cfg.Plugins {
-		if plugin.Process != nil && !e.Debug.ProcessPlugins {
+		if plugin.Process != nil && debugProcessPlugins.Value() == "0" {
 			return ErrPluginProcessDisabled
 		}
 	}

internal/cmd/generate.go

@@ -26,8 +26,11 @@ import (
 	"github.com/sqlc-dev/sqlc/internal/multierr"
 	"github.com/sqlc-dev/sqlc/internal/opts"
 	"github.com/sqlc-dev/sqlc/internal/plugin"
+	"github.com/sqlc-dev/sqlc/internal/sqlcdebug"
 )
 
+var debugDumpCatalog = sqlcdebug.New("dumpcatalog")
+
 const errMessageNoVersion = `The configuration file must have a version number.
 Set the version to 1 or 2 at the top of sqlc.json:
 
@@ -244,7 +247,7 @@ func parse(ctx context.Context, name, dir string, sql config.SQL, combo config.C
 		}
 		return nil, true
 	}
-	if parserOpts.Debug.DumpCatalog {
+	if debugDumpCatalog.Value() == "1" {
 		debug.Dump(c.Catalog())
 	}
 	if err := c.ParseQueries(sql.Queries, parserOpts); err != nil {

internal/cmd/process.go

@@ -13,7 +13,6 @@ import (
 
 	"github.com/sqlc-dev/sqlc/internal/compiler"
 	"github.com/sqlc-dev/sqlc/internal/config"
-	"github.com/sqlc-dev/sqlc/internal/debug"
 	"github.com/sqlc-dev/sqlc/internal/opts"
 )
 
@@ -87,9 +86,7 @@ func processQuerySets(ctx context.Context, rp ResultProcessor, conf *config.Conf
 			sql.Queries = joined
 
 			var name, lang string
-			parseOpts := opts.Parser{
-				Debug: debug.Debug,
-			}
+			parseOpts := opts.Parser{}
 
 			switch {
 			case sql.Gen.Go != nil:

internal/cmd/vet.go

@@ -33,9 +33,16 @@ import (
 	"github.com/sqlc-dev/sqlc/internal/quickdb"
 	"github.com/sqlc-dev/sqlc/internal/shfmt"
 	"github.com/sqlc-dev/sqlc/internal/sql/sqlpath"
+	"github.com/sqlc-dev/sqlc/internal/sqlcdebug"
 	"github.com/sqlc-dev/sqlc/internal/vet"
 )
 
+var (
+	debugDumpExplain = sqlcdebug.New("dumpexplain")
+	debugDumpVetEnv  = sqlcdebug.New("dumpvetenv")
+	debugDatabases   = sqlcdebug.New("databases")
+)
+
 var ErrFailedChecks = errors.New("failed checks")
 
 var pjson = protojson.UnmarshalOptions{AllowPartial: true, DiscardUnknown: true}
@@ -148,7 +155,7 @@ func Vet(ctx context.Context, dir, filename string, opts *Options) error {
 		Dir:           dir,
 		Env:           env,
 		Stderr:        stderr,
-		OnlyManagedDB: e.Debug.OnlyManagedDatabases,
+		OnlyManagedDB: debugDatabases.Value() == "managed",
 		Replacer:      shfmt.NewReplacer(nil),
 	}
 	errored := false
@@ -316,7 +323,7 @@ func (p *pgxConn) Explain(ctx context.Context, query string, args ...*plugin.Par
 	if err := row.Scan(&result); err != nil {
 		return nil, err
 	}
-	if debug.Debug.DumpExplain {
+	if debugDumpExplain.Value() == "1" {
 		fmt.Println(eQuery, "with args", eArgs)
 		fmt.Println(string(result[0]))
 	}
@@ -358,7 +365,7 @@ func (me *mysqlExplainer) Explain(ctx context.Context, query string, args ...*pl
 	if err := row.Scan(&result); err != nil {
 		return nil, err
 	}
-	if debug.Debug.DumpExplain {
+	if debugDumpExplain.Value() == "1" {
 		fmt.Println(eQuery, "with args", eArgs)
 		fmt.Println(string(result))
 	}
@@ -480,9 +487,7 @@ func (c *checker) checkSQL(ctx context.Context, s config.SQL) error {
 	s.Queries = joined
 
 	var name string
-	parseOpts := opts.Parser{
-		Debug: debug.Debug,
-	}
+	parseOpts := opts.Parser{}
 
 	result, failed := parse(ctx, name, c.Dir, s, combo, parseOpts, c.Stderr)
 	if failed {
@@ -642,7 +647,7 @@ func (c *checker) checkSQL(ctx context.Context, s config.SQL) error {
 					evalMap["mysql"] = engineOutput.MySQL
 				}
 
-				if debug.Debug.DumpVetEnv {
+				if debugDumpVetEnv.Value() == "1" {
 					fmt.Printf("vars for rule '%s' evaluating against query '%s':\n", name, query.Name)
 					debug.DumpAsJSON(evalMap)
 				}

internal/compiler/parse.go

@@ -13,12 +13,15 @@ import (
 	"github.com/sqlc-dev/sqlc/internal/sql/ast"
 	"github.com/sqlc-dev/sqlc/internal/sql/astutils"
 	"github.com/sqlc-dev/sqlc/internal/sql/validate"
+	"github.com/sqlc-dev/sqlc/internal/sqlcdebug"
 )
 
+var debugDumpAST = sqlcdebug.New("dumpast")
+
 func (c *Compiler) parseQuery(stmt ast.Node, src string, o opts.Parser) (*Query, error) {
 	ctx := context.Background()
 
-	if o.Debug.DumpAST {
+	if debugDumpAST.Value() == "1" {
 		debug.Dump(stmt)
 	}
 

internal/debug/dump.go

@@ -3,22 +3,16 @@ package debug
 import (
 	"encoding/json"
 	"fmt"
-	"os"
 
 	"github.com/davecgh/go-spew/spew"
 
-	"github.com/sqlc-dev/sqlc/internal/opts"
+	"github.com/sqlc-dev/sqlc/internal/sqlcdebug"
 )
 
-var Active bool
-var Debug opts.Debug
-
-func init() {
-	Active = os.Getenv("SQLCDEBUG") != ""
-	if Active {
-		Debug = opts.DebugFromEnv()
-	}
-}
+// Active reports whether SQLCDEBUG had any value set at startup. It
+// remains a global so unrelated debug-spew sites that don't tie to a
+// specific setting can gate their output on "is debug mode on at all".
+var Active = sqlcdebug.Any()
 
 func Dump(n ...interface{}) {
 	if Active {

internal/endtoend/endtoend_test.go

@@ -17,10 +17,26 @@ import (
 	"github.com/sqlc-dev/sqlc/internal/cmd"
 	"github.com/sqlc-dev/sqlc/internal/config"
 	"github.com/sqlc-dev/sqlc/internal/opts"
+	"github.com/sqlc-dev/sqlc/internal/sqlcdebug"
 	"github.com/sqlc-dev/sqlc/internal/sqltest/docker"
 	"github.com/sqlc-dev/sqlc/internal/sqltest/native"
 )
 
+// withSQLCDEBUG installs the given SQLCDEBUG-formatted string for the
+// duration of the test and restores the empty default afterwards.
+//
+// Callers in TestReplay are sequential, so this does not need a mutex:
+// Go's test scheduler does not run TestReplay concurrently with the
+// parallel top-level tests in this package.
+func withSQLCDEBUG(t *testing.T, raw string) func() {
+	t.Helper()
+	if raw == "" {
+		return func() {}
+	}
+	sqlcdebug.Update(raw)
+	return func() { sqlcdebug.Update("") }
+}
+
 func lineEndings() cmp.Option {
 	return cmp.Transformer("LineEndings", func(in string) string {
 		// Replace Windows new lines with Unix newlines
@@ -263,13 +279,15 @@ func TestReplay(t *testing.T) {
 
 				opts := cmd.Options{
 					Env: cmd.Env{
-						Debug:      opts.DebugFromString(args.Env["SQLCDEBUG"]),
 						Experiment: opts.ExperimentFromString(args.Env["SQLCEXPERIMENT"]),
 					},
 					Stderr:       &stderr,
 					MutateConfig: testctx.Mutate(t, path),
 				}
 
+				release := withSQLCDEBUG(t, args.Env["SQLCDEBUG"])
+				defer release()
+
 				switch args.Command {
 				case "diff":
 					err = cmd.Diff(ctx, path, "", &opts)

internal/engine/postgresql/analyzer/analyze.go

@@ -14,19 +14,20 @@ import (
 	core "github.com/sqlc-dev/sqlc/internal/analysis"
 	"github.com/sqlc-dev/sqlc/internal/config"
 	"github.com/sqlc-dev/sqlc/internal/dbmanager"
-	"github.com/sqlc-dev/sqlc/internal/opts"
 	"github.com/sqlc-dev/sqlc/internal/shfmt"
 	"github.com/sqlc-dev/sqlc/internal/sql/ast"
 	"github.com/sqlc-dev/sqlc/internal/sql/catalog"
 	"github.com/sqlc-dev/sqlc/internal/sql/named"
 	"github.com/sqlc-dev/sqlc/internal/sql/sqlerr"
+	"github.com/sqlc-dev/sqlc/internal/sqlcdebug"
 )
 
+var debugDatabases = sqlcdebug.New("databases")
+
 type Analyzer struct {
 	db       config.Database
 	client   dbmanager.Client
 	pool     *pgxpool.Pool
-	dbg      opts.Debug
 	replacer *shfmt.Replacer
 	formats  sync.Map
 	columns  sync.Map
@@ -36,7 +37,6 @@ type Analyzer struct {
 func New(client dbmanager.Client, db config.Database) *Analyzer {
 	return &Analyzer{
 		db:       db,
-		dbg:      opts.DebugFromEnv(),
 		client:   client,
 		replacer: shfmt.NewReplacer(nil),
 	}
@@ -210,7 +210,7 @@ func (a *Analyzer) Analyze(ctx context.Context, n ast.Node, query string, migrat
 				return nil, err
 			}
 			uri = edb.Uri
-		} else if a.dbg.OnlyManagedDatabases {
+		} else if debugDatabases.Value() == "managed" {
 			return nil, fmt.Errorf("database: connections disabled via SQLCDEBUG=databases=managed")
 		} else {
 			uri = a.replacer.Replace(a.db.URI)
@@ -502,7 +502,7 @@ func (a *Analyzer) EnsureConn(ctx context.Context, migrations []string) error {
 			return err
 		}
 		uri = edb.Uri
-	} else if a.dbg.OnlyManagedDatabases {
+	} else if debugDatabases.Value() == "managed" {
 		return fmt.Errorf("database: connections disabled via SQLCDEBUG=databases=managed")
 	} else {
 		uri = a.replacer.Replace(a.db.URI)

internal/engine/sqlite/analyzer/analyze.go

@@ -10,26 +10,26 @@ import (
 
 	core "github.com/sqlc-dev/sqlc/internal/analysis"
 	"github.com/sqlc-dev/sqlc/internal/config"
-	"github.com/sqlc-dev/sqlc/internal/opts"
 	"github.com/sqlc-dev/sqlc/internal/shfmt"
 	"github.com/sqlc-dev/sqlc/internal/sql/ast"
 	"github.com/sqlc-dev/sqlc/internal/sql/catalog"
 	"github.com/sqlc-dev/sqlc/internal/sql/named"
 	"github.com/sqlc-dev/sqlc/internal/sql/sqlerr"
+	"github.com/sqlc-dev/sqlc/internal/sqlcdebug"
 )
 
+var debugDatabases = sqlcdebug.New("databases")
+
 type Analyzer struct {
 	db       config.Database
 	conn     *sqlite3.Conn
-	dbg      opts.Debug
 	replacer *shfmt.Replacer
 	mu       sync.Mutex
 }
 
 func New(db config.Database) *Analyzer {
 	return &Analyzer{
 		db:       db,
-		dbg:      opts.DebugFromEnv(),
 		replacer: shfmt.NewReplacer(nil),
 	}
 }
@@ -44,7 +44,7 @@ func (a *Analyzer) Analyze(ctx context.Context, n ast.Node, query string, migrat
 		if a.db.Managed {
 			// For managed databases, create an in-memory database
 			uri = ":memory:"
-		} else if a.dbg.OnlyManagedDatabases {
+		} else if debugDatabases.Value() == "managed" {
 			return nil, fmt.Errorf("database: connections disabled via SQLCDEBUG=databases=managed")
 		} else {
 			uri = a.replacer.Replace(a.db.URI)
@@ -200,7 +200,7 @@ func (a *Analyzer) EnsureConn(ctx context.Context, migrations []string) error {
 	if a.db.Managed {
 		// For managed databases, create an in-memory database
 		uri = ":memory:"
-	} else if a.dbg.OnlyManagedDatabases {
+	} else if debugDatabases.Value() == "managed" {
 		return fmt.Errorf("database: connections disabled via SQLCDEBUG=databases=managed")
 	} else {
 		uri = a.replacer.Replace(a.db.URI)