Documentation
¶
Overview ¶
Package sdb is the API surface handed to Go scripts. A script is a plain Go file (package main) defining:
func Run(s *sdb.S) error
It can query any configured connection, loop with parameters, push results into the results view, and export in any supported format.
Index ¶
- func IsCanceled(err error) bool
- type Plan
- type PlanText
- type Result
- type S
- func (s *S) Canceled() bool
- func (s *S) Conns() []string
- func (s *S) Ctx() context.Context
- func (s *S) DB(conn string) (*sql.DB, error)
- func (s *S) Exec(conn, stmt string, args ...any) (int64, error)
- func (s *S) Explain(conn, stmt string, analyze bool) (*Plan, error)
- func (s *S) Export(r *Result, format, path string) error
- func (s *S) Print(format string, args ...any)
- func (s *S) Query(conn, query string, args ...any) (*Result, error)
- func (s *S) Show(r *Result)
- func (s *S) WithContext(ctx context.Context) *S
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsCanceled ¶
IsCanceled reports whether an error from Query or Exec is the user stopping the run, as opposed to a genuine failure — so a script can unwind quietly:
if err != nil {
if sdb.IsCanceled(err) {
return nil
}
return err
}
Types ¶
type Plan ¶
Plan is an explained statement: its steps (Root, Nodes), what it cost or took, and dbc's findings about it (Insights). See package explain.
type PlanText ¶
type PlanText = explain.TextOptions
PlanText shapes Plan.Text: width, the metric bars are sized by, color, and whether the findings are appended.
type S ¶
type S struct {
// contains filtered or unexported fields
}
S is the session handle passed to a script's Run function.
func New ¶
New builds a script session. show receives results pushed via Show; print receives Print output (results table / log pane in the TUI, stdout in headless mode).
func (*S) Ctx ¶
Ctx returns the session's context. Long-running scripts can select on s.Ctx().Done() (or check s.Canceled()) to bail out early.
func (*S) DB ¶
DB exposes the raw *database/sql.DB for a connection — the escape hatch for transactions, prepared statements, or anything else database/sql can do.
func (*S) Explain ¶
Explain describes how conn's database runs stmt, as the TUI's Ctrl+X and `dbc explain` do. analyze runs the statement to measure it: on Postgres a write is analyzed inside a transaction that is rolled back; on the other engines a write is explained but not run. It runs on its own session, not one the script shares with Query.
p, err := s.Explain("pg", "SELECT * FROM orders WHERE user_id = 42", true)
s.Print("%s", p.Text(sdb.PlanText{Insights: true}))
for _, in := range p.Insights { if in.Severity != "info" { … } }
func (*S) Export ¶
Export renders a result in the named format (csv|tsv|markdown|html|json|text) and writes it to path — or to the system clipboard when path is empty.
func (*S) Query ¶
Query runs a statement with parameters on the named connection and returns the result set. Use the placeholder style of the target driver ($1 for postgres/bytdb, ? for mysql/sqlite).
func (*S) WithContext ¶
WithContext attaches a cancellation context to the session and returns it. The host — not the script — sets this: when the user stops a run, the query in flight is aborted and every later Query or Exec fails immediately, so a looping script unwinds through its own error handling.
Source Files