fix!: PHOENIX_POSTGRES_HOST should not be split (#9087)

Author: RogerHYang

MIGRATION.md

@@ -1,5 +1,25 @@
 # Migrations
 
+## v11.x to v12.0.0
+
+### PostgreSQL Connection Environment Variables
+
+**Breaking Change**: Specifying port numbers in `PHOENIX_POSTGRES_HOST` is no longer supported.
+
+**Before**:
+```shell
+export PHOENIX_POSTGRES_HOST=localhost:5432
+```
+
+**After**:
+```shell
+export PHOENIX_POSTGRES_HOST=localhost
+export PHOENIX_POSTGRES_PORT=5432
+```
+
+**Impact**: If you were setting `PHOENIX_POSTGRES_HOST` with a port (e.g., `localhost:5432`), you must now separate the host and port into their respective environment variables.
+
+
 ## v10.0.0 to v11.0.0
 
 This release is entirely encapsulated in a set of new tables. Have a nice release!

src/phoenix/config.py

@@ -1123,16 +1123,10 @@ def __init__(self, message: Optional[str] = None) -> None:
         super().__init__(message)
 
 
-# LEGACY: Regex for backward compatibility with host:port parsing in PHOENIX_POSTGRES_HOST
-_HOST_PORT_REGEX = re.compile(r"^[^:]+:\d{1,5}$")
-
-
 def get_env_postgres_connection_str() -> Optional[str]:
     """
     Build PostgreSQL connection string from environment variables.
-
-    LEGACY: Supports host:port parsing in PHOENIX_POSTGRES_HOST for backward compatibility.
-    """  # noqa: E501
+    """
     if not (
         (pg_host := getenv(ENV_PHOENIX_POSTGRES_HOST, "").rstrip("/"))
         and (pg_user := getenv(ENV_PHOENIX_POSTGRES_USER))
@@ -1142,10 +1136,6 @@ def get_env_postgres_connection_str() -> Optional[str]:
     pg_port = getenv(ENV_PHOENIX_POSTGRES_PORT)
     pg_db = getenv(ENV_PHOENIX_POSTGRES_DB)
 
-    if _HOST_PORT_REGEX.match(pg_host):  # maintain backward compatibility
-        pg_host, parsed_port = pg_host.split(":")
-        pg_port = pg_port or parsed_port  # use the explicitly set port if provided
-
     encoded_user = quote(pg_user)
     encoded_password = quote(pg_password)
     connection_str = f"postgresql://{encoded_user}:{encoded_password}@{pg_host}"

tests/unit/test_config.py

@@ -52,20 +52,13 @@ def test_minimal_connection_string(self, monkeypatch: pytest.MonkeyPatch) -> Non
             expected = f"postgresql://{quote('user')}:{quote('pass')}@localhost"
             assert get_env_postgres_connection_str() == expected
 
-        def test_full_connection_string_with_port_override(
+        def test_full_connection_string_with_separate_port(
             self, monkeypatch: pytest.MonkeyPatch
         ) -> None:
-            """Test that explicit port overrides port in host string.
-
-            LEGACY BEHAVIOR: For backward compatibility, PHOENIX_POSTGRES_HOST can contain
-            a port (e.g., 'localhost:5432'), which gets parsed and split. However, if
-            PHOENIX_POSTGRES_PORT is explicitly set, it overrides the port from the host string.
-            This maintains compatibility with older configurations.
-            """
+            """Test connection string with all parameters including separate host and port."""
             monkeypatch.setenv("PHOENIX_POSTGRES_USER", "user")
             monkeypatch.setenv("PHOENIX_POSTGRES_PASSWORD", "pass")
-            # LEGACY: Host includes port, but explicit port should override it
-            monkeypatch.setenv("PHOENIX_POSTGRES_HOST", "localhost:5432")
+            monkeypatch.setenv("PHOENIX_POSTGRES_HOST", "localhost")
             monkeypatch.setenv("PHOENIX_POSTGRES_PORT", "9999")
             monkeypatch.setenv("PHOENIX_POSTGRES_DB", "mydb")