testdrive: add built-in mz_system and materialize connections

.agents/skills/mz-limits-test/SKILL.md

@@ -42,7 +42,7 @@ class Generator:
         """Records EXPLAIN query for timing and prints `> {query}`."""
 ```
 
-`header()` is inherited - it resets the `public` schema and grants privileges. `footer()` prints a blank line. `generate()` calls `header()` → `body()` → `footer()`.
+`header()` is inherited - it resets the `public` schema and grants privileges. `footer()` prints a blank line. `generate()` calls `header()` → `body()` → `footer()`. `mz_system` is a built-in testdrive connection, so `$ postgres-execute connection=mz_system` works in `body()` without any registration.
 
 ## How to Add a New Limits Test
 

.agents/skills/mz-test/SKILL.md

@@ -84,18 +84,16 @@ bin/mzcompose --find testdrive run default -- FILENAME.td
 
 `FILENAME.td` is a file in `test/testdrive/`, relative to that directory (not the repo root).
 
-`connection=mz_system` is NOT a built-in testdrive connection. A `.td` that uses
-`$ postgres-execute connection=mz_system` (e.g. for `ALTER SYSTEM SET`) must
-first register it:
+`mz_system` and `materialize` are built-in testdrive connections, so
+`$ postgres-execute connection=mz_system` (e.g. for `ALTER SYSTEM SET`) works
+without a prior registration. Any other connection name must first be
+registered:
 
 ```
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
+$ postgres-connect name=conn1 url=postgres://materialize:materialize@${testdrive.materialize-sql-addr}
 ```
 
-Omitting the line fails in CI with `connection 'mz_system' not found`. When
-verifying a `.td` locally, run it as written (bare `mz_system` name), not a copy
-with the full URL hand-substituted into `connection=...`, since the URL form
-passes locally while the committed bare-name form fails CI.
+Using an unregistered name fails with `connection 'conn1' not found`.
 
 Some compositions (e.g. platform-checks, upgrade, pg-cdc multi-version) run the
 same `.td` file against multiple Materialize versions. When a change alters

doc/developer/testdrive.md

@@ -572,6 +572,13 @@ CREATE TABLE postgres_execute (f1 INTEGER);
 
 If any of the statements fail, the entire test will fail. Any result sets returned from the server are ignored and not checked for correctness.
 
+Two connection names are built in and can be used without a prior `$ postgres-connect` registration: `mz_system` connects as the `mz_system` user via the internal SQL address (e.g. for `ALTER SYSTEM SET`), and `materialize` connects as the `materialize` user via the external SQL address. The connection is established on first use and is then cached like a named connection created by `$ postgres-connect`, so repeated uses share a session. An explicit `$ postgres-connect` with the same name takes precedence.
+
+```
+$ postgres-execute connection=mz_system
+ALTER SYSTEM SET max_tables = 1000;
+```
+
 With `background=true` (only valid for URL connections), the statements execute in the background while the test continues. The task is joined at the end of the file, and a failure or a task that does not complete within the default timeout fails the test.
 
 #### `$ postgres-connect name=.... url=...`

misc/python/materialize/feature_benchmark/scenarios/benchmark_main.py

@@ -219,7 +219,6 @@ def init(self) -> Action:
 
     def benchmark(self) -> MeasurementSource:
         return Td(f"""
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${{testdrive.materialize-internal-sql-addr}}
 $ postgres-execute connection=mz_system
 ALTER SYSTEM SET max_result_size = 17179869184;
 
@@ -417,7 +416,6 @@ def init(self) -> Action:
 
     def benchmark(self) -> MeasurementSource:
         return Td(f"""
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${{testdrive.materialize-internal-sql-addr}}
 $ postgres-execute connection=mz_system
 ALTER SYSTEM SET max_result_size = 17179869184;
 
@@ -970,7 +968,6 @@ def init(self) -> list[Action]:
         return [
             self.view_ten(),
             TdAction(f"""
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${{testdrive.materialize-internal-sql-addr}}
 $ postgres-execute connection=mz_system
 ALTER SYSTEM SET enable_column_paged_batcher = true;
 
@@ -1033,7 +1030,6 @@ def dyncfgs(self) -> str:
     def init(self) -> list[Action]:
         return [
             TdAction(f"""
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${{testdrive.materialize-internal-sql-addr}}
 $ postgres-execute connection=mz_system
 {self.dyncfgs()}
 """),
@@ -1826,7 +1822,6 @@ def shared(self) -> Action:
 
     def init(self) -> Action:
         return TdAction(f"""
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${{testdrive.materialize-internal-sql-addr}}
 $ postgres-execute connection=mz_system
 ALTER SYSTEM SET max_sources = {self.n() * 4};
 ALTER SYSTEM SET max_tables = {self.n() * 4};
@@ -2568,7 +2563,6 @@ def init(self) -> Action:
 """ for i in range(0, self.n()))
 
         return TdAction(f"""
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${{testdrive.materialize-internal-sql-addr}}
 $ postgres-execute connection=mz_system
 ALTER SYSTEM SET max_objects_per_schema = {self.n() * 10};
 ALTER SYSTEM SET max_materialized_views = {self.n() * 2};
@@ -2658,7 +2652,6 @@ def init(self) -> Action:
 """ for q, query in enumerate(queries) for i in range(0, self.n()))
 
         return TdAction(f"""
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${{testdrive.materialize-internal-sql-addr}}
 $ postgres-execute connection=mz_system
 ALTER SYSTEM SET max_objects_per_schema = {self.n() * 100};
 ALTER SYSTEM SET max_materialized_views = {self.n() * 100};

src/testdrive/src/action/postgres/execute.rs

@@ -15,6 +15,24 @@ use crate::action::{BackgroundTask, ControlFlow, State};
 use crate::parser::BuiltinCommand;
 use crate::util::postgres::postgres_client;
 
+/// URLs for built-in connection names that resolve without a prior
+/// `postgres-connect` registration. An explicit `postgres-connect` with the
+/// same name takes precedence, since `state.postgres_clients` is consulted
+/// first.
+fn builtin_connection_url(state: &State, name: &str) -> Option<String> {
+    match name {
+        "mz_system" => Some(format!(
+            "postgres://mz_system:materialize@{}",
+            state.materialize.internal_sql_addr
+        )),
+        "materialize" => Some(format!(
+            "postgres://materialize:materialize@{}",
+            state.materialize.sql_addr
+        )),
+        _ => None,
+    }
+}
+
 async fn execute_input(cmd: BuiltinCommand, client: &Client) -> Result<(), anyhow::Error> {
     for query in cmd.input {
         println!(">> {}", query);
@@ -63,6 +81,12 @@ pub async fn run_execute(
             execute_input(cmd, &client_inner).await?;
         }
         (false, false) => {
+            if !state.postgres_clients.contains_key(&connection)
+                && let Some(url) = builtin_connection_url(state, &connection)
+            {
+                let (client, _) = postgres_client(&url, state.default_timeout).await?;
+                state.postgres_clients.insert(connection.clone(), client);
+            }
             let client = state
                 .postgres_clients
                 .get(&connection)

test/bounded-memory/mzcompose.py

@@ -533,7 +533,6 @@ class KafkaScenario(Scenario):
         + KafkaScenario.END_MARKER
         # Ensure this config works.
         + dedent("""
-            $ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
             $ postgres-execute connection=mz_system
             ALTER SYSTEM SET storage_upsert_max_snapshot_batch_buffering = 2;
             """)
@@ -608,7 +607,6 @@ class KafkaScenario(Scenario):
     Scenario(
         name="table-insert-delete",
         pre_restart=dedent("""
-            $ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
             $ postgres-execute connection=mz_system
             ALTER SYSTEM SET max_result_size = 2147483648;
 
@@ -873,7 +871,6 @@ class KafkaScenario(Scenario):
     Scenario(
         name="cardinality-estimate-disjunction",
         pre_restart=dedent("""
-            $ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
             $ postgres-execute connection=mz_system
             ALTER SYSTEM SET ENABLE_CARDINALITY_ESTIMATES TO TRUE;
 
@@ -1190,7 +1187,6 @@ class KafkaScenario(Scenario):
             # * Lgalloc disabled to force more memory pressure.
             # * Index options to enable retained history.
             # * Finally, enable backpressure.
-            $ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
             $ postgres-execute connection=mz_system
             ALTER SYSTEM SET min_timestamp_interval = '10ms';
             ALTER SYSTEM SET enable_lgalloc = false;
@@ -1299,7 +1295,6 @@ class KafkaScenario(Scenario):
     Scenario(
         name="copy-to-from-s3",
         pre_restart=dedent(f"""
-            $ postgres-connect name=mz_system url=postgres://mz_system:materialize@${{testdrive.materialize-internal-sql-addr}}
             $ postgres-execute connection=mz_system
             ALTER SYSTEM SET max_result_size = 2147483648;
 

test/cluster/query-without-default-cluster/query-without-default-cluster.td

@@ -7,8 +7,6 @@
 # the Business Source License, use of this software will be governed
 # by the Apache License, Version 2.0.
 
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
-
 $ postgres-execute connection=mz_system
 DROP CLUSTER quickstart CASCADE
 

test/cluster/resources/resource-limits.td

@@ -7,7 +7,6 @@
 # the Business Source License, use of this software will be governed
 # by the Apache License, Version 2.0.
 
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
 $ postgres-connect name=mz_analytics url=postgres://mz_analytics:materialize@${testdrive.materialize-internal-sql-addr}
 
 ! ALTER SYSTEM SET max_tables TO 42

test/launchdarkly/mzcompose.py

@@ -223,7 +223,6 @@ def sys(command: str) -> None:
             c.testdrive(
                 "\n".join(
                     [
-                        "$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}",
                         "$ postgres-execute connection=mz_system",
                         command,
                     ]
@@ -390,7 +389,6 @@ def run_scoped_feature_flag_cases(
             c.testdrive(
                 "\n".join(
                     [
-                        "$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}",
                         "$ postgres-execute connection=mz_system",
                         "CREATE CLUSTER ld_legacy SIZE 'scale=1,workers=1,legacy'",
                         "CREATE CLUSTER ld_role SIZE 'scale=1,workers=1,legacy'",
@@ -436,7 +434,6 @@ def run_scoped_feature_flag_cases(
             c.testdrive(
                 "\n".join(
                     [
-                        "$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}",
                         "$ postgres-execute connection=mz_system",
                         "DROP CLUSTER ld_role",
                         "CREATE CLUSTER ld_role SIZE 'scale=1,workers=1,legacy'",
@@ -562,7 +559,6 @@ def run_scoped_feature_flag_cases(
             c.testdrive(
                 "\n".join(
                     [
-                        "$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}",
                         "$ postgres-execute connection=mz_system",
                         "CREATE CLUSTER ld_sync SIZE 'scale=1,workers=1,legacy'",
                     ]

test/legacy-upgrade/create-in-v0.131.0-alter-table.td

@@ -7,8 +7,6 @@
 # the Business Source License, use of this software will be governed
 # by the Apache License, Version 2.0.
 
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
-
 $ postgres-execute connection=mz_system
 ALTER SYSTEM SET enable_alter_table_add_column = true;
 

test/legacy-upgrade/create-in-v0.62.0-returning-keyword.td

@@ -7,8 +7,6 @@
 # the Business Source License, use of this software will be governed
 # by the Apache License, Version 2.0.
 
-$ postgres-connect name=materialize url=postgres://materialize:materialize@${testdrive.materialize-sql-addr}
-
 # In v0.62+, `returning` must be quoted when used as an identifier.
 $ postgres-execute connection=materialize
 CREATE VIEW view_with_returning AS SELECT "returning" FROM (VALUES (1)) _ ("returning")

test/legacy-upgrade/create-in-v0.68.0-comment.td

@@ -7,8 +7,6 @@
 # the Business Source License, use of this software will be governed
 # by the Apache License, Version 2.0.
 
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
-
 $[version<=12600] postgres-execute connection=mz_system
 ALTER SYSTEM SET enable_comment = true;
 

test/legacy-upgrade/create-in-v0.71.0-role-var.td

@@ -7,6 +7,4 @@
 # the Business Source License, use of this software will be governed
 # by the Apache License, Version 2.0.
 
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
-
 > ALTER ROLE materialize SET application_name TO foo_bar_baz;

test/limits/mzcompose.py

@@ -91,9 +91,6 @@ class Generator:
     @classmethod
     def header(cls) -> None:
         print(f"\n#\n# {cls}\n#\n")
-        print(
-            "$ postgres-connect name=mz_system url=postgres://mz_system@materialized:6877/materialize"
-        )
         print("$ postgres-execute connection=mz_system")
         print("DROP SCHEMA IF EXISTS public CASCADE;")
         print(f"CREATE SCHEMA public /* {cls} */;")

test/mysql-cdc-old-syntax/mysql-cdc.td

@@ -131,7 +131,6 @@ CREATE TABLE another_schema.another_table (f1 TEXT);
 INSERT INTO another_schema.another_table VALUES ('123');
 
 # Sneak in a test for mysql_source_snapshot_max_execution_time
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
 $ postgres-execute connection=mz_system
 ALTER SYSTEM SET mysql_source_snapshot_max_execution_time = 1000
 
@@ -150,7 +149,6 @@ $ postgres-execute connection=mz_system
 ALTER SYSTEM SET mysql_source_snapshot_max_execution_time = 0
 
 # Validate mysql_source_snapshot_lock_wait_timeout
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
 $ postgres-execute connection=mz_system
 ALTER SYSTEM SET mysql_source_snapshot_lock_wait_timeout = 1
 

test/mysql-cdc/mysql-cdc.td

@@ -131,7 +131,6 @@ CREATE TABLE another_schema.another_table (f1 TEXT);
 INSERT INTO another_schema.another_table VALUES ('123');
 
 # Sneak in a test for mysql_source_snapshot_max_execution_time
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
 $ postgres-execute connection=mz_system
 ALTER SYSTEM SET mysql_source_snapshot_max_execution_time = 10000
 
@@ -152,7 +151,6 @@ $ postgres-execute connection=mz_system
 ALTER SYSTEM SET mysql_source_snapshot_max_execution_time = 0
 
 # Validate mysql_source_snapshot_lock_wait_timeout
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
 $ postgres-execute connection=mz_system
 ALTER SYSTEM SET mysql_source_snapshot_lock_wait_timeout = 1
 

test/mysql-cdc/proxied/connect_timeout.td

@@ -13,7 +13,6 @@
 > DROP SECRET IF EXISTS mysql_pass;
 
 # Override MySQL connect timeout to 3s
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
 $ postgres-execute connection=mz_system
 ALTER SYSTEM SET mysql_source_connect_timeout = '3s';
 

test/mysql-cdc/proxied/connect_timeout_latency.td

@@ -13,7 +13,6 @@
 > DROP SECRET IF EXISTS mysql_pass;
 
 # Override MySQL connect timeout to 2s
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
 $ postgres-execute connection=mz_system
 ALTER SYSTEM SET mysql_source_connect_timeout = '2s';
 
@@ -41,7 +40,6 @@ $ http-request method=POST url=http://toxiproxy:8474/proxies/mysql/toxics conten
 contains:connection attempt timed out after 2s
 
 # Override MySQL connect timeout to 30s
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
 $ postgres-execute connection=mz_system
 ALTER SYSTEM SET mysql_source_connect_timeout = '30s';
 

test/pg-cdc-old-syntax/pg-cdc.td

@@ -156,7 +156,6 @@ CREATE PUBLICATION another_publication FOR TABLE another_schema.another_table;
 # $ postgres-verify-slot connection=postgres://postgres:postgres@postgres slot=materialize_% active=false
 
 # Sneak in a test for pg_source_snapshot_statement_timeout, pg_source_wal_sender_timeout
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
 $ postgres-execute connection=mz_system
 ALTER SYSTEM SET pg_source_snapshot_statement_timeout = 1000;
 ALTER SYSTEM SET pg_source_wal_sender_timeout = 0;

test/pg-cdc/pg-cdc.td

@@ -161,7 +161,6 @@ CREATE PUBLICATION another_publication FOR TABLE another_schema.another_table;
 # $ postgres-verify-slot connection=postgres://postgres:postgres@postgres slot=materialize_% active=false
 
 # Sneak in a test for pg_source_snapshot_statement_timeout, pg_source_wal_sender_timeout
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
 $ postgres-execute connection=mz_system
 ALTER SYSTEM SET pg_source_snapshot_statement_timeout = 1000;
 ALTER SYSTEM SET pg_source_wal_sender_timeout = 0;

test/pg-cdc/verify-offset-committed-on-startup.td

@@ -46,7 +46,6 @@ ANALYZE;
 
 # Configure Materialize
 
-$ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
 $ postgres-execute connection=mz_system
 ALTER SYSTEM SET storage_statistics_collection_interval = 100
 ALTER SYSTEM SET storage_statistics_interval = 200

test/restart/mzcompose.py

@@ -294,8 +294,6 @@ def workflow_allowed_cluster_replica_sizes(c: Composition) -> None:
     c.testdrive(
         service="testdrive_no_reset",
         input=dedent("""
-            $ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
-
             # We can create a cluster with sizes 'scale=1,workers=1' and 'scale=1,workers=2'
             > CREATE CLUSTER test REPLICAS (r1 (SIZE 'scale=1,workers=1'), r2 (SIZE 'scale=1,workers=2'))
 
@@ -319,8 +317,6 @@ def workflow_allowed_cluster_replica_sizes(c: Composition) -> None:
     c.testdrive(
         service="testdrive_no_reset",
         input=dedent("""
-            $ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
-
             # Cluster replica of disallowed sizes still exist
             > SHOW CLUSTER REPLICAS WHERE cluster = 'test'
             test r1 scale=1,workers=1 true ""
@@ -354,8 +350,6 @@ def workflow_allowed_cluster_replica_sizes(c: Composition) -> None:
             > SHOW allowed_cluster_replica_sizes
             "\\"scale=1,workers=1\\", \\"scale=1,workers=2\\""
 
-            $ postgres-connect name=mz_system url=postgres://mz_system:materialize@${testdrive.materialize-internal-sql-addr}
-
             # Reset for following tests
             $ postgres-execute connection=mz_system
             ALTER SYSTEM RESET allowed_cluster_replica_sizes