environments setup-local: consolidate databricks-connect to a single managed pin

.nextchanges/cli/setup-local-dbconnect-consolidate.md

@@ -0,0 +1 @@
+`databricks environments setup-local` now removes a `databricks-connect` pin from `[project].dependencies`, an optional-dependency extra, or a dependency group when its version range conflicts with the compute target's `databricks-connect` version, so `uv sync` no longer fails with an unsatisfiable resolution when a template ships a conflicting pin. A pin that co-resolves, carries no version, or is marker-gated is left untouched, and each removed pin is reported with the new `W_DBCONNECT_CONSOLIDATED` warning. Wildcard version pins such as `==15.1.*` are now also checked for conflicts with the environment's constraints.

acceptance/localenv/constraints-only-existing/output.txt

@@ -0,0 +1,59 @@
+
+>>> [CLI] environments setup-local --serverless-version 4 --constraints-only --dry-run --output json
+{
+  "schemaVersion": 1,
+  "command": "environments setup-local",
+  "ok": true,
+  "mode": "constraints-only",
+  "dryRun": true,
+  "compute": {
+    "source": "serverless",
+    "serverlessVersion": "v4",
+    "envKey": "serverless/serverless-v4"
+  },
+  "resolved": {
+    "pythonVersion": "3.12",
+    "artifactSource": "network"
+  },
+  "greenfield": false,
+  "plan": {
+    "wouldWrite": "[TEST_TMP_DIR]/pyproject.toml",
+    "wouldBackup": "[TEST_TMP_DIR]/pyproject.toml.bak",
+    "wouldInstallPython": "3.12",
+    "diff": "--- pyproject.toml\n+++ pyproject.toml.new\n@@ -1,8 +1,15 @@\n [project]\n name = \"demo\"\n-requires-python = \"\u003e=3.10\"\n+requires-python = \"\u003e=3.12\"\n dependencies = [\"databricks-connect==15.1.*\"]\n \n [dependency-groups]\n dev = [\"databricks-connect~=16.0\"]\n docs = [\"databricks-connect==15.0.0\"]\n+\n+# managed by databricks environments setup-local — do not edit\n+[tool.uv]\n+constraint-dependencies = [\n+    \"pyarrow\u003c19\",\n+]\n+# end managed by databricks environments setup-local\n"
+  },
+  "phases": [
+    {
+      "phase": "preflight",
+      "status": "ok"
+    },
+    {
+      "phase": "resolve",
+      "status": "ok"
+    },
+    {
+      "phase": "fetch",
+      "status": "ok"
+    },
+    {
+      "phase": "merge",
+      "status": "ok"
+    },
+    {
+      "phase": "provision",
+      "status": "ok"
+    },
+    {
+      "phase": "validate",
+      "status": "ok"
+    }
+  ],
+  "warnings": [
+    {
+      "code": "W_REQUIRES_PYTHON_OVERRIDDEN",
+      "message": "requires-python \"\u003e=3.10\" is replaced by the environment's \"\u003e=3.12\""
+    }
+  ],
+  "error": null,
+  "durationMs": [DURATION_MS]
+}

acceptance/localenv/constraints-only-existing/script

@@ -0,0 +1,16 @@
+# --constraints-only omits databricks-connect entirely: no managed pin is inserted and
+# no stray is removed, so every databricks-connect requirement the user already had — in
+# [project].dependencies, dev, and a sibling group — is left byte-for-byte untouched. Only
+# requires-python and the [tool.uv] constraints are managed. The JSON diff shows this.
+cat > pyproject.toml <<'PY'
+[project]
+name = "demo"
+requires-python = ">=3.10"
+dependencies = ["databricks-connect==15.1.*"]
+
+[dependency-groups]
+dev = ["databricks-connect~=16.0"]
+docs = ["databricks-connect==15.0.0"]
+PY
+
+trace $CLI environments setup-local --serverless-version 4 --constraints-only --dry-run --output json

acceptance/localenv/constraints-only-existing/test.toml

@@ -0,0 +1,24 @@
+EnvMatrix.DATABRICKS_BUNDLE_ENGINE = ["direct"]
+
+# The script writes pyproject.toml as the merge input; --dry-run leaves it unchanged.
+Ignore = ["pyproject.toml"]
+
+[Env]
+DATABRICKS_LOCALENV_CONSTRAINT_SOURCE_URL_TEST_OVERRIDE = "$DATABRICKS_HOST"
+
+[[Server]]
+Pattern = "GET /serverless/serverless-v4/pyproject.toml"
+Response.Body = '''
+[project]
+requires-python = ">=3.12"
+
+[dependency-groups]
+dev = ["databricks-connect~=17.2.0"]
+
+[tool.uv]
+constraint-dependencies = ["pyarrow<19"]
+'''
+
+[[Repls]]
+Old = 'uv uv \S+(?: \([^)]+\))?'
+New = 'uv [UV_VERSION]'

acceptance/localenv/dbconnect-compatible-kept-check/output.txt

@@ -0,0 +1,64 @@
+
+>>> [CLI] environments setup-local --serverless-version 4 --dry-run --output json
+{
+  "schemaVersion": 1,
+  "command": "environments setup-local",
+  "ok": true,
+  "mode": "default",
+  "dryRun": true,
+  "compute": {
+    "source": "serverless",
+    "serverlessVersion": "v4",
+    "envKey": "serverless/serverless-v4"
+  },
+  "resolved": {
+    "pythonVersion": "3.12",
+    "dbconnectVersion": "17.2.0",
+    "artifactSource": "network"
+  },
+  "greenfield": false,
+  "plan": {
+    "wouldWrite": "[TEST_TMP_DIR]/pyproject.toml",
+    "wouldBackup": "[TEST_TMP_DIR]/pyproject.toml.bak",
+    "wouldInstallPython": "3.12",
+    "diff": "--- pyproject.toml\n+++ pyproject.toml.new\n@@ -1,6 +1,6 @@\n [project]\n name = \"demo\"\n-requires-python = \"\u003e=3.10\"\n+requires-python = \"\u003e=3.12\"\n dependencies = [\n     \"databricks-connect\u003e=15\",\n     \"databricks-connect ; python_version \u003c '3.13'\",\n@@ -10,5 +10,11 @@\n extra = [\"databricks-connect\"]\n \n [dependency-groups]\n-dev = [\"databricks-connect~=16.0\"]\n+dev = [\"databricks-connect~=17.2.0\"]\n test = [\"databricks-connect\u003e=15,\u003c20\"]\n+\n+# managed by databricks environments setup-local — do not edit\n+[tool.uv]\n+constraint-dependencies = [\n+]\n+# end managed by databricks environments setup-local\n"
+  },
+  "phases": [
+    {
+      "phase": "preflight",
+      "status": "ok"
+    },
+    {
+      "phase": "resolve",
+      "status": "ok"
+    },
+    {
+      "phase": "fetch",
+      "status": "ok"
+    },
+    {
+      "phase": "merge",
+      "status": "ok"
+    },
+    {
+      "phase": "provision",
+      "status": "ok"
+    },
+    {
+      "phase": "validate",
+      "status": "ok"
+    }
+  ],
+  "warnings": [
+    {
+      "code": "W_REQUIRES_PYTHON_OVERRIDDEN",
+      "message": "requires-python \"\u003e=3.10\" is replaced by the environment's \"\u003e=3.12\""
+    },
+    {
+      "code": "W_DBCONNECT_PIN_OVERRIDDEN",
+      "message": "databricks-connect \"databricks-connect~=16.0\" is replaced by the environment's \"databricks-connect~=17.2.0\""
+    }
+  ],
+  "error": null,
+  "durationMs": [DURATION_MS]
+}

acceptance/localenv/dbconnect-compatible-kept-check/script

@@ -0,0 +1,24 @@
+# Only a databricks-connect pin that provably cannot co-resolve with the managed
+# version (~=17.2.0) is removed. A pin that overlaps it (>=15), carries no version, or
+# is marker-gated resolves fine, so it is left in place — the merge does not silently
+# rewrite the user's declaration (including [project].dependencies wheel metadata) when
+# nothing is broken. The dry-run diff shows only requires-python and the dev pin change,
+# and no W_DBCONNECT_CONSOLIDATED warning is emitted.
+cat > pyproject.toml <<'PY'
+[project]
+name = "demo"
+requires-python = ">=3.10"
+dependencies = [
+    "databricks-connect>=15",
+    "databricks-connect ; python_version < '3.13'",
+]
+
+[project.optional-dependencies]
+extra = ["databricks-connect"]
+
+[dependency-groups]
+dev = ["databricks-connect~=16.0"]
+test = ["databricks-connect>=15,<20"]
+PY
+
+trace $CLI environments setup-local --serverless-version 4 --dry-run --output json

acceptance/localenv/dbconnect-compatible-kept-check/test.toml

@@ -0,0 +1,24 @@
+EnvMatrix.DATABRICKS_BUNDLE_ENGINE = ["direct"]
+
+# The script writes pyproject.toml as the merge input; --dry-run leaves it unchanged.
+Ignore = ["pyproject.toml"]
+
+[Env]
+DATABRICKS_LOCALENV_CONSTRAINT_SOURCE_URL_TEST_OVERRIDE = "$DATABRICKS_HOST"
+
+[[Server]]
+Pattern = "GET /serverless/serverless-v4/pyproject.toml"
+Response.Body = '''
+[project]
+requires-python = ">=3.12"
+
+[dependency-groups]
+dev = ["databricks-connect~=17.2.0"]
+
+[tool.uv]
+constraint-dependencies = []
+'''
+
+[[Repls]]
+Old = 'uv uv \S+(?: \([^)]+\))?'
+New = 'uv [UV_VERSION]'

acceptance/localenv/dbconnect-consolidate-check/output.txt

@@ -0,0 +1,76 @@
+
+>>> [CLI] environments setup-local --serverless-version 4 --dry-run --output json
+{
+  "schemaVersion": 1,
+  "command": "environments setup-local",
+  "ok": true,
+  "mode": "default",
+  "dryRun": true,
+  "compute": {
+    "source": "serverless",
+    "serverlessVersion": "v4",
+    "envKey": "serverless/serverless-v4"
+  },
+  "resolved": {
+    "pythonVersion": "3.12",
+    "dbconnectVersion": "17.2.0",
+    "artifactSource": "network"
+  },
+  "greenfield": false,
+  "plan": {
+    "wouldWrite": "[TEST_TMP_DIR]/pyproject.toml",
+    "wouldBackup": "[TEST_TMP_DIR]/pyproject.toml.bak",
+    "wouldInstallPython": "3.12",
+    "diff": "--- pyproject.toml\n+++ pyproject.toml.new\n@@ -1,15 +1,20 @@\n [project]\n name = \"demo\"\n-requires-python = \"\u003e=3.10\"\n+requires-python = \"\u003e=3.12\"\n dependencies = [\n     \"databricks-dlt\",\n-    \"databricks-connect==15.1.*\",\n     \"pytest\",\n ]\n \n [project.optional-dependencies]\n-extra = [\"databricks-connect==14.0.0\"]\n+extra = []\n \n [dependency-groups]\n-dev = [\"databricks-connect~=16.0\"]\n-docs = [\"databricks-connect==15.0.0\"]\n+dev = [\"databricks-connect~=17.2.0\"]\n+docs = []\n+\n+# managed by databricks environments setup-local — do not edit\n+[tool.uv]\n+constraint-dependencies = [\n+]\n+# end managed by databricks environments setup-local\n"
+  },
+  "phases": [
+    {
+      "phase": "preflight",
+      "status": "ok"
+    },
+    {
+      "phase": "resolve",
+      "status": "ok"
+    },
+    {
+      "phase": "fetch",
+      "status": "ok"
+    },
+    {
+      "phase": "merge",
+      "status": "ok"
+    },
+    {
+      "phase": "provision",
+      "status": "ok"
+    },
+    {
+      "phase": "validate",
+      "status": "ok"
+    }
+  ],
+  "warnings": [
+    {
+      "code": "W_REQUIRES_PYTHON_OVERRIDDEN",
+      "message": "requires-python \"\u003e=3.10\" is replaced by the environment's \"\u003e=3.12\""
+    },
+    {
+      "code": "W_DBCONNECT_PIN_OVERRIDDEN",
+      "message": "databricks-connect \"databricks-connect~=16.0\" is replaced by the environment's \"databricks-connect~=17.2.0\""
+    },
+    {
+      "code": "W_DBCONNECT_CONSOLIDATED",
+      "message": "databricks-connect \"databricks-connect==15.1.*\" in [project].dependencies conflicts with the environment's \"databricks-connect~=17.2.0\" and is removed; it is managed in \"dev\""
+    },
+    {
+      "code": "W_DBCONNECT_CONSOLIDATED",
+      "message": "databricks-connect \"databricks-connect==14.0.0\" in [project.optional-dependencies].extra conflicts with the environment's \"databricks-connect~=17.2.0\" and is removed; it is managed in \"dev\""
+    },
+    {
+      "code": "W_DBCONNECT_CONSOLIDATED",
+      "message": "databricks-connect \"databricks-connect==15.0.0\" in [dependency-groups].docs conflicts with the environment's \"databricks-connect~=17.2.0\" and is removed; it is managed in \"dev\""
+    }
+  ],
+  "error": null,
+  "durationMs": [DURATION_MS]
+}

acceptance/localenv/dbconnect-consolidate-check/script

@@ -0,0 +1,24 @@
+# Every stray databricks-connect pin here is disjoint from the managed version, so it
+# would make uv unsatisfiable and is removed — from [project].dependencies, an
+# optional-dependency extra, and another dependency group — leaving the single managed
+# pin in [dependency-groups].dev. The JSON diff shows each stray removed, with one
+# W_DBCONNECT_CONSOLIDATED warning per removed pin (in document order).
+cat > pyproject.toml <<'PY'
+[project]
+name = "demo"
+requires-python = ">=3.10"
+dependencies = [
+    "databricks-dlt",
+    "databricks-connect==15.1.*",
+    "pytest",
+]
+
+[project.optional-dependencies]
+extra = ["databricks-connect==14.0.0"]
+
+[dependency-groups]
+dev = ["databricks-connect~=16.0"]
+docs = ["databricks-connect==15.0.0"]
+PY
+
+trace $CLI environments setup-local --serverless-version 4 --dry-run --output json

acceptance/localenv/dbconnect-consolidate-check/test.toml

@@ -0,0 +1,24 @@
+EnvMatrix.DATABRICKS_BUNDLE_ENGINE = ["direct"]
+
+# The script writes pyproject.toml as the merge input; --dry-run leaves it unchanged.
+Ignore = ["pyproject.toml"]
+
+[Env]
+DATABRICKS_LOCALENV_CONSTRAINT_SOURCE_URL_TEST_OVERRIDE = "$DATABRICKS_HOST"
+
+[[Server]]
+Pattern = "GET /serverless/serverless-v4/pyproject.toml"
+Response.Body = '''
+[project]
+requires-python = ">=3.12"
+
+[dependency-groups]
+dev = ["databricks-connect~=17.2.0"]
+
+[tool.uv]
+constraint-dependencies = []
+'''
+
+[[Repls]]
+Old = 'uv uv \S+(?: \([^)]+\))?'
+New = 'uv [UV_VERSION]'

acceptance/localenv/merge-warnings-json/output.txt

@@ -21,7 +21,7 @@
     "wouldWrite": "[TEST_TMP_DIR]/pyproject.toml",
     "wouldBackup": "[TEST_TMP_DIR]/pyproject.toml.bak",
     "wouldInstallPython": "3.12",
-    "diff": "--- pyproject.toml\n+++ pyproject.toml.new\n@@ -1,9 +1,17 @@\n [project]\n name = \"demo\"\n-requires-python = \"\u003e=3.10\"\n+requires-python = \"\u003e=3.12\"\n dependencies = [\"pyarrow==21.0.0\"]\n \n [dependency-groups]\n-dev = [\"databricks-connect~=16.0.0\", {include-group = \"spark\"}]\n+dev = [\"databricks-connect~=17.2.0\", {include-group = \"spark\"}]\n spark = [\"databricks-connect==15.0.0\"]\n qa = [\"pandas==4.0.0\"]\n+\n+# managed by databricks environments setup-local — do not edit\n+[tool.uv]\n+constraint-dependencies = [\n+    \"pyarrow\u003c19\",\n+    \"pandas\u003c3\",\n+]\n+# end managed by databricks environments setup-local\n"
+    "diff": "--- pyproject.toml\n+++ pyproject.toml.new\n@@ -1,9 +1,17 @@\n [project]\n name = \"demo\"\n-requires-python = \"\u003e=3.10\"\n+requires-python = \"\u003e=3.12\"\n dependencies = [\"pyarrow==21.0.0\"]\n \n [dependency-groups]\n-dev = [\"databricks-connect~=16.0.0\", {include-group = \"spark\"}]\n-spark = [\"databricks-connect==15.0.0\"]\n+dev = [\"databricks-connect~=17.2.0\", {include-group = \"spark\"}]\n+spark = []\n qa = [\"pandas==4.0.0\"]\n+\n+# managed by databricks environments setup-local — do not edit\n+[tool.uv]\n+constraint-dependencies = [\n+    \"pyarrow\u003c19\",\n+    \"pandas\u003c3\",\n+]\n+# end managed by databricks environments setup-local\n"
   },
   "phases": [
     {
@@ -59,8 +59,8 @@
       "message": "databricks-connect \"databricks-connect~=16.0.0\" is replaced by the environment's \"databricks-connect~=17.2.0\""
     },
     {
-      "code": "W_DBCONNECT_PIN_DUPLICATED",
-      "message": "databricks-connect \"databricks-connect==15.0.0\" is not rewritten by the merge; the environment's \"databricks-connect~=17.2.0\" sits in \"dev\" alongside it, and no version satisfies both"
+      "code": "W_DBCONNECT_CONSOLIDATED",
+      "message": "databricks-connect \"databricks-connect==15.0.0\" in [dependency-groups].spark conflicts with the environment's \"databricks-connect~=17.2.0\" and is removed; it is managed in \"dev\""
     },
     {
       "code": "W_USER_CONSTRAINT_CONFLICT",

acceptance/localenv/merge-warnings/output.txt

@@ -2,7 +2,7 @@
 >>> [CLI] environments setup-local --serverless-version 4 --dry-run
 warning: requires-python ">=3.10" is replaced by the environment's ">=3.12"
 warning: databricks-connect "databricks-connect~=16.0.0" is replaced by the environment's "databricks-connect~=17.2.0"
-warning: databricks-connect "databricks-connect==15.0.0" is not rewritten by the merge; the environment's "databricks-connect~=17.2.0" sits in "dev" alongside it, and no version satisfies both
+warning: databricks-connect "databricks-connect==15.0.0" in [dependency-groups].spark conflicts with the environment's "databricks-connect~=17.2.0" and is removed; it is managed in "dev"
 warning: dependency "pyarrow==21.0.0" conflicts with the environment constraint "pyarrow<19"
 warning: dependency "pandas==4.0.0" conflicts with the environment constraint "pandas<3"
 Plan: [TEST_TMP_DIR]/pyproject.toml

acceptance/localenv/wildcard-constraint-conflict-check/output.txt

@@ -0,0 +1,8 @@
+
+>>> [CLI] environments setup-local --serverless-version 4 --dry-run
+warning: requires-python ">=3.10" is replaced by the environment's ">=3.12"
+warning: dependency "pyarrow==18.*" conflicts with the environment constraint "pyarrow~=19.0"
+Plan: [TEST_TMP_DIR]/pyproject.toml
+  changed region: requires-python
+  changed region: tool.uv.constraint-dependencies
+Check complete. No files were modified.