feat(integrations): add OpenTelemetry and GORM sub-modules (#451 #452)

* docs: add Q2 2026 roadmap design spec from multi-persona audit

Full-project audit using 5 parallel analytical personas (Performance,
SQL Compatibility, API/DX, Competitive, Community). Synthesizes into
prioritized P0–P3 roadmap covering: HN launch, query fingerprinting,
linter expansion to 30 rules, DML transforms, C binding hardening,
live DB schema introspection, SQL transpilation, CONNECT BY, OTel,
GORM integration, and advisor expansion.

Corresponding GitHub issues: #442–#460

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: add Q2 2026 implementation plans for all roadmap items

12 implementation plans covering all prioritized GitHub issues:

P0 (Critical):
- 2026-03-29-sentry-fixes.md (#434, #437) — fix Sentry noise filters
- 2026-03-29-openssf-scorecard.md (#443) — security scorecard badge

P1 (High Priority):
- 2026-03-29-query-fingerprinting.md (#444) — SQL normalization + SHA-256 fingerprints
- 2026-03-29-linter-expansion.md (#445) — L011-L030 safety/performance/naming rules
- 2026-03-29-dml-transforms.md (#446) — SET clause and RETURNING transforms
- 2026-03-29-cbinding-hardening.md (#447) — C binding coverage + stress tests
- 2026-03-29-advisor-expansion.md (#453) — OPT-009 through OPT-020 advisor rules

P2 (Medium Priority):
- 2026-03-29-sql-parser-additions.md (#450, #454, #455, #456) — DDL formatter, CONNECT BY, SAMPLE, PIVOT/UNPIVOT
- 2026-03-29-schema-introspection.md (#448) — live DB schema introspection (Postgres, MySQL, SQLite)
- 2026-03-29-integrations.md (#451, #452) — OpenTelemetry + GORM sub-modules
- 2026-03-29-sql-transpilation.md (#449) — SQL dialect transpilation API

P3 (Low Priority):
- 2026-03-29-p3-items.md (#458, #459, #460) — CLI watch registration, pool stats, JSON functions

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(integrations): add OpenTelemetry and GORM sub-modules (#451 #452)

- integrations/opentelemetry: InstrumentedParse() wraps gosqlx.Parse() with
  OTel spans (db.system, db.statement.type, db.sql.tables, db.sql.columns);
  errors recorded on span with status Error; 3 tests pass with race detector
- integrations/gorm: Plugin struct implementing gorm.Plugin; afterStatement
  callback normalizes GORM SQL (backtick→double-quote, ?→$N) before parsing;
  Stats()/Reset() API; nil Statement guard; 5 tests pass with race detector
- .github/workflows/integrations.yml: separate jobs for each sub-module
- CHANGELOG.md: document new sub-modules under [Unreleased]

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(integrations): bump OTel SDK v1.26→v1.42 to resolve CVE-2026-24051

Updates go.opentelemetry.io/otel/sdk from v1.26.0 to v1.42.0 to fix
HIGH severity PATH hijacking vulnerability (GHSA-9h8m-3fm2-qjrq).

Also bumps transitive deps: logr v1.4.3, sys v0.41.0.

* fix(integrations): address PR #465 review — CI Go version, GORM history limit, error callback

- CI workflow: bump go-version from 1.23 to 1.26 to match project requirements
- GORM plugin: add maxHistory field (default 1000) to bound query record growth
- GORM plugin: add OnParseError callback for visibility into parse failures
- GORM plugin: add NewPluginWithOptions constructor with PluginOptions struct
- Tests: add coverage for MaxHistory trimming, OnParseError callback, defaults

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Ajit Pratap Singh <ajitpratapsingh@Ajits-Mac-mini-2655.local>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

.github/workflows/integrations.yml

@@ -0,0 +1,40 @@
+name: Integrations
+
+on:
+  push:
+    paths:
+      - 'integrations/**'
+      - '.github/workflows/integrations.yml'
+  pull_request:
+    paths:
+      - 'integrations/**'
+      - '.github/workflows/integrations.yml'
+
+jobs:
+  opentelemetry:
+    name: OpenTelemetry Integration
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: integrations/opentelemetry
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.26'
+      - run: go mod tidy
+      - run: go test -race -timeout 60s ./...
+
+  gorm:
+    name: GORM Integration
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: integrations/gorm
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.26'
+      - run: go mod tidy
+      - run: go test -race -timeout 60s ./...

CHANGELOG.md

@@ -15,6 +15,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `gosqlx.Transpile()` top-level convenience wrapper
   - `gosqlx transpile --from <dialect> --to <dialect>` CLI subcommand
 - **MariaDB dialect** (`--dialect mariadb`): New SQL dialect extending MySQL with support for SEQUENCE DDL (`CREATE/DROP/ALTER SEQUENCE` with full option set), temporal tables (`FOR SYSTEM_TIME`, `WITH SYSTEM VERSIONING`, `PERIOD FOR`), and `CONNECT BY` hierarchical queries with `PRIOR`, `START WITH`, and `NOCYCLE`
+- `integrations/opentelemetry/` sub-module: `InstrumentedParse()` wraps `gosqlx.Parse()` with OpenTelemetry spans including `db.system`, `db.statement.type`, `db.sql.tables`, `db.sql.columns` attributes
+- `integrations/gorm/` sub-module: GORM plugin that records executed query metadata (tables, columns, statement type) via GoSQLX parsing with GORM SQL normalization (backtick identifiers, `?` placeholders); exposes `Stats()` and `Reset()` APIs
+- CI workflow for integration sub-modules (`.github/workflows/integrations.yml`)
 
 ## [1.13.0] - 2026-03-20
 

integrations/gorm/go.mod

@@ -0,0 +1,17 @@
+module github.com/ajitpratap0/GoSQLX/integrations/gorm
+
+go 1.26.1
+
+require (
+	github.com/ajitpratap0/GoSQLX v1.13.0
+	gorm.io/driver/sqlite v1.5.6
+	gorm.io/gorm v1.25.10
+)
+
+require (
+	github.com/jinzhu/inflection v1.0.0 // indirect
+	github.com/jinzhu/now v1.1.5 // indirect
+	github.com/mattn/go-sqlite3 v1.14.22 // indirect
+)
+
+replace github.com/ajitpratap0/GoSQLX => ../../

integrations/gorm/go.sum

@@ -0,0 +1,10 @@
+github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
+github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
+github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
+github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
+github.com/mattn/go-sqlite3 v1.14.22 h1:2gZY6PC6kBnID23Tichd1K+Z0oS6nE/XwU+Vz/5o4kU=
+github.com/mattn/go-sqlite3 v1.14.22/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
+gorm.io/driver/sqlite v1.5.6 h1:fO/X46qn5NUEEOZtnjJRWRzZMe8nqJiQ9E+0hi+hKQE=
+gorm.io/driver/sqlite v1.5.6/go.mod h1:U+J8craQU6Fzkcvu8oLeAQmi50TkwPEhHDEjQZXDah4=
+gorm.io/gorm v1.25.10 h1:dQpO+33KalOA+aFYGlK+EfxcI5MbO7EP2yYygwh9h+s=
+gorm.io/gorm v1.25.10/go.mod h1:hbnx/Oo0ChWMn1BIhpy1oYozzpM15i4YPuHDmfYtwg8=

integrations/gorm/plugin.go

@@ -0,0 +1,190 @@
+// Package gosqlxgorm provides a GORM plugin that parses each executed query
+// with GoSQLX and records extracted metadata (tables, columns, statement type).
+package gosqlxgorm
+
+import (
+	"regexp"
+	"strconv"
+	"strings"
+	"sync"
+
+	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
+	"github.com/ajitpratap0/GoSQLX/pkg/sql/ast"
+	"github.com/ajitpratap0/GoSQLX/pkg/sql/keywords"
+	"gorm.io/gorm"
+)
+
+// reQuestionMark replaces GORM's ? positional placeholders.
+var reQuestionMark = regexp.MustCompile(`\?`)
+
+// QueryRecord holds metadata about a single recorded GORM query.
+type QueryRecord struct {
+	SQL     string
+	Tables  []string
+	Columns []string
+	Type    string // SELECT, INSERT, UPDATE, DELETE, ...
+	ParseOK bool
+}
+
+// PluginStats is the aggregate of all queries observed since initialization.
+type PluginStats struct {
+	TotalQueries int
+	ParseErrors  int
+	Queries      []QueryRecord
+}
+
+// defaultMaxHistory is the default maximum number of query records kept.
+const defaultMaxHistory = 1000
+
+// PluginOptions configures the GORM plugin behavior.
+type PluginOptions struct {
+	// MaxHistory limits the number of query records kept. Zero uses the default (1000).
+	MaxHistory int
+	// OnParseError is called when GoSQLX fails to parse a query. Optional.
+	OnParseError func(sql string, err error)
+}
+
+// Plugin is a GORM plugin that parses each executed query with GoSQLX
+// and records extracted metadata (tables, columns, statement type).
+type Plugin struct {
+	mu           sync.Mutex
+	queries      []QueryRecord
+	maxHistory   int
+	onParseError func(sql string, err error)
+}
+
+// NewPlugin returns a new GoSQLX GORM plugin with default options.
+func NewPlugin() *Plugin {
+	return &Plugin{maxHistory: defaultMaxHistory}
+}
+
+// NewPluginWithOptions returns a new GoSQLX GORM plugin configured with opts.
+func NewPluginWithOptions(opts PluginOptions) *Plugin {
+	mh := opts.MaxHistory
+	if mh <= 0 {
+		mh = defaultMaxHistory
+	}
+	return &Plugin{
+		maxHistory:   mh,
+		onParseError: opts.OnParseError,
+	}
+}
+
+// Name implements gorm.Plugin.
+func (p *Plugin) Name() string { return "gosqlx" }
+
+// Initialize implements gorm.Plugin by registering after-callbacks.
+func (p *Plugin) Initialize(db *gorm.DB) error {
+	db.Callback().Query().After("gorm:query").Register("gosqlx:after_query", p.afterStatement)
+	db.Callback().Create().After("gorm:create").Register("gosqlx:after_create", p.afterStatement)
+	db.Callback().Update().After("gorm:update").Register("gosqlx:after_update", p.afterStatement)
+	db.Callback().Delete().After("gorm:delete").Register("gosqlx:after_delete", p.afterStatement)
+	db.Callback().Raw().After("gorm:raw").Register("gosqlx:after_raw", p.afterStatement)
+	return nil
+}
+
+func (p *Plugin) afterStatement(db *gorm.DB) {
+	// Guard against nil Statement — this can happen during initialization callbacks.
+	if db.Statement == nil {
+		return
+	}
+	sql := db.Statement.SQL.String()
+	if sql == "" {
+		return
+	}
+
+	rec := QueryRecord{SQL: sql}
+
+	// Normalize GORM-generated SQL for GoSQLX compatibility:
+	//   1. Replace backtick-quoted identifiers with double-quoted identifiers
+	//      (GORM SQLite/MySQL driver uses backticks; GoSQLX standard mode uses double-quotes).
+	//   2. Replace ? positional placeholders with $N (PostgreSQL style).
+	normalized := normalizeSQLForParsing(sql)
+
+	// Try PostgreSQL dialect (handles double-quoted identifiers and $N placeholders),
+	// then fall back to standard SQL parsing.
+	tree, err := gosqlx.ParseWithDialect(normalized, keywords.DialectPostgreSQL)
+	if err != nil {
+		tree, err = gosqlx.Parse(normalized)
+	}
+	if err != nil {
+		rec.ParseOK = false
+		if p.onParseError != nil {
+			p.onParseError(sql, err)
+		}
+	} else {
+		rec.ParseOK = true
+		rec.Tables = gosqlx.ExtractTables(tree)
+		rec.Columns = gosqlx.ExtractColumns(tree)
+		if tree != nil && len(tree.Statements) > 0 {
+			rec.Type = stmtTypeName(tree.Statements[0])
+		}
+	}
+
+	p.mu.Lock()
+	p.queries = append(p.queries, rec)
+	if len(p.queries) > p.maxHistory {
+		// Trim oldest entries to stay within the limit.
+		excess := len(p.queries) - p.maxHistory
+		copy(p.queries, p.queries[excess:])
+		p.queries = p.queries[:p.maxHistory]
+	}
+	p.mu.Unlock()
+}
+
+// normalizeSQLForParsing converts GORM-generated SQL into a form that GoSQLX
+// can parse: backtick identifiers become double-quoted, and ? placeholders
+// become $N placeholders.
+func normalizeSQLForParsing(sql string) string {
+	// Replace backtick-quoted identifiers with double-quoted identifiers.
+	sql = strings.ReplaceAll(sql, "`", "\"")
+	// Replace ? positional placeholders with $N.
+	n := 0
+	sql = reQuestionMark.ReplaceAllStringFunc(sql, func(string) string {
+		n++
+		return "$" + strconv.Itoa(n)
+	})
+	return sql
+}
+
+// Stats returns a snapshot of all recorded queries.
+func (p *Plugin) Stats() PluginStats {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	var errCount int
+	for _, q := range p.queries {
+		if !q.ParseOK {
+			errCount++
+		}
+	}
+	qs := make([]QueryRecord, len(p.queries))
+	copy(qs, p.queries)
+	return PluginStats{
+		TotalQueries: len(p.queries),
+		ParseErrors:  errCount,
+		Queries:      qs,
+	}
+}
+
+// Reset clears all recorded queries.
+func (p *Plugin) Reset() {
+	p.mu.Lock()
+	p.queries = p.queries[:0]
+	p.mu.Unlock()
+}
+
+// stmtTypeName returns a human-readable SQL statement type name.
+func stmtTypeName(stmt ast.Statement) string {
+	switch stmt.(type) {
+	case *ast.SelectStatement:
+		return "SELECT"
+	case *ast.InsertStatement:
+		return "INSERT"
+	case *ast.UpdateStatement:
+		return "UPDATE"
+	case *ast.DeleteStatement:
+		return "DELETE"
+	default:
+		return "OTHER"
+	}
+}