feat(query): support session WAP branch routing

[zhyass]

I hereby agree to the terms of the CLA available at: https://docs.databend.com/dev/policies/cla/

Summary

Adds a wap_branch session setting to route unqualified table references through table branches for WAP workflows. Reads use the configured branch when it exists and fall back to the base table when it does not; writes target the configured branch and fail if the branch is missing.

This also keeps persisted definitions stable by suppressing session WAP routing when validating or replaying stored view/index SQL, including view schema inference, privilege checks, planner cache paths, CTE binding, DESCRIBE, system.columns, system.statistics, and CREATE TABLE LIKE view.

Adds sqllogictest coverage for read/write routing, explicit branch precedence, missing branch behavior, persisted view/index semantics, planner cache suppression, CTE suppression propagation, and view metadata consistency.

Tests

• Unit Test
• Logic Test
• Benchmark Test
• No Test - Explain why

Type of change

• Bug Fix (non-breaking change which fixes an issue)
• New Feature (non-breaking change which adds functionality)
• Breaking Change (fix or feature that could cause existing functionality not to work as expected)
• Documentation Update
• Refactoring
• Performance Improvement
• Other (please describe):

---

This change is 

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9efcdad9fd

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Swish!

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[zhyass]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. You're on a roll.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[dantengsky]

@zhyass

It seems that DESCRIBE xxx does not respect the wap_branch setting yet. Is that expected?

mysql>   CREATE OR REPLACE DATABASE repro_describe_wap;
Query OK, 0 rows affected (0.069 sec)

mysql>   USE repro_describe_wap;
Database changed
mysql>
mysql>   CREATE TABLE t(a INT, b STRING);
Query OK, 0 rows affected (0.044 sec)

mysql>   INSERT INTO t VALUES (1, 'base');
+-------------------------+
| number of rows inserted |
+-------------------------+
|                       1 |
+-------------------------+
1 row in set (0.053 sec)
Read 1 rows, 22.00 B in 0.040 sec., 24.74 rows/sec., 544.24 B/sec.

mysql>
mysql>   ALTER TABLE t CREATE BRANCH dev;
Query OK, 0 rows affected (0.032 sec)

mysql>   ALTER TABLE t/dev ADD COLUMN c INT;
Query OK, 0 rows affected (0.043 sec)

mysql>   UPDATE t/dev SET c = 10 WHERE a = 1;
+------------------------+
| number of rows updated |
+------------------------+
|                      1 |
+------------------------+
1 row in set (0.130 sec)
Read 1 rows, 30.00 B in 0.086 sec., 11.65 rows/sec., 349.62 B/sec.

mysql>   INSERT INTO t/dev VALUES (2, 'branch', 20);
+-------------------------+
| number of rows inserted |
+-------------------------+
|                       1 |
+-------------------------+
1 row in set (0.055 sec)
Read 1 rows, 27.00 B in 0.037 sec., 26.75 rows/sec., 722.30 B/sec.

mysql>
mysql>   SET wap_branch = 'dev';
Query OK, 0 rows affected (0.004 sec)

mysql>
mysql>   SELECT * FROM t ORDER BY a;
+------+--------+------+
| a    | b      | c    |
+------+--------+------+
|    1 | base   |   10 |
|    2 | branch |   20 |
+------+--------+------+
2 rows in set (0.033 sec)
Read 2 rows, 72.00 B in 0.013 sec., 149.63 rows/sec., 5.26 KiB/sec.

mysql>   DESCRIBE t;
+-------+---------+------+---------+-------+
| Field | Type    | Null | Default | Extra |
+-------+---------+------+---------+-------+
| a     | INT     | YES  | NULL    |       |
| b     | VARCHAR | YES  | NULL    |       |
+-------+---------+------+---------+-------+
2 rows in set (0.014 sec)
Read 0 rows, 0.00 B in 0.002 sec., 0 rows/sec., 0.00 B/sec.

mysql>   SHOW FIELDS FROM t;
+-------+---------+------+---------+-------+
| Field | Type    | Null | Default | Extra |
+-------+---------+------+---------+-------+
| a     | INT     | YES  | NULL    |       |
| b     | VARCHAR | YES  | NULL    |       |
+-------+---------+------+---------+-------+
2 rows in set (0.013 sec)
Read 0 rows, 0.00 B in 0.002 sec., 0 rows/sec., 0.00 B/sec.

mysql>   DESCRIBE t/dev;
+-------+---------+------+---------+-------+
| Field | Type    | Null | Default | Extra |
+-------+---------+------+---------+-------+
| a     | INT     | YES  | NULL    |       |
| b     | VARCHAR | YES  | NULL    |       |
| c     | INT     | YES  | NULL    |       |
+-------+---------+------+---------+-------+
3 rows in set (0.055 sec)
Read 0 rows, 0.00 B in 0.015 sec., 0 rows/sec., 0.00 B/sec.


mysql> select version();
+----------------------------------------------------------------------------------------+
| version()                                                                              |
+----------------------------------------------------------------------------------------+
| 8.0.90-v1.2.911-nightly-360b39db75(rust-1.94.0-nightly-2026-06-16T10:15:42.479960000Z) |
+----------------------------------------------------------------------------------------+
1 row in set (0.037 sec)
Read 1 rows, 1.00 B in 0.009 sec., 115.67 rows/sec., 115.67 B/sec.

  SET enable_experimental_table_ref=1;

  CREATE OR REPLACE DATABASE repro_describe_wap;
  USE repro_describe_wap;

  CREATE TABLE t(a INT, b STRING);
  INSERT INTO t VALUES (1, 'base');

  ALTER TABLE t CREATE BRANCH dev;
  ALTER TABLE t/dev ADD COLUMN c INT;
  UPDATE t/dev SET c = 10 WHERE a = 1;
  INSERT INTO t/dev VALUES (2, 'branch', 20);

  SET wap_branch = 'dev';

  SELECT * FROM t ORDER BY a;
  DESCRIBE t;
  SHOW FIELDS FROM t;
  DESCRIBE t/dev;