Deprecate setup-local --constraints-only in favour of --no-dbconnect

.nextchanges/cli/setup-local-deprecate-constraints-only.md

@@ -0,0 +1 @@
+Deprecated the `databricks environments setup-local --constraints-only` flag in favour of the orthogonal `--no-dbconnect`. The flag still works (it remains a hidden alias with identical behaviour) but is hidden from `--help` and now prints a one-line deprecation notice; it will be removed in a later release.

.nextchanges/cli/setup-local-orthogonal-flags.md

@@ -0,0 +1 @@
+Added orthogonal `--no-constraints`, `--no-dbconnect`, and `--no-provision` flags to `databricks environments setup-local`. The flags compose: `--no-constraints` skips writing the remote Python-version and dependency pins, `--no-dbconnect` skips the databricks-connect dependency, and `--no-provision` writes the project files but stops before creating the virtual environment. Phases that a flag opts out of report a new `skipped` status in `--output json`.

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

@@ -1,5 +1,6 @@
 
 >>> [CLI] environments setup-local --serverless-version 4 --constraints-only --dry-run --output json
+Flag --constraints-only has been deprecated, use --no-dbconnect instead
 {
   "schemaVersion": 1,
   "command": "environments setup-local",

acceptance/localenv/constraints-only/output.txt

@@ -1,5 +1,6 @@
 
 >>> [CLI] environments setup-local --serverless-version 4 --constraints-only --dry-run --output json
+Flag --constraints-only has been deprecated, use --no-dbconnect instead
 {
   "schemaVersion": 1,
   "command": "environments setup-local",

acceptance/localenv/help/output.txt

@@ -18,10 +18,12 @@ Examples:
 Flags:
       --cluster-id string           cluster ID to use as the compute target
       --cluster-name string         cluster name to use as the compute target (resolved to an ID via the Clusters API)
-      --constraints-only            apply the Python version and constraints without adding the databricks-connect dependency
       --dry-run                     compute the plan without writing files or provisioning
   -h, --help                        help for setup-local
       --job-task string             job task to use as the compute target, as <job-id>.<task-key> (the task key is required)
+      --no-constraints              skip writing the remote Python version and dependency constraints
+      --no-dbconnect                skip adding the databricks-connect dependency
+      --no-provision                write the project files but skip creating the virtual environment (no uv sync, Python download, or validation)
       --serverless-version string   serverless version to use as the compute target (e.g. 5)
 
 Global Flags:

acceptance/localenv/no-constraints/output.txt

@@ -0,0 +1,60 @@
+
+>>> [CLI] environments setup-local --serverless-version 4 --no-constraints --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@@ -3,4 +3,7 @@\n requires-python = \"\u003e=3.10\"\n \n [dependency-groups]\n-dev = [\"databricks-connect~=16.0\"]\n+dev = [\"databricks-connect~=17.2.0\"]\n+\n+[tool.databricks.environment]\n+environment_version = \"4\"\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_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/no-constraints/script

@@ -0,0 +1,15 @@
+# --no-constraints leaves the remote Python version and dependency pins
+# unmanaged: the plan writes neither requires-python nor the [tool.uv] constraint
+# block, and the user's existing requires-python is left untouched. The
+# databricks-connect dependency (orthogonal to --no-constraints) is still managed.
+# The JSON plan shows the diff.
+cat > pyproject.toml <<'PY'
+[project]
+name = "demo"
+requires-python = ">=3.10"
+
+[dependency-groups]
+dev = ["databricks-connect~=16.0"]
+PY
+
+trace $CLI environments setup-local --serverless-version 4 --no-constraints --dry-run --output json

acceptance/localenv/no-constraints/test.toml

@@ -0,0 +1,23 @@
+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/no-dbconnect/output.txt

@@ -0,0 +1,59 @@
+
+>>> [CLI] environments setup-local --serverless-version 4 --no-dbconnect --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,7 +1,17 @@\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+\n+[tool.databricks.environment]\n+environment_version = \"4\"\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/no-dbconnect/script

@@ -0,0 +1,15 @@
+# --no-dbconnect is the orthogonal spelling of --constraints-only: it omits the
+# databricks-connect dependency (mode "constraints-only") while still managing
+# requires-python and the [tool.uv] constraints. Existing databricks-connect
+# requirements the user already had are left untouched.
+cat > pyproject.toml <<'PY'
+[project]
+name = "demo"
+requires-python = ">=3.10"
+dependencies = ["databricks-connect==15.1.*"]
+
+[dependency-groups]
+dev = ["databricks-connect~=16.0"]
+PY
+
+trace $CLI environments setup-local --serverless-version 4 --no-dbconnect --dry-run --output json

acceptance/localenv/no-dbconnect/test.toml

@@ -0,0 +1,23 @@
+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/no-provision-dry-run/output.txt

@@ -0,0 +1,53 @@
+
+>>> [CLI] environments setup-local --serverless-version 4 --no-provision --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": true,
+  "plan": {
+    "wouldWrite": "[TEST_TMP_DIR]/pyproject.toml",
+    "diff": "--- pyproject.toml\n+++ pyproject.toml\n@@ -1 +1,20 @@\n+[project]\n+name = \"001\"\n+version = \"0.0.0\"\n+requires-python = \"\u003e=3.12\"\n+\n+[dependency-groups]\n+dev = [\n+    \"databricks-connect~=17.2.0\",\n+]\n+\n+[tool.databricks.environment]\n+environment_version = \"4\"\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": [
+    {
+      "phase": "preflight",
+      "status": "ok"
+    },
+    {
+      "phase": "resolve",
+      "status": "ok"
+    },
+    {
+      "phase": "fetch",
+      "status": "ok"
+    },
+    {
+      "phase": "merge",
+      "status": "ok"
+    },
+    {
+      "phase": "provision",
+      "status": "skipped"
+    },
+    {
+      "phase": "validate",
+      "status": "skipped"
+    }
+  ],
+  "warnings": [],
+  "error": null,
+  "durationMs": [DURATION_MS]
+}

acceptance/localenv/no-provision-dry-run/script

@@ -0,0 +1,4 @@
+# --dry-run --no-provision: nothing is provisioned (as with any dry run), but the
+# plan reflects the real run's intent, so provision and validate report "skipped"
+# rather than the "ok" a plain dry run reports.
+trace $CLI environments setup-local --serverless-version 4 --no-provision --dry-run --output json

acceptance/localenv/no-provision-dry-run/test.toml

@@ -0,0 +1,20 @@
+EnvMatrix.DATABRICKS_BUNDLE_ENGINE = ["direct"]
+
+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", "pandas<3"]
+'''
+
+[[Repls]]
+Old = 'uv uv \S+(?: \([^)]+\))?'
+New = 'uv [UV_VERSION]'

acceptance/localenv/no-provision-text/output.txt

@@ -0,0 +1,10 @@
+
+>>> [CLI] environments setup-local --serverless-version 4 --no-provision
+✔ Project files written (provisioning skipped)
+
+  Compute target      serverless 4
+  Python              3.12
+  databricks-connect  17.2.0
+  pyproject.toml      created
+
+No virtual environment was created (--no-provision). Re-run without --no-provision to create it.

acceptance/localenv/no-provision-text/script

@@ -0,0 +1,3 @@
+# Text-mode --no-provision: the files are written but no virtual environment is
+# created, so the summary must not claim a venv or print activation hints for one.
+trace $CLI environments setup-local --serverless-version 4 --no-provision

acceptance/localenv/no-provision-text/test.toml

@@ -0,0 +1,24 @@
+EnvMatrix.DATABRICKS_BUNDLE_ENGINE = ["direct"]
+
+# A real --no-provision run creates pyproject.toml through the merge phase; the
+# assertion is the JSON output, so ignore the written file.
+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", "pandas<3"]
+'''
+
+[[Repls]]
+Old = 'uv uv \S+(?: \([^)]+\))?'
+New = 'uv [UV_VERSION]'