vitess.io/vitess@v0.16.2/changelog/15.0/15.0.0/release_notes.md (about)

     1  # Release of Vitess v15.0.0
     2  ## Summary
     3  
     4  - **[Known Issues](#known-issues)**
     5  - **[Breaking Changes](#breaking-changes)**
     6    - [Flags](#flags)
     7    - [VTTablet Flag Deletions](#vttablet-flag-deletions)
     8    - [Vindex Interface](#vindex-interface)
     9  - **[Deprecations](#deprecations)**
    10    - [LogStats Table and Keyspace Deprecated](#logstats-table-and-keyspace-deprecated)
    11    - [Orchestrator Integration Deprecation](#orchestrator-integration-deprecation)
    12    - [Connection Pool Prefill](#connection-pool-prefill)
    13    - [InitShardPrimary Deprecation](#initshardprimary-deprecation)
    14  - **[Command-Line Syntax Deprecations](#command-line-syntax-deprecations)**
    15    - [VTTablet Startup Flag Deletions](#vttablet-startup-flag-deletions)
    16    - [VTTablet Startup Flag Deprecations](#vttablet-startup-flag-deprecations)
    17    - [VTBackup Flag Deprecations](#vtbackup-flag-deprecations)
    18  - **[VTGate](#vtgate)**
    19    - [vtgate --mysql-server-pool-conn-read-buffers](#vtgate--mysql-server-pool-conn-read-buffers)
    20  - **[VDiff2](#vdiff2)**
    21    - [Resume Workflow](#resume-workflow)
    22  - **[New command line flags and behavior](#new-command-line)**
    23    - [vtctl GetSchema --table-schema-only](#vtctl-getschema--table-schema-only)
    24    - [Support for Additional Compressors and Decompressors During Backup & Restore](#support-for-additional-compressors-and-decompressors-during-backup-&-restore)
    25    - [Independent OLAP and OLTP Transactional Timeouts](#independant-olap-and-oltp-transactional-timeouts)
    26    - [Support for Specifying Group Information in Calls to VTGate](#support-for-specifying-group-information-in-calls-to-vtgate)
    27  - **[Online DDL Changes](#online-ddl-changes)**
    28    - [Concurrent Vitess Migrations](#concurrent-vitess-migrations)
    29    - [VTCtl Command Changes](#vtctl-command-changes)
    30    - [New Syntax](#new-syntax)
    31  - **[Tablet Throttler](#tablet-throttler)**
    32    - [API Changes](#api-changes)
    33  - **[Mysql Compatibility](#mysql-compatibility)**
    34    - [System Settings](#system-settings)
    35    - [Lookup Vindexes](#lookup-vindexes)
    36  - **[Durability Policy](#durability-policy)**
    37    - [Cross Cell](#cross-cell)
    38  - **[New EXPLAIN Format](#new-explain-format)**
    39    - [FORMAT=vtexplain](#formatvtexplain)
    40  - **[VTOrc](#vtorc)**
    41    - [Old UI Removal and Replacement](#old-ui-removal-and-replacement)
    42    - [Configuration Refactor and New Flags](#configuratoin-refactor-and-new-flags)
    43    - [Example Upgrade](#example-upgrade)
    44    - [Default Configuration Files](#default-configuration-files)
    45  - **[Flags Restructure](#flags-restructure)**
    46    - [Flags Diff](#flags-diff)
    47  
    48  ## <a id="known-issues"/>Known Issues
    49  
    50  - [Corrupted results for non-full-group-by queries with JOINs](https://github.com/vitessio/vitess/issues/11625). This can be resolved by using full-group-by queries.
    51  
    52  ## Major Changes
    53  
    54  ### <a id="breaking-changes"/>Breaking Changes
    55  
    56  #### <a id="flags"/>Flags
    57  
    58  - The deprecated `--cpu_profile` flag has been removed. Please use the `--pprof` flag instead.
    59  - The deprecated `--mem-profile-rate` flag has been removed. Please use `--pprof=mem` instead.
    60  - The deprecated `--mutex-profile-fraction` flag has been removed. Please use `--pprof=mutex` instead.
    61  - The deprecated vtgate/vtexplain/vtcombo flag `--planner_version` has been removed. Please use `--planner-version` instead.
    62  - The deprecated flag `--master_connect_retry` has been removed. Please use `--replication_connect_retry` instead.
    63  - `vtctl` commands that take shard names and ranges as positional arguments (e.g. `vtctl Reshard ks.workflow -80 -40,40-80`) need to have their positional arguments separated from their flag arguments by a double-dash separator to avoid the new parsing library from mistaking them as flags (e.g. `vtctl Reshard ks.workflow -- -80 -40,40-80`).
    64  - The `--cell` flag in the `vtgate` binary no longer has a default value. It is a required argument that has to be specified for the binary to run. Please explicitly specify the flag, if dependent on the flag's default value.
    65  - The `--db-config-*-*` VTTablet flags were deprecated in `v3.0.0`. They have now been deleted as part of this release. You must use `--db_dba_*` now.
    66  
    67  #### <a id="vttablet-flag-deletions"/>vttablet Flag Deletions
    68  The following VTTablet flags were deprecated in 7.0. They have now been deleted
    69  - `--queryserver-config-message-conn-pool-size`
    70  - `--queryserver-config-message-conn-pool-prefill-parallelism`
    71  - `--client-found-rows-pool-size` A different existing flag `--queryserver-config-transaction-cap` will be used instead
    72  - `--transaction_shutdown_grace_period` Use `--shutdown_grace_period` instead
    73  - `--queryserver-config-max-dml-rows`
    74  - `--queryserver-config-allowunsafe-dmls`
    75  - `--pool-name-prefix`
    76  - `--enable-autocommit` Autocommit is always allowed
    77  
    78  #### <a id="vindex-interface"/>Vindex Interface
    79  
    80  All the vindex interface methods are changed by adding `context.Context` as an input parameter.
    81  
    82  E.g:
    83  ```go
    84  Map(vcursor VCursor, .... ) .... 
    85  	To
    86  Map(ctx context.Context, vcursor VCursor, .... ) ....
    87  ```
    88  
    89  This only affects users who have added their own custom vindex implementation. 
    90  They are required to change their implementation with these new interface method expectations.
    91  
    92  ### <a id="deprecations"/>Deprecations
    93  
    94  #### <a id="logstats-table-and-keyspace-deprecated"/>LogStats Table and Keyspace deprecated
    95  
    96  Information about which tables are used was being reported through the `Keyspace` and `Table` fields on LogStats.
    97  For multi-table queries, this output can be confusing, so we have added `TablesUsed`, that is a string array, listing all tables and which keyspace they are on.
    98  `Keyspace` and `Table` fields are deprecated and will be removed in the v16 release of Vitess.
    99  
   100  #### <a id="orchestrator-integration-deprecation"/>Orchestrator Integration Deprecation
   101  
   102  Orchestrator integration in `vttablet` has been deprecated. It will continue to work in this release but is liable to be removed in future releases.
   103  Consider using VTOrc instead of Orchestrator as VTOrc goes GA in this release.
   104  
   105  #### <a id="connection-pool-prefill"/>Connection Pool Prefill
   106  
   107  The connection pool with prefilled connections have been removed. The pool now does lazy connection creation.
   108  
   109  #### <a id="initshardprimary-deprecation"/>InitShardPrimary Deprecation
   110  
   111  The vtcltd command InitShardPrimary has been deprecated. Please use PlannedReparentShard instead.
   112  
   113  ### <a id="command-line-syntax-deprecations"/>Command-line syntax deprecations
   114  
   115  #### <a id="vttablet-startup-flag-deletions"/>vttablet startup flag deletions
   116  The following VTTablet flags were deprecated in 7.0. They have now been deleted
   117  - --queryserver-config-message-conn-pool-size
   118  - --queryserver-config-message-conn-pool-prefill-parallelism
   119  - --client-found-rows-pool-size --queryserver-config-transaction-cap will be used instead
   120  - --transaction_shutdown_grace_period Use --shutdown_grace_period instead
   121  - --queryserver-config-max-dml-rows
   122  - --queryserver-config-allowunsafe-dmls
   123  - --pool-name-prefix
   124  - --enable-autocommit Autocommit is always allowed
   125  
   126  #### <a id="vttablet-startup-flag-deprecations"/>vttablet startup flag deprecations
   127  - `--enable-query-plan-field-caching` has been deprecated. It will be removed in v16.
   128  - `--enable_semi_sync` has been deprecated. It will be removed in v16. Instead, set the correct durability policy using `SetKeyspaceDurabilityPolicy`
   129  - `--queryserver-config-pool-prefill-parallelism`, `--queryserver-config-stream-pool-prefill-parallelism` and `--queryserver-config-transaction-prefill-parallelism` have all been deprecated. They will be removed in v16.
   130  - `--backup_storage_hook` has been deprecated, consider using one of the builtin compression algorithms or `--external-compressor` and `--external-decompressor` instead.
   131  
   132  #### <a id="vtbackup-flag-deprecations"/>vtbackup flag deprecations
   133  - `--backup_storage_hook` has been deprecated, consider using one of the builtin compression algorithms or `--external-compressor` and `--external-decompressor` instead.
   134  
   135  ### <a id="vtgate"/>VTGate
   136  
   137  #### <a id="vtgate--mysql-server-pool-conn-read-buffers"/>vtgate --mysql-server-pool-conn-read-buffers
   138  
   139  `--mysql-server-pool-conn-read-buffers` enables pooling of buffers used to read from incoming
   140  connections, similar to the way pooling happens for write buffers. Defaults to off.
   141  
   142  ### <a id="vdiff2"/>VDiff v2
   143  
   144  #### <a id="resume-workflow"/>Resume Workflow
   145  
   146  We introduced the ability to resume a VDiff2 workflow:
   147  ```
   148  $ vtctlclient --server=localhost:15999 VDiff --v2 customer.commerce2customer resume 4c664dc2-eba9-11ec-9ef7-920702940ee0
   149  VDiff 4c664dc2-eba9-11ec-9ef7-920702940ee0 resumed on target shards, use show to view progress
   150  
   151  $ vtctlclient --server=localhost:15999 VDiff --v2 customer.commerce2customer show last
   152  
   153  VDiff Summary for customer.commerce2customer (4c664dc2-eba9-11ec-9ef7-920702940ee0)
   154  State:        completed
   155  RowsCompared: 196
   156  HasMismatch:  false
   157  StartedAt:    2022-06-26 22:44:29
   158  CompletedAt:  2022-06-26 22:44:31
   159  
   160  Use "--format=json" for more detailed output.
   161  
   162  $ vtctlclient --server=localhost:15999 VDiff --v2 --format=json customer.commerce2customer show last
   163  {
   164  	"Workflow": "commerce2customer",
   165  	"Keyspace": "customer",
   166  	"State": "completed",
   167  	"UUID": "4c664dc2-eba9-11ec-9ef7-920702940ee0",
   168  	"RowsCompared": 196,
   169  	"HasMismatch": false,
   170  	"Shards": "0",
   171  	"StartedAt": "2022-06-26 22:44:29",
   172  	"CompletedAt": "2022-06-26 22:44:31"
   173  }
   174  ```
   175  
   176  We leverage this resume capability to automatically restart a VDiff2 workflow that encountered a retryable error.
   177  
   178  We also made a number of other enhancements like progress reporting and features needed to make it a full replacement for VDiff v1. You can see more details in the tracking ticket for the VDiff2 feature complete target: https://github.com/vitessio/vitess/issues/10494
   179  
   180  Now that VDiff v2 is feature complete in 15.0, we hope to make it GA in 16.0.
   181  
   182  Please see the VDiff2 [documentation](https://vitess.io/docs/15.0/reference/vreplication/vdiff2/) for additional information.
   183  
   184  ### <a id="new-command-line"/>New command line flags and behavior
   185  
   186  #### <a id="vtctl-getschema--table-schema-only"/>vtctl GetSchema --table-schema-only
   187  
   188  The new flag `--table-schema-only` skips column introspection. `GetSchema` only returns general schema analysis, and specifically it includes the `CREATE TABLE|VIEW` statement in the `schema` field.
   189  
   190  #### <a id="support-for-additional-compressors-and-decompressors-during-backup-&-restore"/>Support for additional compressors and decompressors during backup & restore
   191  Backup/Restore now allow you many more options for compression and decompression instead of relying on the default compressor(`pargzip`).
   192  There are some built-in compressors which you can use out-of-the-box. Users will need to evaluate which option works best for their
   193  use-case. Here are the flags that control this feature
   194  
   195  - `--compression-engine-name`
   196  - `--external-compressor`
   197  - `--external-decompressor`
   198  - `--external-compressor-extension`
   199  - `--compression-level`
   200  
   201  `--compression-engine-name` specifies the engine used for compression. It can have one of the following values
   202  
   203  - pargzip (Default)
   204  - pgzip
   205  - lz4
   206  - zstd
   207  - external
   208  
   209  If you want to use any of the built-in compressors, simply set one of the above values other than `external` for `--compression-engine-name`. The value
   210  specified in `--compression-engine-name` is saved in the backup MANIFEST, which is later read by the restore process to decide which
   211  engine to use for decompression. Default value for engine is 'pargzip'.
   212  
   213  If you would like to use a custom command or external tool for compression/decompression then you need to provide the full command with
   214  arguments to the `--external-compressor` and `--external-decompressor` flags. `--external-compressor-extension` flag also needs to be provided
   215  so that compressed files are created with the correct extension. If the external command is not using any of the built-in compression engines
   216  (i.e. pgzip, pargzip, lz4 or zstd) then you need to set `--compression-engine-name` to value 'external'.
   217  
   218  Please note that if you want to keep the current behavior then you don't need to provide any of these flags.
   219  You can read more about backup & restore [here] (https://vitess.io/docs/15.0/user-guides/operating-vitess/backup-and-restore/).
   220  
   221  If you decided to switch from an external compressor to one of the built-in supported compressors (i.e. pgzip, pargzip, lz4 or zstd) at any point
   222  in the future, you will need to do it in two steps.
   223  
   224  - step #1, set `--external-compressor` and `--external-compressor-extension` flag values to empty and change `--compression-engine-name` to desired value.
   225  - Step #2, after at least one cycle of backup with new configuration, you can set `--external-decompressor` flag value to empty.
   226  
   227  The reason you cannot change all the values together is because the restore process will then have no way to find out which external decompressor
   228  should be used to process the previous backup. Please make sure you have thought out all possible scenarios for restore before transitioning from one
   229  compression engine to another.
   230  
   231  #### <a id="independant-olap-and-oltp-transactional-timeouts"/>Independent OLAP and OLTP transactional timeouts
   232  
   233  `--queryserver-config-olap-transaction-timeout` specifies the timeout applied
   234  to a transaction created within an OLAP workload. The default value is `30`
   235  seconds, but this can be raised, lowered, or set to zero to disable the timeout
   236  altogether.
   237  
   238  Until now, while OLAP queries would bypass the query timeout, transactions
   239  created within an OLAP session would be rolled back
   240  `--queryserver-config-transaction-timeout` seconds after the transaction was
   241  started.
   242  
   243  As of now, OLTP and OLAP transaction timeouts can be configured independently of each
   244  other.
   245  
   246  The main use case is to run queries spanning a long period of time which
   247  require transactional guarantees such as consistency or atomicity.
   248  
   249  #### <a id="support-for-specifying-group-information-in-calls-to-vtgate"/>Support for specifying group information in calls to VTGate
   250  
   251  `--grpc-use-effective-groups` allows non-SSL callers to specify groups information for a caller.
   252  Until now, you could only specify the caller-id for the security context used to authorize queries.
   253  As of now, you can specify the principal of the caller, and any groups they belong to.
   254  
   255  ### <a id="online-ddl-changes"/>Online DDL changes
   256  
   257  #### <a id="concurrent-vitess-migrations"/>Concurrent vitess migrations
   258  
   259  All Online DDL migrations using the `vitess` strategy are now eligible to run concurrently, given `--allow-concurrent` DDL strategy flag. Until now, only `CREATE`, `DROP` and `REVERT` migrations were eligible, and now `ALTER` migrations are supported, as well. The terms for `ALTER` migrations concurrency:
   260  
   261  - DDL strategy must be `vitess --allow-concurent ...`
   262  - No two migrations can run concurrently on the same table
   263  - No two `ALTER`s will copy table data concurrently
   264  - A concurrent `ALTER` migration will not start if another `ALTER` is running and is not `ready_to_complete`
   265  
   266  The main use case is to run multiple concurrent migrations, all with `--postpone-completion`. All table-copy operations will run sequentially, but no migration will actually cut-over, and eventually all migrations will be `ready_to_complete`, continuously tailing the binary logs and keeping up-to-date. A quick and iterative `ALTER VITESS_MIGRATION '...' COMPLETE` sequence of commands will cut-over all migrations _closely together_ (though not atomically together).
   267  
   268  #### <a id="vtctl-command-changes"/>vtctl command changes. 
   269  All `online DDL show` commands can now be run with a few additional parameters
   270  - `--order` , order migrations in the output by either ascending or descending order of their `id` fields.
   271  - `--skip`  , skip specified number of migrations in the output.
   272  - `--limit` , limit results to a specified number of migrations in the output.
   273  
   274  #### <a id="new-syntax"/>New syntax
   275  
   276  The following is now supported:
   277  
   278  ```sql
   279  ALTER VITESS_MIGRATION COMPLETE ALL
   280  ```
   281  
   282  This works on all pending migrations (`queued`, `ready`, `running`) and internally issues a `ALTER VITESS_MIGRATION '<uuid>' COMPLETE` for each one. The command is useful for completing multiple concurrent migrations (see above) that are open-ended (`--postpone-completion`).
   283  
   284  ### <a id="tablet-throttler"/>Tablet Throttler
   285  
   286  #### <a id="api-changes"/>API changes
   287  
   288  API endpoint `/debug/vars` now exposes throttler metrics, such as number of hits and errors per app per check type. Example:
   289  
   290  ```shell
   291  $ curl -s http://127.0.0.1:15100/debug/vars | jq . | grep Throttler
   292    "ThrottlerAggregatedMysqlSelf": 0.191718,
   293    "ThrottlerAggregatedMysqlShard": 0.960054,
   294    "ThrottlerCheckAnyError": 27,
   295    "ThrottlerCheckAnyMysqlSelfError": 13,
   296    "ThrottlerCheckAnyMysqlSelfTotal": 38,
   297    "ThrottlerCheckAnyMysqlShardError": 14,
   298    "ThrottlerCheckAnyMysqlShardTotal": 42,
   299    "ThrottlerCheckAnyTotal": 80,
   300    "ThrottlerCheckMysqlSelfSecondsSinceHealthy": 0,
   301    "ThrottlerCheckMysqlShardSecondsSinceHealthy": 0,
   302    "ThrottlerProbesLatency": 355523,
   303    "ThrottlerProbesTotal": 74,
   304  ```
   305  
   306  ### <a id="mysql-compatibility"/>Mysql Compatibility
   307  
   308  #### <a id="system-settings"/>System Settings
   309  Vitess has had support for system settings from release 7.0 onwards, but this support came with some caveats.
   310  As soon as a client session changes a default system setting, a mysql connection gets reserved for it.
   311  This can sometimes lead to clients running out of mysql connections. 
   312  Users were instructed to minimize the use of this feature and to try to set the desired system settings as defaults in the mysql config.
   313  
   314  With this release, Vitess can handle system settings changes in a much better way and clients can use them more freely.
   315  Vitess now has the ability to pool changed settings without reserving connections for any particular session. 
   316  
   317  This feature can be enabled by setting `queryserver-enable-settings-pool` flag on the vttablet. It is disabled by default.
   318  In future releases, we will make this flag enabled by default.
   319  
   320  #### <a id="lookup-vindexes"/>Lookup Vindexes
   321  
   322  Lookup vindexes now support a new parameter `multi_shard_autocommit`. If this is set to `true`, lookup vindex dml queries will be sent as autocommit to all shards instead of being wrapped in a transaction.
   323  This is different from the existing `autocommit` parameter where the query is sent in its own transaction separate from the ongoing transaction if any i.e. begin -> lookup query execs -> commit/rollback
   324  
   325  ### <a id="durability-policy"/>Durability Policy
   326  
   327  #### <a id="cross-cell"/>Cross Cell
   328  
   329  A new durability policy `cross_cell` is now supported. `cross_cell` durability policy only allows replica tablets from a different cell than the current primary to
   330  send semi-sync ACKs. This ensures that any committed write exists in at least 2 tablets belonging to different cells.
   331  
   332  ### <a id="new-explain-format"/>New EXPLAIN format
   333  
   334  #### <a id="format=vtexplain"/>FORMAT=vtexplain
   335  
   336  With this new `explain` format, you can get an output that is very similar to the command line `vtexplain` app, but from a running `vtgate`, through a MySQL query.
   337  
   338  ### <a id="vtorc"/>VTOrc
   339  
   340  #### <a id="old-ui-removal-and-replacement"/>Old UI Removal and Replacement
   341  
   342  The old UI that VTOrc inherited from `Orchestrator` has been removed. A replacement UI, more consistent with the other Vitess binaries has been created.
   343  In order to use the new UI, `--port` flag has to be provided. 
   344  
   345  Along with the UI, the old APIs have also been deprecated. However, some of them have been ported over to the new UI - 
   346  
   347  | Old API                          | New API                          | Additional notes                                                      |
   348  |----------------------------------|----------------------------------|-----------------------------------------------------------------------|
   349  | `/api/problems`                  | `/api/problems`                  | The new API also supports filtering using the keyspace and shard name |
   350  | `/api/disable-global-recoveries` | `/api/disable-global-recoveries` | Functionally remains the same                                         |
   351  | `/api/enable-global-recoveries`  | `/api/enable-global-recoveries`  | Functionally remains the same                                         |
   352  | `/api/health`                    | `/debug/health`                  | Functionally remains the same                                         |
   353  | `/api/replication-analysis`      | `/api/replication-analysis`      | Functionally remains the same. Output is now JSON format.             |
   354  
   355  Apart from these APIs, we also now have `/debug/status`, `/debug/vars` and `/debug/liveness` available in the new UI.
   356  
   357  #### <a id="configuratoin-refactor-and-new-flags"/>Configuration Refactor and New Flags 
   358  
   359  Since VTOrc was forked from `Orchestrator`, it inherited a lot of configurations that don't make sense for the Vitess use-case.
   360  All of such configurations have been removed.
   361  
   362  VTOrc ignores the configurations that it doesn't understand. So old configurations can be kept around on upgrading and won't cause any issues.
   363  They will just be ignored.
   364  
   365  For all the configurations that are kept, flags have been added for them and the flags are the desired way to pass these configurations going forward.
   366  The config file will be deprecated and removed in upcoming releases. The following is a list of all the configurations that are kept and the associated flags added.
   367  
   368  |          Configurations Kept          |           Flags Introduced            |
   369  |:-------------------------------------:|:-------------------------------------:|
   370  |            SQLite3DataFile            |         `--sqlite-data-file`          |
   371  |          InstancePollSeconds          |        `--instance-poll-time`         |
   372  |    SnapshotTopologiesIntervalHours    |    `--snapshot-topology-interval`     |
   373  |    ReasonableReplicationLagSeconds    |    `--reasonable-replication-lag`     |
   374  |             AuditLogFile              |        `--audit-file-location`        |
   375  |             AuditToSyslog             |         `--audit-to-backend`          |
   376  |           AuditToBackendDB            |          `--audit-to-syslog`          |
   377  |            AuditPurgeDays             |       `--audit-purge-duration`        |
   378  |      RecoveryPeriodBlockSeconds       |  `--recovery-period-block-duration`   |
   379  | PreventCrossDataCenterPrimaryFailover |    `--prevent-cross-cell-failover`    |
   380  |        LockShardTimeoutSeconds        |        `--lock-shard-timeout`         |
   381  |      WaitReplicasTimeoutSeconds       |       `--wait-replicas-timeout`       |
   382  |     TopoInformationRefreshSeconds     | `--topo-information-refresh-duration` |
   383  |          RecoveryPollSeconds          |      `--recovery-poll-duration`       |
   384  
   385  Apart from configurations, some flags from VTOrc have also been removed -
   386  - `sibling`
   387  - `destination`
   388  - `discovery`
   389  - `skip-unresolve`
   390  - `skip-unresolve-check`
   391  - `noop`
   392  - `binlog`
   393  - `statement`
   394  - `grab-election`
   395  - `promotion-rule`
   396  - `skip-continuous-registration`
   397  - `enable-database-update`
   398  - `ignore-raft-setup`
   399  - `tag`
   400  
   401  The ideal way to ensure backward compatibility is to remove the flags listed above while on the previous release. Then upgrade VTOrc.
   402  After upgrading, remove the config file and instead pass the flags that are introduced.
   403  
   404  #### <a id="example-upgrade"/>Example Upgrade
   405  
   406  If you are running VTOrc with the flags `--ignore-raft-setup --clusters_to_watch="ks/0" --config="path/to/config"` and the following configuration
   407  ```json
   408  {
   409    "Debug": true,
   410    "ListenAddress": ":6922",
   411    "MySQLTopologyUser": "orc_client_user",
   412    "MySQLTopologyPassword": "orc_client_user_password",
   413    "MySQLReplicaUser": "vt_repl",
   414    "MySQLReplicaPassword": "",
   415    "RecoveryPeriodBlockSeconds": 1,
   416    "InstancePollSeconds": 1,
   417    "PreventCrossDataCenterPrimaryFailover": true
   418  }
   419  ```
   420  First drop the flag `--ignore-raft-setup` while on the previous release. So, you'll be running VTOrc with `--clusters_to_watch="ks/0" --config="path/to/config"` and the same configuration listed above.
   421  
   422  Now you can upgrade your VTOrc version continuing to use the same flags and configurations, and it will continue to work just the same. If you wish to use the new UI, then you can add the `--port` flag as well.
   423  
   424  After upgrading, you can drop the configuration entirely and use the new flags like `--clusters_to_watch="ks/0" --recovery-period-block-duration=1s --instance-poll-time=1s --prevent-cross-cell-failover`
   425  
   426  #### <a id="default-configuration-files"/>Default Configuration Files
   427  
   428  The default files that VTOrc searches for configurations in have also changed from `"/etc/orchestrator.conf.json", "conf/orchestrator.conf.json", "orchestrator.conf.json"` to
   429  `"/etc/vtorc.conf.json", "conf/vtorc.conf.json", "vtorc.conf.json"`.
   430  
   431  ### <a id="flags-restructure"/>Flags Restructure
   432  
   433  #### <a id="flags-diff"/>Flags Diff
   434  
   435  In addition to these major streams of work in release-15.0, we have made tremendous progress on [VEP-4, aka The Flag Situation](https://github.com/vitessio/enhancements/blob/main/veps/vep-4.md), reorganizing our code so that Vitess binaries and their flags are
   436  clearly aligned in help text. An immediate win for usability, this positions us well to move on to a [viper](https://github.com/spf13/viper) implementation which will facilitate additional improvements including standardization of flag syntax and runtime configuration reloads.
   437  We are also aligning with industry standards regarding the use of flags, ensuring a seamless experience for users migrating from or integrating with other platforms.
   438  Below are the changes for each binary.
   439  - [mysqlctl](https://github.com/vitessio/vitess/blob/release-15.0/doc/flags/14.0-to-15.0-transition/mysqlctl.diff)
   440  - [mysqlctld](https://github.com/vitessio/vitess/blob/release-15.0/doc/flags/14.0-to-15.0-transition/mysqlctld.diff)
   441  - [vtaclcheck](https://github.com/vitessio/vitess/blob/release-15.0/doc/flags/14.0-to-15.0-transition/vtaclcheck.diff)
   442  - [vtadmin](https://github.com/vitessio/vitess/blob/release-15.0/doc/flags/14.0-to-15.0-transition/vtadmin.diff)
   443  - [vtctlclient](https://github.com/vitessio/vitess/blob/release-15.0/doc/flags/14.0-to-15.0-transition/vtctlclient.diff)
   444  - [vtctld](https://github.com/vitessio/vitess/blob/release-15.0/doc/flags/14.0-to-15.0-transition/vtctld.diff)
   445  - [vtctldclient](https://github.com/vitessio/vitess/blob/release-15.0/doc/flags/14.0-to-15.0-transition/vtctldclient.diff)
   446  - [vtexplain](https://github.com/vitessio/vitess/blob/release-15.0/doc/flags/14.0-to-15.0-transition/vtexplain.diff)
   447  - [vtgate](https://github.com/vitessio/vitess/blob/release-15.0/doc/flags/14.0-to-15.0-transition/vtgate.diff)
   448  - [vtgtr](https://github.com/vitessio/vitess/blob/release-15.0/doc/flags/14.0-to-15.0-transition/vtgtr.diff)
   449  - [vtorc](https://github.com/vitessio/vitess/blob/release-15.0/doc/flags/14.0-to-15.0-transition/vtorc.diff)
   450  - [vttablet](https://github.com/vitessio/vitess/blob/release-15.0/doc/flags/14.0-to-15.0-transition/vttablet.diff)
   451  - [vttestserver](https://github.com/vitessio/vitess/blob/release-15.0/doc/flags/14.0-to-15.0-transition/vttestserver.diff)
   452  - [vttlstest](https://github.com/vitessio/vitess/blob/release-15.0/doc/flags/14.0-to-15.0-transition/vttlstest.diff)
   453  - [zk](https://github.com/vitessio/vitess/blob/release-15.0/doc/flags/14.0-to-15.0-transition/zk.diff)
   454  - [zkctl](https://github.com/vitessio/vitess/blob/release-15.0/doc/flags/14.0-to-15.0-transition/zkctl.diff)
   455  - [zkctld](https://github.com/vitessio/vitess/blob/release-15.0/doc/flags/14.0-to-15.0-transition/zkctld.diff)
   456  
   457  ------------
   458  The entire changelog for this release can be found [here](https://github.com/vitessio/vitess/blob/main/changelog/15.0/15.0.0/changelog.md).
   459  
   460  The release includes 595 commits (excluding merges)
   461  
   462  Thanks to all our contributors: @Abirdcfly, @DeathBorn, @GuptaManan100, @K-Kumar-01, @L3o-pold, @Phanatic, @Weijun-H, @ajm188, @arthurschreiber, @arvind-murty, @brirams, @dbussink, @deepthi, @dependabot[bot], @doeg, @frouioui, @harshit-gangal, @mattlord, @maxenglander, @mgale, @notfelineit, @ofiriluz, @olyazavr, @quinox, @rafer, @renatolabs, @rohit-nayak-ps, @rsajwani, @rvrangel, @saunderst, @shlomi-noach, @systay, @vitess-bot[bot], @vmg, @yoheimuta
   463