Escape only "[" "]" for db url parsing (tortoise#2092)

Author: abondar

docs/databases.rst

@@ -30,6 +30,37 @@ If password contains special characters it need to be URL encoded:
     >>> urllib.parse.quote_plus("kx%jj5/g")
     'kx%25jj5%2Fg'
 
+.. note::
+
+    Passwords containing ``%`` followed by valid hex digits (e.g., ``foo%bar``)
+    may not be parsed correctly from a URL string, because the URL parser interprets
+    such sequences as percent-encoded characters. If your password contains ``%``,
+    either percent-encode it (as shown above) or use the dict-based configuration
+    format instead, which bypasses URL parsing entirely:
+
+    .. code-block:: python3
+
+        await Tortoise.init(config={
+            "connections": {
+                "default": {
+                    "engine": "tortoise.backends.asyncpg",
+                    "credentials": {
+                        "host": "127.0.0.1",
+                        "port": 5432,
+                        "user": "myuser",
+                        "password": "ADM[r$VIS]",
+                        "database": "mydb",
+                    }
+                }
+            },
+            "apps": {
+                "models": {
+                    "models": ["myapp.models"],
+                    "default_connection": "default",
+                }
+            },
+        })
+
 The supported ``DB_TYPE``:
 
 ``sqlite``:

tests/backends/test_db_url.py

@@ -196,6 +196,55 @@ def test_postgres_params():
         }
 
 
+def test_mysql_special_chars_in_password():
+    db_url = "mysql://some_user:ADM[r$VIS]@test-rds.somedata.net:3306/mydb?charset=utf8mb4"
+    res = expand_db_url(db_url)
+    assert res == {
+        "engine": "tortoise.backends.mysql",
+        "credentials": {
+            "database": "mydb",
+            "host": "test-rds.somedata.net",
+            "password": "ADM[r$VIS]",
+            "port": 3306,
+            "user": "some_user",
+            "charset": "utf8mb4",
+            "sql_mode": "STRICT_TRANS_TABLES",
+        },
+    }
+
+
+def test_mysql_unbalanced_brackets_in_password():
+    db_url = "mysql://fail_user:DMK_15[ZWIN6@test-rds.somedata.net:3306/mydb2?charset=utf8mb4"
+    res = expand_db_url(db_url)
+    assert res == {
+        "engine": "tortoise.backends.mysql",
+        "credentials": {
+            "database": "mydb2",
+            "host": "test-rds.somedata.net",
+            "password": "DMK_15[ZWIN6",
+            "port": 3306,
+            "user": "fail_user",
+            "charset": "utf8mb4",
+            "sql_mode": "STRICT_TRANS_TABLES",
+        },
+    }
+
+
+def test_mysql_literal_percent_in_password_is_corrupted():
+    # Known limitation: a literal '%' followed by valid hex (e.g. '%ba') gets
+    # decoded by unquote_plus, corrupting the password. Users must pre-encode
+    # '%' as '%25' in their URLs to avoid this.
+    db_url = "mysql://user:foo%bar@127.0.0.1:3306/mydb"
+    res = expand_db_url(db_url)
+    assert res["credentials"]["password"] != "foo%bar"
+
+
+def test_mysql_pre_encoded_percent_in_password():
+    db_url = "mysql://user:foo%25bar@127.0.0.1:3306/mydb"
+    res = expand_db_url(db_url)
+    assert res["credentials"]["password"] == "foo%bar"
+
+
 def test_mysql_basic():
     res = expand_db_url("mysql://root:@127.0.0.1:33060/test")
     assert res == {

tests/test_issue_404.py

@@ -130,47 +130,36 @@
 
 
 def _quote_url_userinfo(db_url: str) -> str:
-    """Quote special characters in username and password to avoid URL parsing issues.
+    """Encode characters in the userinfo section that break urlparse.
 
-    urlparse fails when passwords contain characters like '[' or ']' because it
-    tries to parse them as IPv6 addresses. This function percent-encodes the userinfo
-    part (username:password) while leaving the rest of the URL intact.
-
-    Only characters that cause parsing issues (like '[' and ']') are encoded.
-    Already percent-encoded sequences (like %25) are preserved.
+    Specifically, '[' and ']' cause urlparse to fail with a ValueError because
+    it interprets them as IPv6 address brackets. This encodes only those characters,
+    leaving everything else (including '%') untouched.
     """
-    # Find the scheme delimiter
     scheme_end = db_url.find("://")
     if scheme_end == -1:
         return db_url
 
-    scheme = db_url[: scheme_end + 3]  # Include "://"
+    scheme = db_url[: scheme_end + 3]
     rest = db_url[scheme_end + 3 :]
 
-    # Find the userinfo section (everything before @)
     at_pos = rest.find("@")
     if at_pos == -1:
-        # No credentials
         return db_url
 
     userinfo = rest[:at_pos]
     after_userinfo = rest[at_pos:]
 
-    # Split userinfo into username and password
     colon_pos = userinfo.find(":")
     if colon_pos == -1:
-        # No password, just username
-        # Only quote characters that cause parsing issues
-        username = urlparse.quote(userinfo, safe="%")
+        username = userinfo.replace("[", "%5B").replace("]", "%5D")
         return scheme + username + after_userinfo
-    else:
-        username = userinfo[:colon_pos]
-        password = userinfo[colon_pos + 1 :]
-        # Quote username and password, but preserve already-encoded sequences
-        # We keep % as safe so existing percent-encoded chars aren't double-encoded
-        username_quoted = urlparse.quote(username, safe="%")
-        password_quoted = urlparse.quote(password, safe="%")
-        return scheme + username_quoted + ":" + password_quoted + after_userinfo
+
+    username = userinfo[:colon_pos]
+    password = userinfo[colon_pos + 1 :]
+    username_quoted = username.replace("[", "%5B").replace("]", "%5D")
+    password_quoted = password.replace("[", "%5B").replace("]", "%5D")
+    return scheme + username_quoted + ":" + password_quoted + after_userinfo
 
 
 def expand_db_url(db_url: str, testing: bool = False) -> dict: