Documentation
¶
Overview ¶
Package tutorial is the interactive companion to docs/scripting-and-etl-tutorial.md: the lessons as data, the workspace files they write, and the checks that say whether a lesson worked. `dbc tutorial` (tutorialcmd.go) is its command line.
tutorial/
tutorial.go ◄─ types, the embedded workspace, init, detection
lessons.go ◄─ the lessons, one per doc section (§0 … §12)
checks.go ◄─ check helpers: row counts, files, clean runs
flow.go ◄─ show / run / check a lesson, the status list
runner.go ◄─ Runner: how a lesson runs dbc (a child process)
workspace/ ◄─ the files, byte for byte as the doc shows them
Everything a lesson does goes through dbc itself, run as a child process in the workspace (see Runner). So `--run` does exactly what the learner would type, and a check reads state the same way a learner would (`dbc -t json "SELECT …"`), not through dbc's internals.
Index ¶
- Constants
- Variables
- func CheckLesson(e *Env, l Lesson, w io.Writer) bool
- func CheckWorkspace(dir string) error
- func CommandLine(args []string) string
- func File(name string) ([]byte, error)
- func FileNames() []string
- func Init(dir string, force bool, w io.Writer) error
- func Run(e *Env, l Lesson, force bool, w, errw io.Writer) bool
- func Show(w io.Writer, dir string, l Lesson, withFiles bool)
- func Status(e *Env, inWorkspace bool, w io.Writer) bool
- type Check
- type Command
- type Env
- type Lesson
- type Runner
- type Written
Constants ¶
const DocPath = "docs/scripting-and-etl-tutorial.md"
DocPath is the tutorial's Markdown, relative to the repo root.
const DocURL = "https://github.com/rohanthewiz/dbc/blob/main/" + DocPath
DocURL is the doc on GitHub, for a binary installed without a checkout.
Variables ¶
var Dirs = []string{"scripts", "pipelines", "jobs", "plugins", "data", "runs"}
Dirs are the workspace's directories, made by Init so dbc's listings (`dbc scripts`, `dbc pipelines`) have somewhere to look from the start. They match the *_dir settings in workspace/dbc.toml.
var ErrNotWorkspace = errors.New("not a tutorial workspace")
ErrNotWorkspace says dir is not a tutorial workspace.
Functions ¶
func CheckLesson ¶
CheckLesson runs l's checks and prints each one, ✓ or ✗ with what was found and the hint. A lesson with no checks (the UIs, the pitfalls) says so and passes.
func CheckWorkspace ¶
CheckWorkspace says whether dir is a tutorial workspace: a dbc.toml that defines the two connections every lesson uses. Any other dbc.toml is someone's real config, and a lesson must not run against it. A plain error wrapping ErrNotWorkspace, since its text is shown to the learner; a config that can't be read is a real failure and gets serr's fields.
func CommandLine ¶
CommandLine is args as the learner would type them after "dbc", quoted for a POSIX shell where needed.
func FileNames ¶
func FileNames() []string
FileNames lists every embedded workspace file, slash-separated.
func Init ¶
Init makes dir a tutorial workspace: lesson 0's files and the empty directories. It reports each file on w.
func Run ¶
Run does lesson l for the learner: warns when an earlier lesson isn't done, writes the lesson's missing files, runs its commands with their output streamed through (each echoed as "$ dbc …" first), then checks it. A lesson whose checks already pass is not run again unless force: some commands fail a second time on purpose (§0's seed, §4's copy). force also replaces files already there. It reports whether the lesson ended with every check passing.
Types ¶
type Check ¶
type Check struct {
What string // "warehouse has 6 orders"
Hint string // what to do when it fails
Test func(e *Env) error // nil = passed; the error says what was found
}
Check is one thing a lesson must leave behind.
type Command ¶
type Command struct {
Args []string
// ExpectFail marks a command that fails on purpose to show something
// (§4's copy into a full table shows the one-transaction load). Its
// non-zero exit does not stop the lesson; a zero exit is reported.
ExpectFail bool
// Note says why the command is there; printed after it.
Note string
}
Command is one dbc invocation a lesson runs: Args after "dbc".
type Env ¶
type Env struct {
Ctx context.Context // canceled on Ctrl+C
Dir string // the workspace
Dbc Runner // runs dbc there
}
Env is what a check or a run works in.
type Lesson ¶
type Lesson struct {
N int // the doc's section number (§N)
Title string // the doc's heading after "N. ", exactly
Summary string // a few lines: what the lesson teaches
Files []string // workspace files the lesson adds, slash-separated
Commands []Command // what to type, in order
Checks []Check // the state the lesson leaves; none = nothing to check
}
Lesson is one section of the tutorial.
func Lessons ¶
func Lessons() []Lesson
Lessons is the tutorial, one lesson per doc section. Titles are the doc's headings exactly (TestLessonsMatchDocHeadings), and Files are the embedded copies of its code blocks (TestWorkspaceMatchesDoc).
Commands are the doc's, in an order that works on a fresh workspace: §6 runs the pipeline before it previews one fragment, because that fragment's lookup reads a table the earlier fragment writes (the doc's own warning). Checks look at state only (tables, files, run records), never at output text, which carries timings and run ids.
type Runner ¶
type Runner func(ctx context.Context, dir string, args []string, stdout, stderr io.Writer) (code int, err error)
Runner runs dbc with args in dir, its output to stdout and stderr, and returns its exit code. err is for a dbc that could not be started at all; a dbc that ran and failed is a non-zero code with a nil err.
The command passes ExecRunner; the unit tests pass a fake that answers from a table, so lessons and checks are tested without a database.
func ExecRunner ¶
ExecRunner runs the dbc binary at bin as a child process with its working directory set to the workspace. That cwd is what makes the workspace's ./dbc.toml the config (dbc's resolution: --config, else ./dbc.toml, else ~/.config/dbc/config.toml), so the child runs exactly what the learner would type there. env nil = this process's environment.
Running in process instead would not work: dbc's headless paths end with os.Exit (fail, usage), and the config is found from the cwd.
Source Files