Skip to content

Commit

Permalink
Docs: removing references to deprecated '--allow_long_unavailability'…
Browse files Browse the repository at this point in the history
… flag (#1536)

Signed-off-by: Shlomi Noach <[email protected]>
  • Loading branch information
shlomi-noach authored Jul 13, 2023
1 parent b3803b6 commit d58f9eb
Show file tree
Hide file tree
Showing 5 changed files with 5 additions and 32 deletions.
2 changes: 1 addition & 1 deletion content/en/docs/18.0/reference/programs/vtctl/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ Note that wherever `vtctl` commands produced master or MASTER for tablet type, t
| [ReloadSchemaKeyspace](../vtctl/schema-version-permissions#reloadschemakeyspace) | `ReloadSchemaKeyspace -- [--concurrency=10] [--include_primary=false] <keyspace>` |
| [ValidateSchemaShard](../vtctl/schema-version-permissions#validateschemashard) | `ValidateSchemaShard -- [--exclude_tables=''] [--include-views] <keyspace/shard>` |
| [ValidateSchemaKeyspace](../vtctl/schema-version-permissions#validateschemakeyspace) | `ValidateSchemaKeyspace -- [--exclude_tables=''] [--include-views] <keyspace name>` |
| [ApplySchema](../vtctl/schema-version-permissions#applyschema) | `ApplySchema -- [--allow_long_unavailability] [--wait_replicas_timeout=10s] {--sql=<sql> \|\| --sql-file=<filename>} <keyspace>` |
| [ApplySchema](../vtctl/schema-version-permissions#applyschema) | `ApplySchema -- [--wait_replicas_timeout=10s] {--sql=<sql> \|\| --sql-file=<filename>} <keyspace>` |
| [CopySchemaShard](../vtctl/schema-version-permissions#copyschemashard) | `CopySchemaShard -- [--tables=<table1>,<table2>,...] [--exclude_tables=<table1>,<table2>,...] [--include-views] [--skip-verify] [--wait_replicas_timeout=10s] {<source keyspace/shard> \|\| <source tablet alias>} <destination keyspace/shard>` |
| [ValidateVersionShard](../vtctl/schema-version-permissions#validateversionshard) | `ValidateVersionShard <keyspace/shard>` |
| [ValidateVersionKeyspace](../vtctl/schema-version-permissions#validateversionkeyspace) | `ValidateVersionKeyspace <keyspace name>` |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -153,13 +153,12 @@ Applies the schema change to the specified keyspace on all shards. The recommend

#### Example

<pre class="command-example">ApplySchema -- [--allow_long_unavailability] [--wait_replicas_timeout=10s] [--ddl_strategy=<ddl_strategy>] [--request_context=<unique-request-context>] [--skip_preflight] {--sql=&lt;sql&gt; || --sql-file=&lt;filename&gt;} &lt;keyspace&gt;</pre>
<pre class="command-example">ApplySchema -- [--wait_replicas_timeout=10s] [--ddl_strategy=<ddl_strategy>] [--request_context=<unique-request-context>] [--skip_preflight] {--sql=&lt;sql&gt; || --sql-file=&lt;filename&gt;} &lt;keyspace&gt;</pre>

#### Flags

| Name | Type | Definition |
| :-------- | :--------- | :--------- |
| 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. |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ This can be caused by a DDL executed on the source table as by default — contr
If you want the same or similar DDL to be applied on the target then you can apply that DDL on the target keyspace
and then restart the workflow. For example, using the example above:
```bash
$ vtctlclient ApplySchema -- --allow_long_unavailability --ddl_strategy=direct --sql="alter table customer add notes varchar(100) not null" customer
$ vtctlclient ApplySchema -- --ddl_strategy=direct --sql="alter table customer add notes varchar(100) not null" customer

$ vtctlclient Workflow -- customer.commerce2customer start
```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -37,31 +37,6 @@ CREATE TABLE `demo` (
```
In the above, we run a direct, synchronous, blocking `ALTER TABLE` statement. Knowing the table is in `commerce` keyspace, Vitess autodetects the relevant shards, and then autodetects which is the `primary` server in each shard. It then directly invokes the `ALTER TABLE` statement on all shards (concurrently), and the `vtctlclient` command only returns when all are complete.

Vitess will run some validations:

```shell
$ vtctlclient ApplySchema -- --sql "ALTER TABLE demo add column status int" commerce
E0908 10:35:53.478462 3711762 main.go:67] remote error: rpc error: code = Unknown desc = schema change failed, ExecuteResult: {
"FailedShards": null,
"SuccessShards": null,
"CurSQLIndex": 0,
"Sqls": [
"ALTER TABLE demo add column status int"
],
"ExecutorErr": "rpc error: code = Unknown desc = TabletManager.PreflightSchema on zone1-0000000100 error: /usr/bin/mysql: exit status 1, output: ERROR 1060 (42S21) at line 3: Duplicate column name 'status'\n: /usr/bin/mysql: exit status 1, output: ERROR 1060 (42S21) at line 3: Duplicate column name 'status'\n",
"TotalTimeSpent": 87104194
}
```

Vitess was able to determine that the migration is invalid because a column named `status` already exists. The statement never made it to the MySQL servers. These checks are not thorough, though they cover common scenarios.

If the table is large, then `ApplySchema` will reject the statement, try to protect the user from blocking their production servers. You may override that by supplying `--allow_long_unavailability` as follows:

```shell
$ vtctlclient ApplySchema -- --allow_long_unavailability --sql "ALTER TABLE demo modify id bigint unsigned" commerce
```


## VTGate

You may run DDL directly from VTGate just like you would send to a MySQL instance. For example:
Expand Down
5 changes: 2 additions & 3 deletions content/zh/docs/18.0/reference/vtctl.md
Original file line number Diff line number Diff line change
Expand Up @@ -1085,17 +1085,16 @@ Updates the configuration of the MaxReplicationLag module. The configuration mus

### ApplySchema

Applies the schema change to the specified keyspace on every master, running in parallel on all shards. The changes are then propagated to slaves 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.
Applies the schema change to the specified keyspace on every master, running in parallel on all shards. The changes are then propagated to slaves via replication.

#### Example

<pre class="command-example">ApplySchema [-allow_long_unavailability] [-wait_replicas_timeout=10s] {-sql=&lt;sql&gt; || -sql-file=&lt;filename&gt;} &lt;keyspace&gt;</pre>
<pre class="command-example">ApplySchema [-wait_replicas_timeout=10s] {-sql=&lt;sql&gt; || -sql-file=&lt;filename&gt;} &lt;keyspace&gt;</pre>

#### Flags

| Name | Type | Definition |
| :-------- | :--------- | :--------- |
| allow_long_unavailability | Boolean | Allow large schema changes which incur a longer unavailability of the database. |
| sql | string | A list of semicolon-delimited SQL commands |
| sql-file | string | Identifies the file that contains the SQL commands |
| wait_replicas_timeout | Duration | The amount of time to wait for slaves to receive the schema change via replication. |
Expand Down

0 comments on commit d58f9eb

Please sign in to comment.