diff --git a/AGENTS.md b/AGENTS.md index 87076572..57565f8e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ PlanetScale is a serverless database platform for **MySQL** (via Vitess), **Post On Vitess/MySQL, schema changes ship via **deploy requests**: online, non-blocking migrations you review and then deploy. -Many commands are engine-specific, and some operations use different commands per engine. Schema changes: Vitess/MySQL uses `deploy-request`; Postgres and Neki branches apply DDL directly. Access: Vitess/MySQL uses `password`; Postgres and Neki use `role`. Resize: Vitess/MySQL uses `keyspace resize`; Postgres uses `branch resize`; Neki uses `branch config-profile`, `router`, and `shard`. Vitess/MySQL-only: `deploy-request`, `keyspace` (including `keyspace create-external`), `branch vtctld move-tables`, `connect`, `password`. `pscale workflow` will be deprecated soon; use `pscale branch vtctld move-tables` to move tables. Postgres-only: `traffic-control`, branch `switchover`/`parameters`, and `import d1`. Postgres and Neki: `role`, branch `maintenance`. Neki-only: `branch shard`, `config-profile`, `router`, `sidecar`, `admin`, `data-topology`, `changes`. The rest (`database`, `branch`, `sql`, `shell`, `insights`, `metrics`, `backup`, `org`, `auth`, `api`) work on all three. +Many commands are engine-specific, and some operations use different commands per engine. Schema changes: Vitess/MySQL uses `deploy-request`; Postgres and Neki branches apply DDL directly. Access: Vitess/MySQL uses `password`; Postgres and Neki use `role`. Resize: Vitess/MySQL uses `keyspace resize`; Postgres uses `branch resize`; Neki uses `branch config-profile`, `router`, and `shard`. Vitess/MySQL-only: `deploy-request`, `keyspace` (including `keyspace create-external`), `branch vtctld move-tables`, `connect`, `password`. `pscale workflow` is deprecated; use `pscale branch vtctld move-tables` to move tables. Postgres-only: `traffic-control`, branch `switchover`/`parameters`, and `import d1`. Postgres and Neki: `role`, branch `maintenance`. Neki-only: `branch shard`, `config-profile`, `router`, `sidecar`, `admin`, `data-topology`, `changes`. The rest (`database`, `branch`, `sql`, `shell`, `insights`, `metrics`, `backup`, `org`, `auth`, `api`) work on all three. When a database is "weird" (slow, erroring, locked, bloated): @@ -479,7 +479,7 @@ External create required flags: `--host`, `--source-database`, `--username`, `-- ## Vitess MoveTables -Copy tables between keyspaces with `pscale branch vtctld move-tables`. `pscale workflow` will be deprecated soon; prefer `move-tables` for new work. JSON output includes `next_steps` — follow those commands. Typical order: create the target keyspace (`keyspace create` or `keyspace create-external`), create the workflow, poll `status`, switch replica traffic, then primary traffic (ask the user first), then `complete --dry-run` and `complete` after approval. Create with `--auto-start=false` to leave streams stopped, then `start` when you are ready. +Copy tables between keyspaces with `pscale branch vtctld move-tables`. `pscale workflow` is deprecated; use `move-tables` instead. JSON output includes `next_steps` — follow those commands. Typical order: create the target keyspace (`keyspace create` or `keyspace create-external`), create the workflow, poll `status`, switch replica traffic, then primary traffic (ask the user first), then `complete --dry-run` and `complete` after approval. Create with `--auto-start=false` to leave streams stopped, then `start` when you are ready. `--workflow` is the workflow name you choose. `--source-keyspace` and `--target-keyspace` are required on create. Pass `--tables t1,t2` or `--all-tables` (mutually exclusive). `list` without `--target-keyspace` returns workflows in every keyspace on the branch. diff --git a/internal/cmd/branch/vtctld/list_tablets.go b/internal/cmd/branch/vtctld/list_tablets.go index 333a0404..3e0c6c18 100644 --- a/internal/cmd/branch/vtctld/list_tablets.go +++ b/internal/cmd/branch/vtctld/list_tablets.go @@ -17,9 +17,10 @@ func ListTabletsCmd(ch *cmdutil.Helper) *cobra.Command { } cmd := &cobra.Command{ - Use: "list-tablets ", - Short: "List tablets for a branch, grouped by keyspace and shard", - Args: cmdutil.RequiredArgs("database", "branch"), + Use: "list-tablets ", + Hidden: true, + Short: "List tablets for a branch, grouped by keyspace and shard", + Args: cmdutil.RequiredArgs("database", "branch"), RunE: func(cmd *cobra.Command, args []string) error { ctx := cmd.Context() database, branch := args[0], args[1] diff --git a/internal/cmd/branch/vtctld/lookup_vindex.go b/internal/cmd/branch/vtctld/lookup_vindex.go index 735a28ed..95807c5c 100644 --- a/internal/cmd/branch/vtctld/lookup_vindex.go +++ b/internal/cmd/branch/vtctld/lookup_vindex.go @@ -11,8 +11,9 @@ import ( func LookupVindexCmd(ch *cmdutil.Helper) *cobra.Command { cmd := &cobra.Command{ - Use: "lookup-vindex ", - Short: "Manage Lookup Vindex operations", + Use: "lookup-vindex ", + Short: "Manage Lookup Vindex operations", + Hidden: true, } cmd.AddCommand(LookupVindexCreateCmd(ch)) diff --git a/internal/cmd/branch/vtctld/materialize.go b/internal/cmd/branch/vtctld/materialize.go index 265ed679..9da8217a 100644 --- a/internal/cmd/branch/vtctld/materialize.go +++ b/internal/cmd/branch/vtctld/materialize.go @@ -12,8 +12,9 @@ import ( func MaterializeCmd(ch *cmdutil.Helper) *cobra.Command { cmd := &cobra.Command{ - Use: "materialize ", - Short: "Manage Materialize workflows", + Use: "materialize ", + Short: "Manage Materialize workflows", + Hidden: true, } cmd.AddCommand(MaterializeCreateCmd(ch)) diff --git a/internal/cmd/branch/vtctld/planned_reparent.go b/internal/cmd/branch/vtctld/planned_reparent.go index a1129605..6c896965 100644 --- a/internal/cmd/branch/vtctld/planned_reparent.go +++ b/internal/cmd/branch/vtctld/planned_reparent.go @@ -27,8 +27,9 @@ func PlannedReparentShardCmd(ch *cmdutil.Helper) *cobra.Command { } cmd := &cobra.Command{ - Use: "planned-reparent-shard ", - Short: "Reparent a shard to a new primary", + Use: "planned-reparent-shard ", + Hidden: true, + Short: "Reparent a shard to a new primary", Long: `Reparent a shard to a new primary using Vitess PlannedReparentShard. Both the old and new primaries must be up and running. diff --git a/internal/cmd/branch/vtctld/vtctld.go b/internal/cmd/branch/vtctld/vtctld.go index 7bd34145..d1bd1471 100644 --- a/internal/cmd/branch/vtctld/vtctld.go +++ b/internal/cmd/branch/vtctld/vtctld.go @@ -11,7 +11,6 @@ func VtctldCmd(ch *cmdutil.Helper) *cobra.Command { Aliases: []string{"vtctld"}, Short: "Run vtctl commands against a branch", Long: "Run vtctl commands against a branch. This command is only supported for Vitess databases.", - Hidden: true, } cmd.AddCommand(MaterializeCmd(ch)) diff --git a/internal/cmd/dataimports/dataimports.go b/internal/cmd/dataimports/dataimports.go index 82e36674..42b3691d 100644 --- a/internal/cmd/dataimports/dataimports.go +++ b/internal/cmd/dataimports/dataimports.go @@ -5,14 +5,16 @@ import ( "github.com/spf13/cobra" ) +const deprecation = "import MySQL databases with \"pscale keyspace create-external\" and \"pscale branch vtctl move-tables\" instead. See https://planetscale.com/docs/vitess/imports/database-imports for more information." + // DataImportsCmd handles data imports into PlanetScale. func DataImportsCmd(ch *cmdutil.Helper) *cobra.Command { cmd := &cobra.Command{ Use: "data-imports ", Short: "Create, list, and delete branch data imports", Long: "Create, list, and delete branch data imports.\n\nThis command is only supported for Vitess databases.", - Deprecated: "Vitess workflows are now available in the PlanetScale dashboard. See https://planetscale.com/docs/vitess/imports/database-imports for more information.", - PersistentPreRunE: cmdutil.CheckAuthentication(ch.Config), + Deprecated: deprecation, + PersistentPreRunE: cmdutil.WarnDeprecated("data-imports", deprecation, cmdutil.CheckAuthentication(ch.Config)), } cmd.PersistentFlags().StringVar(&ch.Config.Organization, "org", ch.Config.Organization, "The organization for the current user") diff --git a/internal/cmd/workflow/workflow.go b/internal/cmd/workflow/workflow.go index cec9fd14..482c03e0 100644 --- a/internal/cmd/workflow/workflow.go +++ b/internal/cmd/workflow/workflow.go @@ -5,12 +5,15 @@ import ( "github.com/spf13/cobra" ) +const deprecation = "use \"pscale branch vtctl move-tables\" instead. See https://planetscale.com/docs/cli/move-tables for more information." + func WorkflowCmd(ch *cmdutil.Helper) *cobra.Command { cmd := &cobra.Command{ Use: "workflow ", Short: "Manage the workflows for PlanetScale databases", + Deprecated: deprecation, Long: "Manage the workflows for PlanetScale databases.\n\nThis command is only supported for Vitess databases.", - PersistentPreRunE: cmdutil.CheckAuthentication(ch.Config), + PersistentPreRunE: cmdutil.WarnDeprecated("workflow", deprecation, cmdutil.CheckAuthentication(ch.Config)), } cmd.PersistentFlags().StringVar(&ch.Config.Organization, "org", ch.Config.Organization, diff --git a/internal/cmdutil/cmdutil.go b/internal/cmdutil/cmdutil.go index 7f2e0aba..94734b9b 100644 --- a/internal/cmdutil/cmdutil.go +++ b/internal/cmdutil/cmdutil.go @@ -154,6 +154,14 @@ func ExactArgs(reqArgs ...string) cobra.PositionalArgs { } } +// Cobra only prints Deprecated for the command being run, so subcommands of a deprecated group need this. +func WarnDeprecated(name, message string, next func(cmd *cobra.Command, args []string) error) func(cmd *cobra.Command, args []string) error { + return func(cmd *cobra.Command, args []string) error { + fmt.Fprintf(cmd.ErrOrStderr(), "Command %q is deprecated, %s\n", name, message) + return next(cmd, args) + } +} + // CheckAuthentication checks whether the user is authenticated and returns a // actionable error message. func CheckAuthentication(cfg *config.Config) func(cmd *cobra.Command, args []string) error {