All Products
Search

This Product

    ApsaraDB RDS:Execute hints on an ApsaraDB RDS for MySQL instance

    Document Center

    ApsaraDB RDS:Execute hints on an ApsaraDB RDS for MySQL instance

    Last Updated:Mar 30, 2026

    In a read/write splitting setup, the proxy automatically distributes queries between the primary and secondary instances. Hints let you override that routing for specific queries — directing a single query to the primary for up-to-date results, offloading a heavy read to a secondary, or targeting a named instance for diagnostic commands.

    Prerequisites

    Before you begin, ensure that you have:

    MySQL CLI requirement

    When connecting with the MySQL CLI, pass the -c flag to prevent the client from stripping comment-based hints:

    mysql -c -h <endpoint> -u <username> -p

    Without -c, the MySQL CLI removes all SQL comment hints before they reach the proxy.

    Hint syntax reference

    All hints use the standard SQL block comment format (/* ... */) and must appear immediately before the target statement.

    Note

    Hints bypass consistency and transaction constraints and have the highest routing priority. Evaluate your workloads before using hints. Hints cannot include statements that reconfigure environment variables — for example, /*FORCE_SLAVE*/ SET NAMES utf8; is not allowed and may cause errors.

    Route to primary: /*FORCE_MASTER*/

    Forces the query to the primary RDS instance. Use this when you need up-to-date data immediately after a write, such as when replication lag on secondary instances would return stale results.

    /*FORCE_MASTER*/ SELECT * FROM orders WHERE order_id = 12345;

    Route to secondary: /*FORCE_SLAVE*/

    Forces the query to a secondary RDS instance. Use this to offload read-heavy queries from the primary.

    /*FORCE_SLAVE*/ SELECT COUNT(*) FROM logs WHERE created_at > '2026-01-01';

    Route to a specific instance: /*force_node='<instance-id>'*/

    Routes a single query to the instance you specify by instance ID. If the instance is unavailable, the query fails with:

    force hint server node is not found, please check.

    The following example runs SHOW PROCESSLIST only on instance rr-bpxxxxx:

    /*force_node='rr-bpxxxxx'*/ SHOW PROCESSLIST;

    Persistent routing: /*force_proxy_internal*/

    Sets a persistent override that routes all subsequent queries to a specified instance.

    /*force_proxy_internal*/SET force_node = 'rr-bpxxxxx';

    After running this statement, every subsequent query in the session is sent to rr-bpxxxxx. If that instance is unavailable, subsequent queries fail with:

    set force node 'rr-bpxxxxx' is not found, please check.
    Warning

    Avoid /*force_proxy_internal*/ in most cases. It routes all subsequent traffic to one instance, disabling read/write splitting. If you set a read-only instance's weight to 0 and then force-route to it using any hint, the client is disconnected from that instance.

    What's next