databricks-sdk-patterns

name	databricks-sdk-patterns
description	Apply production-ready Databricks SDK patterns for Python and REST API. Use when implementing Databricks integrations, refactoring SDK usage, or establishing team coding standards for Databricks. Trigger with phrases like "databricks SDK patterns", "databricks best practices", "databricks code patterns", "idiomatic databricks".
allowed-tools	Read, Write, Edit
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
compatible-with	claude-code, codex, openclaw
tags	["saas","databricks","api","python"]

Databricks SDK Patterns

Overview

Production-ready patterns for the Databricks Python SDK (databricks-sdk). Covers singleton client initialization, typed error handling, cluster lifecycle management, type-safe job construction, and pagination. Uses real SDK exception classes and API shapes.

Prerequisites

• databricks-sdk>=0.20.0 installed
• Authentication configured (see databricks-install-auth)
• Python 3.10+

Instructions

Step 1: Singleton Client with Profile Support

Each WorkspaceClient holds an HTTP session and re-authenticates. Cache instances.

from databricks.sdk import WorkspaceClient, AccountClient
from functools import lru_cache

@lru_cache(maxsize=4)
def get_client(profile: str = "DEFAULT") -> WorkspaceClient:
    """Cached WorkspaceClient — one per profile."""
    return WorkspaceClient(profile=profile)

@lru_cache(maxsize=1)
def get_account_client() -> AccountClient:
    """Account-level client for multi-workspace operations."""
    return AccountClient(
        host="https://accounts.cloud.databricks.com",
        account_id="00000000-0000-0000-0000-000000000000",
    )

# Usage
w = get_client()
w_prod = get_client("production")

Step 2: Structured Error Handling

The SDK raises typed exceptions from databricks.sdk.errors. Distinguish transient (retryable) from permanent failures.

from dataclasses import dataclass
from typing  TypeVar, , , 
 databricks.sdk.errors  (
    NotFound,
    PermissionDenied,
    TooManyRequests,
    TemporarilyUnavailable,
    ResourceConflict,
    InvalidParameterValue,
    ResourceAlreadyExists,
)

T = TypeVar()


 ([T]):
    value: [T] = 
    error: [] = 
    retryable:  = 


     () -> :
         .error  

 () -> Result:
    
    :
         Result(value=func(*args, **kwargs))
     NotFound  e:
         Result(error=, retryable=)
     PermissionDenied  e:
         Result(error=, retryable=)
     InvalidParameterValue  e:
         Result(error=, retryable=)
     ResourceAlreadyExists  e:
         Result(error=, retryable=)
     ResourceConflict  e:
         Result(error=, retryable=)
     TooManyRequests  e:
         Result(error=, retryable=)
     TemporarilyUnavailable  e:
         Result(error=, retryable=)


result = safe_call(w.clusters.get, cluster_id=)
 result.ok:
    ()
 result.retryable:
    ()
:
    ()