databricks-setup-local

Databricks Setup-Local

最初に必ず実行： CLI、認証、プロファイルの選択には databricks-core を使用してください。デフォルトのプロファイルは決して使用しないでください。既存の環境では、databricks-execution-compute を使用してください。

ワークフロー

1. CLI と認証を確認する

CLI は v1.16.0 以上である必要があります。このリリースでは、--no-dbconnect と、このスキルが処理する E_PROVISION_CONFLICT エラーが追加されました。バージョンを決定論的に比較してください。決して目視で判断しないでください（1.9.0 は 1.16.0 より古く、文字列の辞書順比較では正しく判定できません）。最初にこのゲートを実行し、終了コードが 0 以外の場合は先へ進まないでください。

# Subshell so a failed gate reports non-zero without closing a persistent shell.
(
  # Read stdout only -- upgrade nags on stderr carry their own semver and would win the parse.
  if ! raw="$(databricks version 2>/dev/null)"; then
    echo "STOP: databricks CLI is missing or failed to run -- install or upgrade it via databricks-core first"
    exit 1
  fi
  have="$(printf '%s\n' "$raw" | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' | head -n1 | tr -d v)"
  [ -n "$have" ] || have="$(printf '%s\n' "$raw" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -n1)"
  if [ -z "$have" ]; then
    echo "STOP: could not read a version from 'databricks version' -- upgrade via databricks-core first"
    exit 1
  fi
  case "$raw" in
    *-dev*)
      echo "NOTE: dev build $have -- the floor cannot be checked; ask the user to confirm this build has setup-local"
      ;;
    *)
      if [ "$(printf '%s\n%s\n' "1.16.0" "$have" | sort -V | head -n1)" != "1.16.0" ]; then
        echo "STOP: databricks CLI $have is older than v1.16.0, the floor this skill requires -- older CLIs can run setup-local but not as documented here; upgrade via databricks-core first"
        exit 1
      fi
      ;;
  esac
)

ゲートに合格した後に限り、選択したプロファイルで認証してください。

databricks auth describe --profile <PROFILE>

最新の安定版 CLI を優先してください。オンラインでの検索は不要です。ゲートの終了コードが 0 以外の場合（v1.16.0 より古い、CLI がない、またはバージョンを読み取れない）、または setup-local がヘルプにない、unknown command が表示される、このスキルで渡すよう指示されたフラグが拒否される場合は、停止してください。NOTE: dev build と表示された場合は、必要な最低バージョンを検証できません。続行する前にユーザーに確認してください。アップグレードには承認を得たうえで databricks-core を使用し、検証してください。setup-local を手動で再作成してはいけません。

すべてのワークスペースコマンドで、選択したプロファイルを使用してください。承認なしに別のパッケージマネージャーへ切り替えないでください。

2. プロジェクトディレクトリを確認する

pyproject.toml、.venv、uv.lock を含む（または含む予定の）ルートディレクトリを確認してください。候補となるルートが複数ある場合は、ユーザーに確認してください。プレビューと適用では、このディレクトリを使用してください。このディレクトリは新規作成する環境または uv で管理される環境である必要がありますが、プレビュー時に書き込み可能である必要はありません。

3. ターゲットを 1 つ選択する

次の分岐から、必ず 1 つだけ選択してください。

• クラスター： --cluster-id <ID> または --cluster-name <NAME> を使用します。不明な場合は、選択したプロファイルでクラスター一覧を表示してユーザーに確認してください。例を参照してください。
• Serverless： --serverless-version <N> を使用します。バージョン一覧を表示するコマンドはありません。指定されていない場合は、ユーザーに確認してください。
• ジョブタスク： --job-task <JOB_ID>.<TASK_KEY> を使用します。タスクが不明な場合は、databricks jobs get <JOB_ID> --profile <PROFILE> --output json を実行し、タスクキーを提示してユーザーに確認してください。
• Bundle： databricks.yml があるプロジェクトです。databricks-dabs を使用して、ルートと選択したターゲットを確認してください。そのターゲットがサポート対象のクラシックまたは Serverless コンピュートに解決される場合に限り、コンピュートフラグを省略してください。それ以外の場合はユーザーに確認してください。名前付きターゲットの場合は --target <BUNDLE_TARGET> を追加してください。

コンピュートフラグを組み合わせてはいけません。どの分岐にも該当しない場合は、ユーザーに確認してください。

4. プレビュー

まずドライランを実行します。ファイルの書き込みやインストールは行われません。

databricks environments setup-local --profile <PROFILE> <TARGET_ARGS> --dry-run --output json

Bundle の場合、<TARGET_ARGS> は空、または --target <BUNDLE_TARGET> です。通常モードをデフォルトとして使用してください。ユーザーがこのコマンドによる databricks-connect の管理を明示的に望まない場合に限り、--no-dbconnect を使用してください。この場合も、結果の mode には constraints-only と報告されます。JSON 出力と例を参照してください。

5. 承認を得て適用する

適用する前に、ディレクトリが書き込み可能であることを確認し、uv --version を実行してください。uv のインストール前にユーザーに確認してください。DATABRICKS_LOCALENV_AUTO_INSTALL_UV=1 を黙って設定したり、リモートインストーラーを実行したりしてはいけません。

適用前に、ターゲット、バージョン、警告、plan.diff、ディレクトリを提示してください。適用によって、次の操作が行われる可能性があることを説明してください。

• pyproject.toml のバックアップと書き換え
• Python と依存関係のインストール
• .venv と uv.lock の更新

Bundle 内で --serverless-version N を使用する場合は、以下で説明する適用後のジョブ YAML 同期についても開示し、両方の変更に対する承認を得てください。

ユーザーがプロビジョニングを依頼した場合、または指定されたディレクトリに対するその計画を承認した場合に限り、適用してください。ディレクトリ、プロファイル、ターゲット、モードを維持してください。

プレビュー後にディレクトリ、プロファイル、ターゲット、モード、またはプロジェクトファイルが変更された場合は、--dry-run を再実行し、新しい計画を提示して、改めて承認を得てください。解決された Python、databricks-connect、管理対象の制約を正式なものとして扱い、推測したバージョンに置き換えてはいけません。ユーザー所有の依存関係との競合は、別途承認を得て解消してください。

6. 結果を処理する

• ok: true：バンドル内で --serverless-version N が指定されている場合、YAML ソース内の既存のすべてのジョブの environments[].spec.environment_version を "N" に更新してから、バンドルを検証します。該当するものがない場合はその旨を報告し、作り出さないでください。クラスターおよびジョブタスクのターゲットでは、この処理をスキップしてください。ターゲット、バージョン、警告、venvPath を報告してください。uv run <cmd> を優先するか、venvPath からプラットフォーム固有のインタープリターを導き出してください。
• ok: false：トラブルシューティングを使用してください。ファイルを変更する診断実行の前、および外部の課題を起票する前に確認してください。
• JSON がない場合：パイプライン開始前の CLI、認証、ディレクトリ、またはキャッシュのエラーがないか、標準エラー出力を確認してください。