sql-scope

sql-scope

Real-time SQL query monitor for Go applications. Wraps database/sql drivers to capture every query, then streams them to an interactive terminal UI over gRPC.

┌──────────────────────────────────────────────────────────────────────────────┐
│  Your Go app (database/sql)                                                  │
│        │                                                                     │
│        ▼                                                                     │
│  sql-scope driver wrapper ──► gRPC server (:9091)                            │
│        │                            │                                        │
│        ▼                            ▼                                        │
│  Real DB driver              sql-scope monitor (TUI)                         │
│  (pgx / mysql)                                                               │
└──────────────────────────────────────────────────────────────────────────────┘

Supports PostgreSQL (pgx) and MySQL (go-sql-driver/mysql).

Install

go install github.com/mickamy/sql-scope@latest

Or build from source:

git clone https://github.com/mickamy/sql-scope.git
cd sql-scope
make install

Quick Start

1. Instrument your application

import (
    "database/sql"

    _ "github.com/jackc/pgx/v5/stdlib" // or _ "github.com/go-sql-driver/mysql"

    "github.com/mickamy/sql-scope/scope"
    "github.com/mickamy/sql-scope/scope/driver"
)

func main() {
    ctx := context.Background()

    // Start the scope server (default port 9091)
    s, err := scope.New(ctx)
    // s, err := scope.New(ctx, scope.WithPort(9092))  // custom port
    if err != nil { log.Fatal(err) }
    defer s.Close()

    // Wrap your database driver
    name := driver.Wrap("pgx", s)       // PostgreSQL
    // name := driver.Wrap("mysql", s)   // MySQL

    // Use database/sql as usual
    db, err := sql.Open(name, dsn)
    // All queries are now captured and streamed.
}

2. Launch the monitor

sql-scope monitor localhost:9091

To enable EXPLAIN support, set the database DSN:

DATABASE_URL="postgres://user:pass@localhost/db" sql-scope monitor localhost:9091

TUI

List View

The default view shows all captured queries in real time.

• Transactions are automatically grouped and color-coded
• New events are followed automatically (disable by scrolling up)
• A preview panel below the list shows details of the selected item

Inspector View

A detailed view of a single query or transaction summary.

Shows: operation type, full query with syntax highlighting, arguments, duration, timestamp, rows affected, error, caller stack trace, and transaction ID.

Explain View

Shows the output of EXPLAIN or EXPLAIN ANALYZE with syntax highlighting and horizontal scrolling.

Clipboard

c copies the raw parameterized query (e.g. SELECT * FROM users WHERE id = $1).

C interpolates arguments into the query before copying (e.g. SELECT * FROM users WHERE id = 42). String arguments are automatically single-quoted; numbers, booleans, and NULL are left unquoted.

Both PostgreSQL-style ($1, $2) and MySQL-style (?) placeholders are supported.

EXPLAIN

Pressing x runs EXPLAIN on the selected query against your database. X runs EXPLAIN ANALYZE (actually executes the query).

Pressing e or E opens the query in your $EDITOR (default: vi) before running EXPLAIN, so you can tweak it first.

Requires DATABASE_URL (or a custom env var via --dsn-env):

sql-scope monitor localhost:9091 --dsn-env=MY_DSN

Captured Data

Every database/sql operation is captured:

Each event includes:

• SQL query text and arguments
• Execution duration
• Timestamp
• Rows affected
• Error (if any)
• Caller stack trace (filtered to application frames)
• Transaction ID (for grouping)

Examples

Complete working examples are in the example/ directory:

docker compose up -d   # Start PostgreSQL and MySQL

# PostgreSQL
DATABASE_URL="postgres://postgres:postgres@localhost:5432/db?sslmode=disable" \
  go run ./example/postgres

# MySQL
DATABASE_URL="root:root@tcp(localhost:3306)/db" \
  go run ./example/mysql

Then in another terminal:

DATABASE_URL="postgres://postgres:postgres@localhost:5432/db?sslmode=disable" \
  sql-scope monitor localhost:9091

CLI Reference

sql-scope monitor <scope-addr> [--dsn-env=ENV]
sql-scope version
sql-scope help

License

MIT