Merge pull request #1350 from vitessio/docs-schema-management-review-…

…202301

Docs: update 'schema management' docs and related

content/en/docs/16.0/reference/features/schema-management.md

@@ -79,52 +79,35 @@ This section describes the following commands:
 
 ### ApplySchema
 
-Vitess' schema modification functionality is designed the following goals in mind:
+Vitess offers [managed schema migration](../../../user-guides/schema-changes/managed-online-schema-changes/), and notably supports online schema migrations (aka Online DDL), transparently to the user. Vitess Online DDL offers:
 
-* Enable simple updates that propagate to your entire fleet of servers.
-* Require minimal human interaction.
-* Minimize errors by testing changes against a temporary database.
-* Guarantee very little downtime (or no downtime) for most schema updates.
-* Do not store permanent schema data in the topology service.
+* Non-blocking migrations
+* Migrations are asyncronously auto-scheduled, queued and executed by tablets
+* Migration state is trackable
+* Migrations are cancellable
+* Migrations are retry-able
+* Lossless, [revertible migrations](../../../user-guides/schema-changes/revertible-migrations/)
+* Support for [declarative migrations](../../../user-guides/schema-changes/declarative-migrations/)
+* Support for [postponed migrations](../../../user-guides/schema-changes/postponed-migrations/)
+* Support for [failover agnostic migrations](../../../user-guides/schema-changes/recoverable-migrations/)
+* Support for [concurrent migrations](../../../user-guides/schema-changes/concurrent-migrations/)
 
-Note that, at this time, Vitess only supports [data definition statements](https://dev.mysql.com/doc/refman/5.6/en/sql-data-definition-statements.html) that create, modify, or delete database tables. For instance, `ApplySchema` does not affect stored procedures or grants.
+The [ApplySchema](../../../reference/programs/vtctl/schema-version-permissions/#applyschema) command applies a schema change to the specified keyspace on all shards. The command format is: `ApplySchema -- {--sql=<sql> || --sql_file=<filename>} <keyspace>`
 
-The [ApplySchema](../../../reference/programs/vtctl/#applyvschema) command applies a schema change to the specified keyspace on every primary tablet, running in parallel on all shards. Changes are then propagated to replicas. The command format is: `ApplySchema -- {--sql=<sql> || --sql_file=<filename>} <keyspace>`
+Further reading:
 
-When the `ApplySchema` action actually applies a schema change to the specified keyspace, it performs the following steps:
-
-1. It finds shards that belong to the keyspace, including newly added shards if a [resharding event](../sharding/#resharding) has taken place.
-2. It validates the SQL syntax and determines the impact of the schema change. If the scope of the change is too large, Vitess rejects it. See the [permitted schema changes](#permitted-schema-changes) section for more detail.
-3. It employs a pre-flight check to ensure that a schema update will succeed before the change is actually applied to the live database. In this stage, Vitess copies the current schema into a temporary database, applies the change there to validate it, and retrieves the resulting schema. By doing so, Vitess verifies that the change succeeds without actually touching live database tables.
-4. It applies the SQL command on the primary tablet in each shard.
-
-The following sample command applies the SQL in the **user_table.sql** file to the **user** keyspace:
-
-`ApplySchema -- --sql_file=user_table.sql user`
+* [Making schema changes](../../../user-guides/schema-changes/)
+* [Managed schema changes](../../../user-guides/schema-changes/managed-online-schema-changes/)
+* [DDL strategies](../../../user-guides/schema-changes/ddl-strategies/)
 
 #### Permitted schema changes
 
-The `ApplySchema` command supports a limited set of DDL statements. In addition, Vitess rejects some schema changes because large changes can slow replication and may reduce the availability of your overall system.
-
-The following list identifies types of DDL statements that Vitess supports:
-
-* `CREATE TABLE`
-* `CREATE INDEX`
-* `CREATE VIEW`
-* `ALTER TABLE`
-* `ALTER VIEW`
-* `RENAME TABLE`
-* `DROP TABLE`
-* `DROP INDEX`
-* `DROP VIEW`
-
-In addition, Vitess applies the following rules when assessing the impact of a potential change:
+The `ApplySchema` command supports these commands:
 
-* `DROP` statements are always allowed, regardless of the table's size.
-* `ALTER` statements are only allowed if the table on the shard's primary tablet has 100,000 rows or less.
-* For all other statements, the table on the shard's primary tablet must have 2 million rows or less.
+* `CREATE TABLE`, `ALTER TABLE`, `DROP TABLE`, `CREATE VIEW`, `ALTER VIEW`, `DROP VIEW` in Online DDL
+* In addition, `CREATE INDEX`, `DROP INDEX`, `RENAME TABLE`, in non Online DDL
 
-If a schema change gets rejected because it affects too many rows, you can specify the flag `--allow_long_unavailability` to tell `ApplySchema` to skip this check. However, we do not recommend this. Instead, you should apply large schema changes by using an external tool such as `gh-ost` or `pt-online-schema-change`.
+`ApplySchema` does not support creation or modifications of stored routines, including functions, procedures, triggers, and events.
 
 ### ApplyVSchema
 

content/en/docs/16.0/reference/programs/vtctl/schema-version-permissions.md

@@ -149,7 +149,7 @@ Validates that the schema on the primary tablet for shard 0 matches the schema o
 
 ### ApplySchema
 
-Applies the schema change to the specified keyspace on every primary, running in parallel on all shards. The changes are then propagated to replicas via replication. If -allow_long_unavailability is set, schema changes affecting a large number of rows (and possibly incurring a longer period of unavailability) will not be rejected. --ddl_strategy is used to instruct migrations via vreplication, gh-ost or pt-osc with optional parameters. -request_context allows the user to specify a custom request context for online DDL migrations. If --skip_preflight, SQL goes directly to shards without going through sanity checks.
+Applies the schema change to the specified keyspace on all shards. The recommended method of applying schema changes is via [Online DDL](../../../../user-guides/schema-changes/managed-online-schema-changes/), which ensures migrations are non-blocking and keeps replication in sync throughout the operation. --ddl_strategy is used to instruct migrations via vreplication, `gh-ost` or `pt-osc` with optional parameters. -request_context allows the user to specify a custom request context for online DDL migrations. If --skip_preflight, SQL goes directly to shards without going through sanity checks.
 
 #### Example
 
@@ -159,11 +159,11 @@ Applies the schema change to the specified keyspace on every primary, running in
 
 | Name | Type | Definition |
 | :-------- | :--------- | :--------- |
-| allow_long_unavailability | Boolean | Allow large schema changes which incur a longer unavailability of the database. |
+| allow_long_unavailability | Boolean | Allow large schema changes which incur a longer unavailability of the database. Flag will be deprecated as the recommended way to run long migrations is via Online DDL. |
 | caller_id | string | Effective caller ID used for the operation and should map to an ACL name which grants this identity the necessary permissions to perform the operation (this is only necessary when strict table ACLs are used). |
 | ddl_strategy | string | Online DDL strategy, compatible with @@ddl_strategy session variable (examples: 'gh-ost', 'pt-osc', 'gh-ost --max-load=Threads_running=100' (default "direct"). |
 | request_context | string | For Only DDL, optionally supply a custom unique string used as context for the migration(s) in this command. By default a unique context is auto-generated by Vitess. |
-| skip_preflight | Boolean | Skip pre-apply schema checks, and directly forward schema change query to shards. |
+| skip_preflight | Boolean | Skip pre-apply schema checks, and directly forward schema change query to shards. Ignored when using Online DDL |
 | sql | string | A list of semicolon-delimited SQL commands. |
 | sql-file | string | Identifies the file that contains the SQL commands. This file needs to exist on the server, rather than on the client. |
 | wait_replicas_timeout | Duration | The amount of time to wait for replicas to receive the schema change via replication (default 10s). |

content/en/docs/16.0/user-guides/schema-changes/managed-online-schema-changes.md

@@ -4,7 +4,7 @@ weight: 2
 aliases: ['/docs/user-guides/managed-online-schema-changes/']
 ---
 
-Vitess offers managed, online schema migrations (aka Online DDL), transparently to the user. Vitess Onine DDL offers:
+Vitess offers managed, online schema migrations (aka Online DDL), transparently to the user. Vitess Online DDL offers:
 
 - Non-blocking migrations
 - Migrations are asyncronously auto-scheduled, queued and executed by tablets
@@ -21,14 +21,15 @@ Vitess offers managed, online schema migrations (aka Online DDL), transparently
 As general overview:
 
 - User chooses a [strategy](../ddl-strategies) for online DDL (online DDL is opt in)
-- User submits one or more schema change queries, using the standard MySQL `CREATE TABLE`, `ALTER TABLE` and `DROP TABLE` syntax.
+- User submits one or more schema change queries, using the standard MySQL `CREATE TABLE`, `ALTER TABLE`, `DROP TABLE`, `CREATE VIEW`, `ALTER VIEW`, `DROP VIEW` syntax.
 - Vitess responds with a Job ID for each schema change query.
 - Vitess resolves affected shards.
 - A shard's `primary` tablet schedules the migration to run when possible.
 - Tablets will independently run schema migrations:
   - `ALTER TABLE` statements run via `VReplication`, `gh-ost` or `pt-online-schema-change`, as per selected [strategy](../ddl-strategies)
-  - `CREATE TABLE` statements run directly.
+  - `CREATE TABLE` and `CREATE VIEW` statements run directly.
   - `DROP TABLE` statements run [safely and lazily](../../../design-docs/table-lifecycle/safe-lazy-drop-tables/).
+  - `ALTER VIEW` and `DROP VIEW` are internally modified to allow quick revert.
 - Vitess provides the user a mechanism to view migration status, launch (if required), complete (if required), cancel or retry migrations, based on the job ID.
 
 ## Syntax