text: change "instance" to "database server" for consistency

evanelias · evanelias · commit 5f7598e3ed8b · 2024-09-12T18:43:20.000-04:00
This commit tweaks the wording of logging, help text, and error messages to
prefer "database server" instead of "instance". Previously, a mix of these
two terms was used, which could cause confusion. We now prefer "database
server" (or equivalently "DB server") to refer to a copy of MySQL Server or
MariaDB Server running on a specific host and port. Although "instance" is
common terminology on cloud vendors ("RDS instance", "CloudSQL instance",
etc) overall that term seems less clear because e.g. an "EC2 instance" can
also be the client side / where Skeema runs from.

This change is being made now ahead of a planned new documentation page, which
will cover core concepts and terminology.

A few places intentionally still use "instance" even after this commit:

* The concurrent-instances option for `skeema push` remains as-is for
  backwards compatibility.
* The "-- instance: ..." comment in STDOUT output of `skeema diff` and
  `skeema push` remains as-is, since some users parse this text.
* Some internal-only error messages still use "instance", since the internal
  struct type tengo.Instance isn't being renamed.

The first two might change in a future major-version bump (e.g. Skeema v2)
if/when that happens, but no concrete plans at this time.

This commit also adjusts some other unrelated help text, for example now
preferring "command-line arg" over "CLI arg".
diff --git a/README.md b/README.md
@@ -17,7 +17,7 @@ Skeema supports a pull-request-based workflow for schema change submission, revi
 
 ## Products and downloads
 
-This repo is the free open source Community edition of the Skeema CLI. The Community edition supports management of [**tables**](https://www.skeema.io/docs/features/tables/) and [**routines**](https://www.skeema.io/docs/features/routines/) (procs/funcs). Builds are provided for Linux and MacOS.
+This repo is the free open source Community edition of the Skeema command-line tool. The Community edition supports management of [**tables**](https://www.skeema.io/docs/features/tables/) and [**routines**](https://www.skeema.io/docs/features/routines/) (procs/funcs). Builds are provided for Linux and MacOS.
 
 The paid [Premium edition](https://www.skeema.io/download/) of the Skeema CLI adds support for managing [**views**](https://www.skeema.io/docs/features/views/), [**triggers**](https://www.skeema.io/docs/features/triggers/), and [**events**](https://www.skeema.io/docs/features/events/). It also includes a native **Windows build**, built-in [**SSH tunnel**](https://www.skeema.io/docs/features/ssh/) functionality, [**seed data**](https://www.skeema.io/docs/features/seeddata/) management, and many other improvements.
 
@@ -27,7 +27,7 @@ For download links and more information, visit [skeema.io](https://www.skeema.io
 
 Page | Description
 --- | ---
-[Installation](https://www.skeema.io/docs/install/) | How to install the CLI
+[Installation](https://www.skeema.io/docs/install/) | How to install the Skeema CLI tool
 [Getting started](https://www.skeema.io/docs/examples/) | Usage examples and screencasts
 [Requirements](https://www.skeema.io/docs/requirements/) | Supported database systems and required database privileges
 [Features](https://www.skeema.io/docs/features/) | How Skeema interacts with each type of database object, and various feature-specific topics
@@ -37,7 +37,7 @@ Page | Description
 [Schema change workflow](https://www.skeema.io/docs/workflow/) | Recommended flow for pull-request-driven schema changes
 [Pipelines and automation](https://www.skeema.io/docs/automation/) | Integrating Skeema into automated workflows
 [Recipes](https://www.skeema.io/docs/recipes/) | Using Skeema to achieve common schema management tasks
-[FAQ](https://www.skeema.io/docs/faq/) | Frequently asked questions about the Skeema CLI
+[FAQ](https://www.skeema.io/docs/faq/) | Frequently asked questions about Skeema
 
 ## Credits
 
diff --git a/cmd_add_env.go b/cmd_add_env.go
@@ -55,12 +55,12 @@ func AddEnvHandler(cfg *mybase.Config) error {
 	// that checks connectivity.
 	var inst *tengo.Instance
 	if !cfg.OnCLI("host") {
-		return NewExitValue(CodeBadConfig, "`skeema add-environment` requires --host to be supplied on CLI")
+		return NewExitValue(CodeBadConfig, "`skeema add-environment` requires --host to be supplied on command-line")
 	}
 	if instances, err := dir.Instances(); err != nil {
 		return err
 	} else if len(instances) == 0 {
-		return NewExitValue(CodeBadConfig, "Command line did not specify which instance to connect to")
+		return NewExitValue(CodeBadConfig, "Sharding configuration for host (or host-wrapper) yielded an empty list of database servers")
 	} else {
 		inst = instances[0]
 	}
diff --git a/cmd_diff.go b/cmd_diff.go
@@ -5,12 +5,12 @@ import (
 )
 
 func init() {
-	summary := "Compare a DB instance's schemas to the filesystem"
-	desc := "Compares the schemas on database instance(s) to the corresponding filesystem " +
+	summary := "Compare a DB server's schemas to the filesystem"
+	desc := "Compares the schemas on database server(s) to the corresponding filesystem " +
 		"representation of them. The output is a series of DDL commands that, if run on " +
-		"the instance, would cause the instances' schemas to now match the definitions " +
+		"the DB server, would cause its schemas to now match the definitions " +
 		"from the filesystem.\n\n" +
-		"You may optionally pass an environment name as a CLI arg. This will affect " +
+		"You may optionally pass an environment name as a command-line arg. This will affect " +
 		"which section of .skeema config files is used for processing. For example, " +
 		"running `skeema diff staging` will apply config directives from the " +
 		"[staging] section of config files, as well as any sectionless directives at the " +
@@ -46,7 +46,7 @@ func clonePushOptionsToDiff() {
 	descRewrites := map[string]string{
 		"allow-unsafe":    "Permit generating ALTER or DROP operations that are potentially destructive",
 		"alter-wrapper":   "Output ALTER TABLEs as shell commands rather than just raw DDL; see manual for template vars",
-		"brief":           "Don't output DDL to STDOUT; instead output list of instances with at least one difference",
+		"brief":           "Don't output DDL to STDOUT; instead output list of database servers with at least one difference",
 		"safe-below-size": "Always permit generating destructive operations for tables below this size in bytes",
 	}
 	hiddenRewrites := map[string]bool{
diff --git a/cmd_format.go b/cmd_format.go
@@ -15,9 +15,9 @@ func init() {
 	summary := "Normalize format of filesystem representation of database objects"
 	desc := "Reformats the filesystem representation of database objects to match the canonical " +
 		"format shown in SHOW CREATE.\n\n" +
-		"This command relies on accessing database instances to test the SQL DDL in a " +
+		"This command relies on accessing a database server to test the SQL DDL in a " +
 		"temporary location. See the --workspace option for more information.\n\n" +
-		"You may optionally pass an environment name as a CLI arg. This will affect " +
+		"You may optionally pass an environment name as a command-line arg. This will affect " +
 		"which section of .skeema config files is used for workspace selection. For " +
 		"example, running `skeema format staging` will " +
 		"apply config directives from the [staging] section of config files, as well as " +
diff --git a/cmd_init.go b/cmd_init.go
@@ -14,13 +14,13 @@ import (
 )
 
 func init() {
-	summary := "Save a DB instance's schemas to the filesystem"
-	desc := "Creates a filesystem representation of the schemas on a DB instance. " +
-		"For each schema on the instance (or just the single schema specified by " +
+	summary := "Save a DB server's schemas to the filesystem"
+	desc := "Creates a filesystem representation of the schemas on a database server. " +
+		"For each schema on the DB server (or just the single schema specified by " +
 		"--schema), a subdir with a .skeema config file will be created. Each directory " +
 		"will be populated with .sql files containing CREATE statements for every " +
 		"table and routine in the schema.\n\n" +
-		"You may optionally pass an environment name as a CLI arg. This will affect " +
+		"You may optionally pass an environment name as a command-line arg. This will affect " +
 		"which section of .skeema config files the host-related options are written to. " +
 		"For example, running `skeema init staging` will add config directives to the " +
 		"[staging] section of config files. If no environment name is supplied, the " +
@@ -74,7 +74,7 @@ func InitHandler(cfg *mybase.Config) error {
 	if err != nil {
 		return err
 	} else if inst == nil {
-		return NewExitValue(CodeBadConfig, "Command line did not specify which instance to connect to")
+		return NewExitValue(CodeBadConfig, "Command line did not specify which database server to connect to")
 	}
 
 	// Build list of schemas
@@ -87,7 +87,7 @@ func InitHandler(cfg *mybase.Config) error {
 		return NewExitValue(CodeFatalError, "Cannot examine schemas on %s: %s", inst, err)
 	}
 	if onlySchema != "" && len(schemas) == 0 {
-		return NewExitValue(CodeBadConfig, "Schema %s does not exist on instance %s", onlySchema, inst)
+		return NewExitValue(CodeBadConfig, "Schema %s does not exist on database server %s", onlySchema, inst)
 	}
 
 	// Write host option file
diff --git a/cmd_lint.go b/cmd_lint.go
@@ -21,11 +21,11 @@ func init() {
 		"generate an error, a warning, or be ignored entirely. Statements that contain " +
 		"invalid SQL, or otherwise return an error from the database, are always flagged " +
 		"as linter errors.\n\n" +
-		"By default, this command also reformats statements to their canonical form, " +
+		"By default, this command also reformats CREATE statements to their canonical form, " +
 		"just like `skeema format`.\n\n" +
-		"This command relies on accessing database instances to test the SQL DDL in a " +
+		"This command relies on accessing a database server to test the SQL DDL in a " +
 		"temporary location. See the --workspace option for more information.\n\n" +
-		"You may optionally pass an environment name as a CLI arg. This will affect " +
+		"You may optionally pass an environment name as a command-line arg. This will affect " +
 		"which section of .skeema config files is used for linter configuration and " +
 		"workspace selection. For example, running `skeema lint staging` will " +
 		"apply config directives from the [staging] section of config files, as well as " +
diff --git a/cmd_pull.go b/cmd_pull.go
@@ -16,10 +16,10 @@ import (
 func init() {
 	summary := "Update the filesystem representation of schemas"
 	desc := "Updates the existing filesystem representation of the schemas on a DB " +
-		"instance. Use this command when changes have been applied to the database " +
+		"server. Use this command when changes have been applied to the database " +
 		"manually or outside of Skeema, in order to make the filesystem representation " +
 		"reflect those changes.\n\n" +
-		"You may optionally pass an environment name as a CLI arg. This will affect " +
+		"You may optionally pass an environment name as a command-line arg. This will affect " +
 		"which section of .skeema config files is used for processing. For example, " +
 		"running `skeema pull staging` will apply config directives from the " +
 		"[staging] section of config files, as well as any sectionless directives at the " +
diff --git a/cmd_push.go b/cmd_push.go
@@ -15,11 +15,11 @@ import (
 
 func init() {
 	summary := "Alter objects on DBs to reflect the filesystem representation"
-	desc := "Modifies the schemas on database instance(s) to match the corresponding " +
+	desc := "Modifies the schemas on database server(s) to match the corresponding " +
 		"filesystem representation of them. This essentially performs the same diff logic " +
 		"as `skeema diff`, but then actually runs the generated DDL. You should generally " +
 		"run `skeema diff` first to see what changes will be applied.\n\n" +
-		"You may optionally pass an environment name as a CLI arg. This will affect " +
+		"You may optionally pass an environment name as a command-line arg. This will affect " +
 		"which section of .skeema config files is used for processing. For example, " +
 		"running `skeema push staging` will apply config directives from the " +
 		"[staging] section of config files, as well as any sectionless directives at the " +
@@ -62,9 +62,9 @@ func init() {
 	)
 
 	cmd.AddOptions("sharding",
-		mybase.BoolOption("first-only", '1', false, "For dirs mapping to multiple instances or schemas, just run against the first per dir"),
+		mybase.BoolOption("first-only", '1', false, "For dirs mapping to multiple hosts or schemas, only run against the first target per dir"),
 		mybase.BoolOption("brief", 'q', false, "<overridden by diff command>").Hidden(),
-		mybase.StringOption("concurrent-instances", 'c', "1", "Perform operations on this number of instances concurrently"),
+		mybase.StringOption("concurrent-instances", 'c', "1", "Perform operations on this number of database servers concurrently"),
 	)
 
 	workspace.AddCommandOptions(cmd)
diff --git a/internal/applier/target.go b/internal/applier/target.go
@@ -120,7 +120,7 @@ func instancesForDir(dir *fs.Dir) (instances []*tengo.Instance, skipCount int) {
 	if dir.Config.GetBool("first-only") {
 		onlyInstance, err := dir.FirstInstance()
 		if onlyInstance == nil && err == nil {
-			log.Warnf("Skipping %s: directory maps to an empty list of instances", dir)
+			log.Warnf("Skipping %s: directory maps to an empty list of database servers", dir)
 			if dir.Config.Changed("host-wrapper") {
 				log.Warnf("The host-wrapper option controls which hosts this directory maps to, but the executed script returned no hostnames.\n")
 			}
@@ -139,7 +139,7 @@ func instancesForDir(dir *fs.Dir) (instances []*tengo.Instance, skipCount int) {
 		log.Errorf("Skipping %s: %s\n", dir, err)
 		return nil, 1
 	} else if len(rawInstances) == 0 {
-		log.Warnf("Skipping %s: directory maps to an empty list of instances", dir)
+		log.Warnf("Skipping %s: directory maps to an empty list of database servers", dir)
 		if dir.Config.Changed("host-wrapper") {
 			log.Warnf("The host-wrapper option controls which hosts this directory maps to, but the executed script returned no hostnames.\n")
 		}
@@ -175,7 +175,7 @@ func targetsForLogicalSchema(logicalSchema *fs.LogicalSchema, dir *fs.Dir, insta
 		for _, other := range instances[1:] {
 			if compare := other.NameCaseMode(); compare != tengo.NameCaseUnknown && compare != lctn {
 				log.Errorf("Skipping %s: all database servers mapped by the same subdirectory and environment must have the same value for lower_case_table_names.", dir)
-				log.Errorf("Instance %s has lower_case_table_names=%d, but instance %s has lower_case_table_names=%d.", instances[0], lctn, other, compare)
+				log.Errorf("Database server %s has lower_case_table_names=%d, while %s has lower_case_table_names=%d.", instances[0], lctn, other, compare)
 				return nil, len(instances)
 			}
 		}
diff --git a/internal/fs/dir.go b/internal/fs/dir.go
@@ -356,7 +356,7 @@ func (dir *Dir) FirstInstance() (*tengo.Instance, error) {
 	if len(instances) == 1 {
 		return nil, fmt.Errorf("Unable to connect to %s for %s: %s", instances[0], dir, lastErr)
 	}
-	return nil, fmt.Errorf("Unable to connect to any of %d instances for %s; last error %s", len(instances), dir, lastErr)
+	return nil, fmt.Errorf("Unable to connect to any of %d database servers for %s; last error %s", len(instances), dir, lastErr)
 }
 
 // ValidateInstance confirms the supplied instance is (or has been) reachable,
@@ -385,13 +385,13 @@ func (dir *Dir) ValidateInstance(instance *tengo.Instance) error {
 	confFlavor := tengo.ParseFlavor(dir.Config.Get("flavor"))
 	if instFlavor.Known() {
 		if confFlavor != tengo.FlavorUnknown && instFlavor.Family() != confFlavor.Family() && !dir.Config.OnCLI("flavor") {
-			log.Warnf("Instance %s actual flavor %s differs from dir %s configured flavor %s\nIf you have recently upgraded your database server version, consider using `skeema pull` to update your schema definitions.", instance, instFlavor, dir, confFlavor)
+			log.Warnf("Database server %s actual flavor %s differs from dir %s configured flavor %s\nIf you have recently upgraded your database server version, consider using `skeema pull` to update your schema definitions.", instance, instFlavor, dir, confFlavor)
 		}
 		if instFlavor.TooNew() {
-			log.Warnf("Instance %s flavor %s is newer than this version of Skeema. To ensure correct behavior, consider upgrading to a more recent release of Skeema.", instance, instFlavor)
+			log.Warnf("Database server %s flavor %s is newer than this version of Skeema. To ensure correct behavior, consider upgrading to a more recent release of Skeema.", instance, instFlavor)
 		}
 	} else if confFlavor.Known() {
-		log.Debugf("Instance %s flavor cannot be parsed; using dir %s configured flavor %s instead", instance, dir, confFlavor)
+		log.Debugf("Database server %s flavor cannot be parsed; using dir %s configured flavor %s instead", instance, dir, confFlavor)
 		instance.SetFlavor(confFlavor)
 	} else {
 		log.Warnf(`Unable to determine database server vendor/version of %s. To set manually, use the "flavor" option in %s`, instance, filepath.Join(dir.Path, ".skeema"))
diff --git a/internal/util/config.go b/internal/util/config.go
@@ -34,7 +34,7 @@ func AddGlobalOptions(cmd *mybase.Command) {
 		mybase.StringOption("user", 'u', "root", "Username to connect to database host"),
 		mybase.StringOption("password", 'p', "$MYSQL_PWD", "Password for database user; omit value to prompt from TTY").ValueOptional(),
 		mybase.StringOption("host-wrapper", 'H', "", "External bin to shell out to for host lookup; see manual for template vars"),
-		mybase.StringOption("connect-options", 'o', "", "Comma-separated session options to set upon connecting to each database instance"),
+		mybase.StringOption("connect-options", 'o', "", "Comma-separated session options to set upon connecting to each database server"),
 		mybase.StringOption("ignore-schema", 0, "", "Ignore schemas that match regex"),
 		mybase.StringOption("ignore-table", 0, "", "Ignore tables that match regex"),
 		mybase.StringOption("ignore-proc", 0, "", "Ignore stored procedures that match regex"),
diff --git a/internal/workspace/localdocker.go b/internal/workspace/localdocker.go
@@ -139,9 +139,9 @@ func NewLocalDocker(opts Options) (_ *LocalDocker, retErr error) {
 
 	lockName := fmt.Sprintf("skeema.%s", ld.schemaName)
 	if ld.releaseLock, err = getLock(ld.d.Instance, lockName, opts.LockTimeout); err != nil {
-		return nil, fmt.Errorf("Unable to obtain workspace lock on Dockerized instance %s: %s\n"+
+		return nil, fmt.Errorf("Unable to obtain workspace lock on database container %s: %w\n"+
 			"This may happen when running multiple copies of Skeema concurrently from the same client machine, in which case configuring --temp-schema differently for each copy on the command-line may help.\n"+
-			"It can also happen when operating across many shards with a high value for concurrent-instances; if so, either lower concurrent-instances, or enable skip-verify to resolve this.",
+			"It can also happen when operating across many shards with a high value for concurrent-instances. If so, either lower concurrent-instances, or enable skip-verify to resolve this.",
 			ld.d.Instance, err)
 	}
 	// If this function returns an error, don't continue to hold the lock

Original file line number	Diff line number	Diff line change
`@@ -356,7 +356,7 @@ func (dir Dir) FirstInstance() (tengo.Instance, error) {`
`356`	`356`	`if len(instances) == 1 {`
`357`	`357`	`return nil, fmt.Errorf("Unable to connect to %s for %s: %s", instances[0], dir, lastErr)`
`358`	`358`	`}`
`359`		`- return nil, fmt.Errorf("Unable to connect to any of %d instances for %s; last error %s", len(instances), dir, lastErr)`
	`359`	`+ return nil, fmt.Errorf("Unable to connect to any of %d database servers for %s; last error %s", len(instances), dir, lastErr)`
`360`	`360`	`}`
`361`	`361`
`362`	`362`	`// ValidateInstance confirms the supplied instance is (or has been) reachable,`
`@@ -385,13 +385,13 @@ func (dir Dir) ValidateInstance(instance tengo.Instance) error {`
`385`	`385`	`confFlavor := tengo.ParseFlavor(dir.Config.Get("flavor"))`
`386`	`386`	`if instFlavor.Known() {`
`387`	`387`	`if confFlavor != tengo.FlavorUnknown && instFlavor.Family() != confFlavor.Family() && !dir.Config.OnCLI("flavor") {`
`388`		- log.Warnf("Instance %s actual flavor %s differs from dir %s configured flavor %s\nIf you have recently upgraded your database server version, consider using `skeema pull` to update your schema definitions.", instance, instFlavor, dir, confFlavor)
	`388`	+ log.Warnf("Database server %s actual flavor %s differs from dir %s configured flavor %s\nIf you have recently upgraded your database server version, consider using `skeema pull` to update your schema definitions.", instance, instFlavor, dir, confFlavor)
`389`	`389`	`}`
`390`	`390`	`if instFlavor.TooNew() {`
`391`		`- log.Warnf("Instance %s flavor %s is newer than this version of Skeema. To ensure correct behavior, consider upgrading to a more recent release of Skeema.", instance, instFlavor)`
	`391`	`+ log.Warnf("Database server %s flavor %s is newer than this version of Skeema. To ensure correct behavior, consider upgrading to a more recent release of Skeema.", instance, instFlavor)`
`392`	`392`	`}`
`393`	`393`	`} else if confFlavor.Known() {`
`394`		`- log.Debugf("Instance %s flavor cannot be parsed; using dir %s configured flavor %s instead", instance, dir, confFlavor)`
	`394`	`+ log.Debugf("Database server %s flavor cannot be parsed; using dir %s configured flavor %s instead", instance, dir, confFlavor)`
`395`	`395`	`instance.SetFlavor(confFlavor)`
`396`	`396`	`} else {`
`397`	`397`	log.Warnf(`Unable to determine database server vendor/version of %s. To set manually, use the "flavor" option in %s`, instance, filepath.Join(dir.Path, ".skeema"))