Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

feat: add Prometheus metrics for metadata database queries (#18190)

Vincent Huang08a499695705
diff --git a/backend/store/db_connection.go b/backend/store/db_connection.go
index 987b4a2090..144ca0eaa3 100644
--- a/backend/store/db_connection.go
+++ b/backend/store/db_connection.go
@@ -10,6 +10,8 @@ import (
"time"
"github.com/fsnotify/fsnotify"
+ "github.com/jackc/pgx/v5"
+ "github.com/jackc/pgx/v5/stdlib"
"github.com/pkg/errors"
"github.com/bytebase/bytebase/backend/common/qb"
@@ -58,7 +60,7 @@ func (m *DBConnectionManager) Initialize(ctx context.Context) error {
}
// Create initial connection
- db, err := createConnection(ctx, pgURL)
+ db, err := createConnectionWithTracer(ctx, pgURL)
if err != nil {
return err
}
@@ -79,10 +81,16 @@ func (m *DBConnectionManager) Close() error {
m.watcher.Close()
}
- if m.db != nil {
- return m.db.Close()
+ m.mu.Lock()
+ defer m.mu.Unlock()
+
+ if m.db == nil {
+ return nil
}
- return nil
+
+ err := m.db.Close()
+ m.db = nil
+ return err
}
// startFileWatcher starts watching the PG_URL file for changes.
@@ -138,8 +146,8 @@ func (m *DBConnectionManager) reloadConnection(ctx context.Context, filePath str
slog.Info("PG URL file content updated, reconnecting database")
- // Create new connection
- newDB, err := createConnection(ctx, newURL)
+ // Create new connection first (zero downtime)
+ newDB, err := createConnectionWithTracer(ctx, newURL)
if err != nil {
slog.Error("Failed to create new database connection", "error", err)
return
@@ -192,12 +200,15 @@ func readURLFromFile(path string) (string, error) {
return strings.TrimSpace(string(content)), nil
}
-func createConnection(ctx context.Context, pgURL string) (*sql.DB, error) {
- db, err := sql.Open("pgx", pgURL)
+func createConnectionWithTracer(ctx context.Context, pgURL string) (*sql.DB, error) {
+ pgxConfig, err := pgx.ParseConfig(pgURL)
if err != nil {
- return nil, errors.Wrap(err, "failed to open database connection")
+ return nil, errors.Wrap(err, "failed to parse database URL")
}
+ pgxConfig.Tracer = &metadataDBTracer{}
+ db := stdlib.OpenDB(*pgxConfig)
+
// Validate connection
if err := db.PingContext(ctx); err != nil {
db.Close()
diff --git a/backend/store/db_metrics.go b/backend/store/db_metrics.go
new file mode 100644
index 0000000000..88d8b636f7
--- /dev/null
+++ b/backend/store/db_metrics.go
@@ -0,0 +1,18 @@
+package store
+
+import (
+ "github.com/prometheus/client_golang/prometheus"
+ "github.com/prometheus/client_golang/prometheus/promauto"
+)
+
+var (
+ // metadataDBQueryDuration tracks query latency for Bytebase's metadata database.
+ metadataDBQueryDuration = promauto.NewHistogramVec(
+ prometheus.HistogramOpts{
+ Name: "bytebase_metadata_db_query_duration_seconds",
+ Help: "Duration of queries to Bytebase's internal metadata database",
+ Buckets: []float64{0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1.0, 5.0, 10.0, 30.0},
+ },
+ []string{"operation", "status"},
+ )
+)
diff --git a/backend/store/db_tracer.go b/backend/store/db_tracer.go
new file mode 100644
index 0000000000..fb3bc0552a
--- /dev/null
+++ b/backend/store/db_tracer.go
@@ -0,0 +1,93 @@
+package store
+
+import (
+ "context"
+ "errors"
+ "strings"
+ "time"
+
+ "github.com/jackc/pgx/v5"
+)
+
+// metadataDBTracer implements pgx.QueryTracer to record query metrics.
+type metadataDBTracer struct{}
+
+// queryTracerData stores data passed from TraceQueryStart to TraceQueryEnd.
+type queryTracerData struct {
+ startTime time.Time
+ sql string
+}
+
+// queryTracerCtxKey is the context key for storing query trace data.
+type queryTracerCtxKey struct{}
+
+// TraceQueryStart is called at the beginning of Query, QueryRow, and Exec calls.
+func (*metadataDBTracer) TraceQueryStart(ctx context.Context, _ *pgx.Conn, data pgx.TraceQueryStartData) context.Context {
+ traceData := queryTracerData{
+ startTime: time.Now(),
+ sql: data.SQL,
+ }
+ return context.WithValue(ctx, queryTracerCtxKey{}, traceData)
+}
+
+// TraceQueryEnd is called at the end of Query, QueryRow, and Exec calls.
+func (*metadataDBTracer) TraceQueryEnd(ctx context.Context, _ *pgx.Conn, data pgx.TraceQueryEndData) {
+ traceData, ok := ctx.Value(queryTracerCtxKey{}).(queryTracerData)
+ if !ok {
+ return
+ }
+
+ duration := time.Since(traceData.startTime).Seconds()
+ operation := extractQueryOperation(traceData.sql)
+
+ status := "success"
+ if data.Err != nil {
+ if errors.Is(data.Err, context.Canceled) ||
+ errors.Is(data.Err, context.DeadlineExceeded) {
+ status = "cancelled"
+ } else {
+ status = "error"
+ }
+ }
+
+ metadataDBQueryDuration.WithLabelValues(operation, status).Observe(duration)
+}
+
+// extractQueryOperation extracts the SQL operation type from a query string.
+// This is a lightweight operation extraction for metrics purposes only.
+func extractQueryOperation(sql string) string {
+ // Normalize: trim and lowercase
+ normalized := strings.TrimSpace(strings.ToLower(sql))
+ if normalized == "" {
+ return "other"
+ }
+
+ // Find first word
+ firstWord := normalized
+ if idx := strings.IndexAny(normalized, " \t\n\r"); idx > 0 {
+ firstWord = normalized[:idx]
+ }
+
+ switch firstWord {
+ case "select", "show":
+ return "select"
+ case "insert":
+ return "insert"
+ case "update":
+ return "update"
+ case "delete":
+ return "delete"
+ case "with":
+ // CTE - look for actual operation
+ if strings.Contains(normalized, " insert ") {
+ return "insert"
+ } else if strings.Contains(normalized, " update ") {
+ return "update"
+ } else if strings.Contains(normalized, " delete ") {
+ return "delete"
+ }
+ return "select"
+ default:
+ return "other"
+ }
+}
diff --git a/backend/store/db_tracer_test.go b/backend/store/db_tracer_test.go
new file mode 100644
index 0000000000..ea705fa27c
--- /dev/null
+++ b/backend/store/db_tracer_test.go
@@ -0,0 +1,94 @@
+package store
+
+import (
+ "context"
+ "errors"
+ "testing"
+ "time"
+
+ "github.com/jackc/pgx/v5"
+ "github.com/stretchr/testify/assert"
+)
+
+func TestExtractQueryOperation(t *testing.T) {
+ tests := []struct {
+ name string
+ sql string
+ expected string
+ }{
+ {"SELECT query", "SELECT * FROM users", "select"},
+ {"INSERT query", "INSERT INTO users VALUES (1)", "insert"},
+ {"UPDATE query", "UPDATE users SET name = 'foo'", "update"},
+ {"DELETE query", "DELETE FROM users WHERE id = 1", "delete"},
+ {"SHOW query", "SHOW max_connections", "select"},
+ {"CTE with SELECT", "WITH cte AS (SELECT 1) SELECT * FROM cte", "select"},
+ {"CTE with INSERT", "WITH cte AS (SELECT 1) INSERT INTO users VALUES (1)", "insert"},
+ {"CTE with UPDATE", "WITH cte AS (SELECT 1) UPDATE users SET name = 'foo'", "update"},
+ {"CTE with DELETE", "WITH cte AS (SELECT 1) DELETE FROM users WHERE id = 1", "delete"},
+ {"Other query", "CREATE TABLE users (id INT)", "other"},
+ {"Empty query", "", "other"},
+ {"Whitespace", " \n\t ", "other"},
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ result := extractQueryOperation(tt.sql)
+ assert.Equal(t, tt.expected, result)
+ })
+ }
+}
+
+func TestMetadataDBTracer_TraceQueryEnd(t *testing.T) {
+ tests := []struct {
+ name string
+ err error
+ expectedStatus string
+ }{
+ {"Success", nil, "success"},
+ {"Error", errors.New("some error"), "error"},
+ {"Context Canceled", context.Canceled, "cancelled"},
+ {"Context Deadline Exceeded", context.DeadlineExceeded, "cancelled"},
+ {"Wrapped Context Canceled", errors.Join(errors.New("wrapper"), context.Canceled), "cancelled"},
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ tracer := &metadataDBTracer{}
+
+ // Start trace
+ ctx := context.Background()
+ startData := pgx.TraceQueryStartData{
+ SQL: "SELECT * FROM users",
+ }
+ ctx = tracer.TraceQueryStart(ctx, nil, startData)
+
+ // Small delay to ensure measurable duration
+ time.Sleep(1 * time.Millisecond)
+
+ // End trace
+ endData := pgx.TraceQueryEndData{
+ Err: tt.err,
+ }
+
+ // We can't directly verify the metric was recorded, but we can verify
+ // the function doesn't panic and handles different error types
+ assert.NotPanics(t, func() {
+ tracer.TraceQueryEnd(ctx, nil, endData)
+ })
+ })
+ }
+}
+
+func TestMetadataDBTracer_TraceQueryEnd_MissingContext(t *testing.T) {
+ tracer := &metadataDBTracer{}
+
+ // End trace without start - should not panic
+ ctx := context.Background()
+ endData := pgx.TraceQueryEndData{
+ Err: nil,
+ }
+
+ assert.NotPanics(t, func() {
+ tracer.TraceQueryEnd(ctx, nil, endData)
+ })
+}
diff --git a/go.mod b/go.mod
index bdff0ba68c..d4b319085a 100644
--- a/go.mod
+++ b/go.mod
@@ -344,7 +344,7 @@ require (
github.com/power-devops/perfstat v0.0.0-20221212215047-62379fc7944b // indirect
github.com/pquerna/cachecontrol v0.2.0 // indirect
github.com/pquerna/otp v1.5.0
- github.com/prometheus/client_golang v1.22.0 // indirect
+ github.com/prometheus/client_golang v1.22.0
github.com/prometheus/client_model v0.6.2 // indirect
github.com/prometheus/common v0.63.0 // indirect
github.com/prometheus/procfs v0.16.1 // indirect