sdb

func (*S) Canceled ¶

func (s *S) Canceled() bool

Canceled reports whether the user has stopped this run.

func (*S) CatalogChanged ¶ added in v0.9.1

func (s *S) CatalogChanged(conn string) bool

CatalogChanged reports whether the session has run a statement that may change conn's catalog (sqlsplit.ChangesCatalog: CREATE, ALTER, DROP, RENAME, COMMENT, ATTACH, DETACH) — through Query, Exec, or what Copy and Writer run to ready a destination. The host asks it once the script has returned, to decide whether the sidebar should list the tables again. Statements run through DB's raw handle are out of its sight, as they are out of the DDL log's.

func (*S) Conns ¶

func (s *S) Conns() []string

Conns returns the configured connection names.

func (*S) Copy ¶ added in v0.9.0

func (s *S) Copy(src, dst, table string, opt CopyOpts) (CopyStats, error)

Copy copies table from connection src into connection dst:

st, err := s.Copy("prod", "local", "public.orders", sdb.CopyOpts{
	Create: true, Truncate: true, Where: "created_at >= now() - interval '7 days'",
})
s.Print("%s", st) // copied 48213 rows prod:public.orders → local:public.orders in 1.4s (direct COPY)

Postgres to Postgres without a Transform or Args streams COPY to COPY and never decodes a row; every other pairing goes row by row. Either way the destination is loaded in one transaction (with its Create and Truncate), so a failed or stopped copy leaves it as it was.

func (*S) Ctx ¶

func (s *S) Ctx() context.Context

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 ¶

func (s *S) DB(conn string) (*sql.DB, error)

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) ETLConn ¶ added in v0.13.0

func (s *S) ETLConn(name string) (etl.Conn, error)

ETLConn resolves a connection name to the etl package's view of it: the pool, opened on first use under the run's context, and its SQL dialect. Its Trace feeds the DDL log (LogDDL), so the CREATE TABLE a Copy makes or a Writer's Setup runs is logged as a script's own Exec of it would be.

func (*S) Exec ¶

func (s *S) Exec(conn, stmt string, args ...any) (int64, error)

Exec runs a non-query statement and returns the rows affected. Its server notices are printed as Query's are.

func (*S) Explain ¶

func (s *S) Explain(conn, stmt string, analyze bool) (*Plan, error)

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 ¶

func (s *S) Export(r *Result, format, path string) error

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. A relative path is in files_dir, as s.Path has it: "report.csv" is one file whether a shell, dbc web or a schedule runs the script. Missing directories are created, as csv.write creates them.

func (*S) ForFiles ¶ added in v0.13.0

func (s *S) ForFiles(dir string) pipeline.Host

ForFiles is the session as a pipeline run whose files_dir is dir sees it: the same session — its connections, context and output, and the Readers, Writers and catalog changes it keeps for the host (shared) — with Paths.FilesDir set to dir. pipeline.Run hands it to the run's nodes (pipeline.FilesHost), so a go.action or script.run node's s.Path and s.Export resolve where the run's file nodes do. The host's, not a script's: the session itself is returned when dir is already its own.

func (*S) LoadPipeline ¶ added in v0.13.0

func (s *S) LoadPipeline(name string) (*PipelineSpec, error)

LoadPipeline finds a pipeline the way RunPipelineNamed does and parses it.

func (*S) LogDDL ¶ added in v0.9.0

func (s *S) LogDDL() *S

LogDDL turns on the DDL log for the rest of the session: every data definition statement it runs (sqlsplit.IsDDL: CREATE, ALTER, DROP, TRUNCATE, RENAME, COMMENT, GRANT, REVOKE) is written to the script output, as Print does, the moment before it runs:

DDL warehouse: CREATE INDEX orders_user_idx ON orders (user_id)

That covers a script's Query and Exec and what Copy and Writer run to ready a destination (a Create's CREATE TABLE, Truncate, a Writer's Setup). Statements a script runs through DB's raw handle are out of its sight.

Logging before the statement, as Postgres's log_statement = 'ddl' does, rather than after it, puts a long CREATE INDEX or an ALTER stuck behind a lock in the log while it is still running. A Query or Exec that then fails adds a "DDL <conn> failed" line, since a script may carry on past the error; a failed Copy or Writer stops with an error naming the statement anyway.

script.Run turns this on for every script, whichever UI runs it. The session's other host, dbc copy, leaves it off. There is deliberately no way to turn it off again, so a script cannot opt out of its own log.

func (*S) Manager ¶ added in v0.13.0

func (s *S) Manager() *db.Manager

Manager is the connections the session runs on. For the host's helpers (a job runner builds its sessions over it), not for scripts.

func (*S) Path ¶ added in v0.13.0

func (s *S) Path(p string) string

Path is where a script's file p is, a relative p being in files_dir as a file node's is: os.Create(s.Path("out.csv")). "~/…" is under the home directory and an absolute path is left as written; a relative one is joined to the host's files_dir (Paths.FilesDir), so "out.csv" is one file whether the script runs from `dbc script` in a shell, the TUI, dbc web, a schedule or dbc.app — not one in each process's working directory. A script opens every file of its own through it (os.Create, os.Open, os.ReadFile, …); s.Export already does.

One result, not Env.Path's (string, error), so it goes straight into an os call: the one failure, a "~" path with no home directory to find, leaves p as written, and the open then fails naming it. With no files_dir set (a host that sets no Paths, a test) a relative p is left relative to the working directory, as before files_dir. In a go.action or script.run node, s is the run's session as the run sees it (ForFiles): its files_dir is the run's, so the node's own files land with the run's file nodes', even when a script ran the pipeline with a files_dir of its own (PipelineOpts.FilesDir).

func (*S) Paths ¶ added in v0.13.0

func (s *S) Paths() Paths

Paths is where the session resolves script and pipeline names.

func (*S) Print ¶

func (s *S) Print(format string, args ...any)

Print writes a Printf-style message to the script output.

func (*S) Query ¶

func (s *S) Query(conn, query string, args ...any) (*Result, error)

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).

Server notices the statement raises (Postgres RAISE NOTICE and its kin) are written to the script output, as Print does, before Query returns — whether or not the statement failed.

func (*S) Reader ¶ added in v0.9.0

func (s *S) Reader(conn, query string, args ...any) (*Reader, error)

Reader runs query on conn and streams its rows. Use the placeholder style of the connection's driver ($1 postgres/bytdb, ? mysql/sqlite).

func (*S) Release ¶ added in v0.9.0

func (s *S) Release()

Release closes every Reader and rolls back every Writer the script left open. The host calls it when the script's Run returns (or panics): a forgotten Writer would otherwise hold a connection and an open transaction — and its locks — for the rest of the process. It rolls back rather than commits, because only an explicit Close says the load is complete. Both are no-ops on what the script already closed.

func (*S) RunJob ¶ added in v0.13.0

func (s *S) RunJob(name string, params Params) (*JobRun, error)

RunJob runs the job called name — a file in the jobs directory (.json may be left off) or a built-in example — with params overriding its own, and waits for it to end. Stop (Ctrl+K) cancels it as it does a query. The run comes back however it ended; the error is non-nil when it did not succeed.

func (*S) RunPipeline ¶ added in v0.13.0

func (s *S) RunPipeline(p *Pipeline, opt PipelineOpts) (*RunStats, error)

RunPipeline runs a pipeline built with NewPipeline. Every fragment runs in order, each sink committing at its fragment's end; the stats come back complete even on error. Stop (Ctrl+K) cancels the run as it does a query.

func (*S) RunPipelineNamed ¶ added in v0.13.0

func (s *S) RunPipelineNamed(name string, opt PipelineOpts) (*RunStats, error)

RunPipelineNamed runs a saved pipeline: a file path, a name in the pipelines directory (.json optional), or a built-in example.

func (*S) RunPipelineSpec ¶ added in v0.13.0

func (s *S) RunPipelineSpec(spec *PipelineSpec, opt PipelineOpts) (*RunStats, error)

RunPipelineSpec runs a pipeline given as data (ParsePipeline, or a literal). A relative path in its file nodes is in the host's files_dir (Paths.FilesDir) unless opt.FilesDir names another directory, so a pipeline run from a script finds the files it finds when scheduled.

${run.trigger} is "script" unless opt.Run says otherwise, and ${run.id} a fresh id of the run's own (pipeline.RunID), as the jobs engine's runs have; no run record is written for it.

func (*S) Show ¶

func (s *S) Show(r *Result)

Show pushes a result to the results view (TUI) or prints it (headless).

func (*S) WithContext ¶

func (s *S) WithContext(ctx context.Context) *S

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.

func (*S) WithJobs ¶ added in v0.13.0

func (s *S) WithJobs(r JobRunner) *S

WithJobs sets the runner s.RunJob uses: the host's engine. The host sets it; a script does not.

func (*S) WithPaths ¶ added in v0.13.0

func (s *S) WithPaths(p Paths) *S

WithPaths tells the session where scripts and pipelines live, for running them by name. The host sets it; a script does not.

func (*S) Writer ¶ added in v0.9.0

func (s *S) Writer(conn, table string, cols []string, opt WriteOpts) (*Writer, error)

Writer starts a load into table on conn; rows passed to Write line up with cols. Nothing is visible to other sessions until Close commits.