Address review comments

Signed-off-by: Rohit Nayak <rohit@planetscale.com>

go/cmd/vtctldclient/command/vreplication/movetables/create.go

@@ -79,9 +79,14 @@ var (
 				return err
 			}
 
-			if len(createOptions.WorkflowOptions.GetShards()) > 0 && createOptions.WorkflowOptions.GetTenantId() == "" {
+			tenantId := createOptions.WorkflowOptions.GetTenantId()
+			if len(createOptions.WorkflowOptions.GetShards()) > 0 && tenantId == "" {
 				return fmt.Errorf("--shards specified, but not --tenant-id: you can only specify target shards for multi-tenant migrations")
 			}
+			if tenantId != "" && len(createOptions.SourceShards) > 0 {
+				return fmt.Errorf("cannot specify both --tenant-id (i.e. a multi-tenant migration) and --source-shards (i.e. a shard-by-shard migration)")
+			}
+
 			return nil
 		},
 		RunE: commandCreate,

go/cmd/vtctldclient/command/vreplication/movetables/movetables.go

@@ -47,9 +47,9 @@ func registerCommands(root *cobra.Command) {
 	create.Flags().StringSliceVar(&createOptions.ExcludeTables, "exclude-tables", nil, "Source tables to exclude from copying.")
 	create.Flags().BoolVar(&createOptions.NoRoutingRules, "no-routing-rules", false, "(Advanced) Do not create routing rules while creating the workflow. See the reference documentation for limitations if you use this flag.")
 	create.Flags().BoolVar(&createOptions.AtomicCopy, "atomic-copy", false, "(EXPERIMENTAL) A single copy phase is run for all tables from the source. Use this, for example, if your source keyspace has tables which use foreign key constraints.")
-	create.Flags().StringVar(&createOptions.WorkflowOptions.TenantId, "tenant-id", "", "(EXPERIMENTAL) The tenant ID to use for the MoveTables workflow into a multi-tenant keyspace.")
+	create.Flags().StringVar(&createOptions.WorkflowOptions.TenantId, "tenant-id", "", "(EXPERIMENTAL: Multi-tenant migrations only) The tenant ID to use for the MoveTables workflow into a multi-tenant keyspace.")
 	create.Flags().BoolVar(&createOptions.WorkflowOptions.StripShardedAutoIncrement, "remove-sharded-auto-increment", true, "If moving the table(s) to a sharded keyspace, remove any auto_increment clauses when copying the schema to the target as sharded keyspaces should rely on either user/application generated values or Vitess sequences to ensure uniqueness.")
-	create.Flags().StringSliceVar(&createOptions.WorkflowOptions.Shards, "shards", nil, "(Multi-tenant migrations only) Specify that vreplication streams should only be created on this subset of target shards. Warning: you should first ensure that all rows on the source route to the specified subset of target shards using your VIndex of choice or you could lose data during the migration.")
+	create.Flags().StringSliceVar(&createOptions.WorkflowOptions.Shards, "shards", nil, "(EXPERIMENTAL: Multi-tenant migrations only) Specify that vreplication streams should only be created on this subset of target shards. Warning: you should first ensure that all rows on the source route to the specified subset of target shards using your VIndex of choice or you could lose data during the migration.")
 	base.AddCommand(create)
 
 	opts := &common.SubCommandsOpts{

go/vt/vtctl/workflow/materializer.go

@@ -438,6 +438,11 @@ func (mz *materializer) buildMaterializer() error {
 	if err != nil {
 		return err
 	}
+
+	// For a multi-tenant migration, user can specify a subset of target shards to stream to, based
+	// on the vindex they have chosen. This is to optimize the number of streams: for example, if we
+	// have 256 shards and a tenant maps to a single shard we can avoid creating 255 unnecessary streams
+	// that would be filtered out by the vindex anyway.
 	var specifiedTargetShards []string
 	switch {
 	case mz.IsMultiTenantMigration():