mysqlx-protocol-notices.dox

/*
 * Copyright (c) 2015, 2025, Oracle and/or its affiliates.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License, version 2.0,
 * as published by the Free Software Foundation.
 *
 * This program is designed to work with certain software (including
 * but not limited to OpenSSL) that is licensed under separate terms,
 * as designated in a particular file or component or in included license
 * documentation. The authors of MySQL hereby grant you an additional
 * permission to link the program and your derivative works with the
 * separately licensed software that they have either included with
 * the program or referenced in the documentation.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License, version 2.0, for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 */

/** @page mysqlx_protocol_notices Notices

Topics in this section:

- @ref notices_Global_Notices
- @ref notices_Local_Notices

Notices are a way to send axillary data from the server to the client
that can be:

- global

- local to the current message sequence

Notices don't affect the state of the current message sequence, that
means: the client is may ignore notices and still be able to properly
understand the message sequence.

Global Notices {#notices_Global_Notices}
==============

Global Notices are sent by the server in case of events happen that are
unrelated to the currently active message sequence:
- server is shutting down
- replica disconnected
- group replication state change
- schema or table dropped


## Server Shutting Down

The server indicates that it shuts down in a clean way.
@warning Not supported yet

## Replica disconnected

The replica stopped to replicate changes from the replication source/group
and may contain stale information.

@note
 Checking for ``SHOW REPLICA STATUS`` and ``io_thread`` and
 ``sql_thread`` leads to a race condition for the following query.
 One would have to check after query of the replica is still running to
 see if it didn't stop in between.
@warning Not supported yet

## Group replication state change

Following changes inside the group, trigger this notice: quorum loss,
view changed, role of the node changed, state changed.
This information is transfered inside `GROUP_REPLICATION_STATE_CHANGED` notice,
using following message @ref Mysqlx::Notice::GroupReplicationStateChanged.

## Schema or Table Dropped/Altered/...

If a client maintains a cache of recent queries + resultsets it would
improve the caching behavior if the client would be notified if a
underlying table or schema was dropped, changed, and so on.
@warning Not supported yet

Local Notices {#notices_Local_Notices}
=============

Local Notices are related to the currently active Message Sequence like:

- Committed Transaction IDs
@warning Not supported yet

- Transaction State Changes
@warning Not supported yet

- SQL warnings @ref Mysqlx::Notice::Warning

- @ref notices_Session_Variable_Changed "session variable changed"

- @ref notices_Session_State_Changed "session state changed"

## Session Variable Changed {#notices_Session_Variable_Changed}

Via
@ref Mysqlx::Notice::SessionVariableChanged

It allows intermediates to track state changes on the clients session
that may be otherwise unnoticeable like:

@code{sql}
 CREATE PROCEDURE init() BEGIN
 SET @@sql_mode=ANSI;
 END
@endcode

Session variable changes are usually done from the client via
``SET @@...`` or ``SELECT @@... :=
 1``, but can also be done via:

- stored procedures

- triggers

- connection setup

 - ``@@character_set_server``
@note
 Part of this functionality is provided in the MySQL C/S %Protocol via
 ``WL#4797`` ``SESSION_SYSVAR_TRACKER`` and the initial handshake
 packet.

## Session State Changed {#notices_Session_State_Changed}

Via @ref Mysqlx::Notice::SessionStateChanged.

- Account Expired while
 @ref mysqlx_protocol_authentication "Authentication"

- current schema changes: ``USE ...``

- sever-side generated primary keys (like ``AUTO_INCREMENT``)

- rows-found, rows-matched, rows-affected

@par CURRENT_SCHEMA
 Sent after statement that changes the current schema like
 ``USE ...``
@warning Not supported yet

@par GENERATED_INSERT_ID
 Sent after an ID was created by an INSERT-operation.
@note
 Multiple ``GENERATED_INSERT_ID`` notices may be sent per message
 sequence. Stored Procedures, Multi-Row INSERTs, and so on.

@par ROWS_FOUND
 Rows that would be found if ``LIMIT`` wasn't applied (see
 ``SQL_CALC_FOUND_ROWS``)
@warning Not supported yet

@par ROWS_AFFECTED
 Rows affected by a modifying statement

@par ROWS_MATCHED
 Rows matched by the criteria of a modifying statement (``UPDATE``,
 ``INSERT``, ``DELETE``, ...)
@note
 ``ROWS_AFFECTED`` and ``ROWS_MATCHED`` where sent in the MySQL
 C/S %Protocol as plain text ``info`` for a ``OK`` packet after an
 ``UPDATE``:
@code{unparsed}
 Rows matched: 0 Changed: 0 Warnings: 0
@endcode

@par ACCOUNT_EXPIRED
 Sent after a successful authentication before
 @ref Mysqlx::Session::AuthenticateOk

@par TRX_COMMITTED
 Sent after a transaction was committed. .value may contain a
 transaction identifier.
@note
 Used to track implicit, explicit and auto commits.
@warning Not supported yet

@see http://dev.mysql.com/doc/en/innodb-implicit-commit.html

@par TRX_ROLLEDBACK
 Sent after a transaction was rolled back.
@note
 Used to track implicit and explicit rollback operations.
@warning Not supported yet

@see http://dev.mysql.com/doc/en/innodb-implicit-commit.html

@par SESSION_ID
 Sent after a session ID is assigned by the server.
@note
 The MySQL C/S provided some of this information via functions:
| Parameter | [Information Functions](https://dev.mysql.com/doc/en/information-functions.html)|
|-----------------------|---------------------------------------------------------------------------------|
| CURRENT_SCHEMA | DATABASE() |
| GENERATED_INSERT_ID | LAST_INSERT_ID() |
| ROWS_FOUND | FOUND_ROWS() |
| ROWS_AFFECTED | ROW_COUNT() |
| SESSION_ID | CONNECTION_ID() |

*/