Refactor variable system for immutability and clarity

Co-authored-by: contact <[email protected]>

Author: cursoragent

CHANGELOG.md

@@ -1,6 +1,30 @@
 # CHANGELOG.md
 
 ## unrelease
+ - **Variable System Improvements**: URL and POST parameters are now immutable, preventing accidental modification. User-defined variables created with `SET` remain mutable.
+   - **BREAKING**: `$variable` no longer accesses POST parameters. Use `:variable` instead.
+     - **What changed**: Previously, `$x` would return a POST parameter value if no GET parameter named `x` existed.
+     - **Fix**: Replace `$x` with `:x` when you need to access form field values.
+     - **Example**: Change `SELECT $username` to `SELECT :username` when reading form submissions.
+   - **BREAKING**: `SET $name` no longer overwrites GET (URL) parameters when a URL parameter with the same name exists.
+     - **What changed**: `SET $name = 'value'` would previously overwrite the URL parameter `$name`. Now it creates an independent SET variable that shadows the URL parameter.
+     - **Fix**: This is generally the desired behavior. If you need to access the original URL parameter after setting a variable with the same name, extract it from the JSON returned by `sqlpage.variables('get')`.
+     - **Example**: If your URL is `page.sql?name=john`, and you do `SET $name = 'modified'`, then:
+       - `$name` will be `'modified'` (the SET variable)
+       - The original URL parameter is still preserved and accessible:
+         - PostgreSQL: `sqlpage.variables('get')->>'name'` returns `'john'`
+         - SQLite: `json_extract(sqlpage.variables('get'), '$.name')` returns `'john'`
+         - MySQL: `JSON_UNQUOTE(JSON_EXTRACT(sqlpage.variables('get'), '$.name'))` returns `'john'`
+   - **New behavior**: Variable lookup now follows this precedence:
+     - `$variable` checks SET variables first, then URL parameters
+     - `:variable` checks SET variables first, then POST parameters  
+     - SET variables always shadow URL/POST parameters with the same name
+   - **New sqlpage.variables() filters**:
+     - `sqlpage.variables('get')` returns only URL parameters as JSON
+     - `sqlpage.variables('post')` returns only POST parameters as JSON
+     - `sqlpage.variables('set')` returns only user-defined SET variables as JSON
+     - `sqlpage.variables()` returns all variables merged together, with SET variables taking precedence
+   - **Deprecation warnings**: Using `$var` when both a URL parameter and POST parameter exist with the same name now shows a warning. In a future version, you'll need to explicitly choose between `$var` (URL) and `:var` (POST).
  - add support for postgres range types
 
 ## v0.39.1 (2025-11-08)

src/webserver/database/syntax_tree.rs

@@ -169,21 +169,20 @@ pub(super) async fn extract_req_param<'a>(
                 Some(Cow::Owned(val.as_json_str().into_owned()))
             } else {
                 let url_val = request.url_params.get(x);
-                let post_val = request.post_variables.get(x);
-                if let Some(post_val) = post_val {
-                    if let Some(url_val) = url_val {
+                if request.post_variables.contains_key(x) {
+                    if url_val.is_some() {
                         log::warn!(
-                            "Deprecation warning! There is both a URL parameter named '{x}' with value '{url_val}' and a form field named '{x}' with value '{post_val}'. \
-                            SQLPage is using the value from the form submission, but this is ambiguous, can lead to unexpected behavior, and will stop working in a future version of SQLPage. \
-                            To fix this, please rename the URL parameter to something else, and reference the form field with :{x}."
+                            "Deprecation warning! There is both a URL parameter named '{x}' and a form field named '{x}'. \
+                            SQLPage is using the URL parameter for ${x}. Please use :{x} to reference the form field explicitly."
                         );
                     } else {
-                        log::warn!("Deprecation warning! ${x} was used to reference a form field value (a POST variable) instead of a URL parameter. This will stop working soon. Please use :{x} instead.");
+                        log::warn!(
+                            "Deprecation warning! ${x} was used to reference a form field value (a POST variable). \
+                            This now uses only URL parameters. Please use :{x} instead."
+                        );
                     }
-                    Some(post_val.as_json_str())
-                } else {
-                    url_val.map(SingleOrVec::as_json_str)
                 }
+                url_val.map(SingleOrVec::as_json_str)
             }
         }
         StmtParam::Error(x) => anyhow::bail!("{x}"),

tests/sql_test_files/it_works_immutable_variables.sql

@@ -15,19 +15,17 @@ SELECT CASE
 END AS contents;
 
 SELECT CASE
-    WHEN json_extract(sqlpage.variables('get'), '$.x') = '1' THEN 'It works !'
-    ELSE 'FAIL: variables(''get'') should return only URL parameters'
+    WHEN sqlpage.variables('get') = '{"x":"1"}' THEN 'It works !'
+    ELSE 'FAIL: variables(''get'') should return only URL parameters, got: ' || sqlpage.variables('get')
 END AS contents;
 
 SELECT CASE
-    WHEN json_extract(sqlpage.variables('set'), '$.x') = 'set_value' AND
-         json_extract(sqlpage.variables('set'), '$.set_only') = 'only_in_set' THEN 'It works !'
-    ELSE 'FAIL: variables(''set'') should return only SET variables'
+    WHEN sqlpage.variables('set') = '{"x":"set_value","set_only":"only_in_set"}' THEN 'It works !'
+    ELSE 'FAIL: variables(''set'') should return only SET variables, got: ' || sqlpage.variables('set')
 END AS contents;
 
 SELECT CASE
-    WHEN json_extract(sqlpage.variables(), '$.x') = 'set_value' AND
-         json_extract(sqlpage.variables(), '$.set_only') = 'only_in_set' THEN 'It works !'
-    ELSE 'FAIL: variables() should merge all with SET taking precedence'
+    WHEN sqlpage.variables() = '{"x":"set_value","set_only":"only_in_set"}' THEN 'It works !'
+    ELSE 'FAIL: variables() should merge all with SET taking precedence, got: ' || sqlpage.variables()
 END AS contents;