databricks-app-python

name: databricks-app-python description: "Builds Python-based Databricks applications using Dash, Streamlit, Gradio, Flask, FastAPI, or Reflex. Handles OAuth authorization (app and user auth), app resources, SQL warehouse and Lakebase connectivity, model serving integration, and deployment. Use when building Python web apps, dashboards, ML demos, or REST APIs for Databricks, or when the user mentions Streamlit, Dash, Gradio, Flask, FastAPI, Reflex, or Databricks app."

Databricks Python Application

Build Python-based Databricks applications. For full examples and recipes, see the Databricks Apps Cookbook.

Critical Rules (always follow)

• MUST confirm framework choice or use Framework Selection below
• MUST use SDK Config() for authentication (never hardcode tokens)
• MUST use app.yaml valueFrom for resources (never hardcode resource IDs)
• MUST use dash-bootstrap-components for Dash app layout and styling
• MUST use @st.cache_resource for Streamlit database connections
• MUST deploy Flask with Gunicorn, FastAPI with uvicorn (not dev servers)

Required Steps

Copy this checklist and verify each item:

- [ ] Framework selected
- [ ] Auth strategy decided: app auth, user auth, or both
- [ ] App resources identified (SQL warehouse, Lakebase, serving endpoint, etc.)
- [ ] Backend data strategy decided (SQL warehouse, Lakebase, or SDK)
- [ ] Deployment method: CLI or DABs

Framework Selection

Default: Recommend Streamlit for prototypes, Dash for production dashboards, FastAPI for APIs, Gradio for ML demos.

Quick Reference

Detailed Guides

Authorization: Use 1-authorization.md when configuring app or user authorization — covers service principal auth, on-behalf-of user tokens, OAuth scopes, per-framework code examples, and CRITICAL OBO gotchas (scopes not auto-applied, BIGINT workspace_id, per-router auth). (Keywords: OAuth, service principal, user auth, on-behalf-of, access token, scopes, OBO, system tables)

App resources: Use 2-app-resources.md when connecting your app to Databricks resources — covers SQL warehouses, Lakebase, model serving, secrets, volumes, and the valueFrom pattern. (Keywords: resources, valueFrom, SQL warehouse, model serving, secrets, volumes, connections)

Frameworks: See 3-frameworks.md for Databricks-specific patterns per framework — covers Dash, Streamlit, Gradio, Flask, FastAPI, and Reflex with auth integration, deployment commands, and Cookbook links. (Keywords: Dash, Streamlit, Gradio, Flask, FastAPI, Reflex, framework selection)

Deployment: Use 4-deployment.md when deploying your app — covers Databricks CLI, Asset Bundles (DABs), app.yaml configuration, and post-deployment verification. (Keywords: deploy, CLI, DABs, asset bundles, app.yaml, logs)

Lakebase: Use 5-lakebase.md when using Lakebase (PostgreSQL) as your app's data layer — covers auto-injected env vars, psycopg2/asyncpg patterns, and when to choose Lakebase vs SQL warehouse. (Keywords: Lakebase, PostgreSQL, psycopg2, asyncpg, transactional, PGHOST)

MCP tools: Use 6-mcp-approach.md for managing app lifecycle via MCP tools — covers creating, deploying, monitoring, and deleting apps programmatically. (Keywords: MCP, create app, deploy app, app logs)

Workflow

1. Determine the task type:

   New app from scratch? → Use Framework Selection, then read 3-frameworks.md Setting up authorization? → Read 1-authorization.md Connecting to data/resources? → Read 2-app-resources.md Using Lakebase (PostgreSQL)? → Read 5-lakebase.md Deploying to Databricks? → Read 4-deployment.md Using MCP tools? → Read 6-mcp-approach.md

2. Follow the instructions in the relevant guide

3. For full code examples, browse https://apps-cookbook.dev/

Core Architecture

All Python Databricks apps follow this pattern:

app-directory/
├── app.py                 # Main application (or framework-specific name)
├── models.py              # Pydantic data models
├── backend.py             # Data access layer
├── requirements.txt       # Additional Python dependencies
├── app.yaml               # Databricks Apps configuration
└── README.md

Backend Toggle Pattern

import os
from databricks.sdk.core import Config

USE_MOCK = os.getenv("USE_MOCK_BACKEND", "true").lower() == "true"

if USE_MOCK:
    from backend_mock import MockBackend as Backend
else:
    from backend_real import RealBackend as Backend

backend = Backend()

SQL Warehouse Connection (shared across all frameworks)

from databricks.sdk.core import Config
from databricks import sql

cfg = Config()  # Auto-detects credentials from environment
conn = sql.connect(
    server_hostname=cfg.host,
    http_path=f"/sql/1.0/warehouses/{os.getenv('DATABRICKS_WAREHOUSE_ID')}",
    credentials_provider=lambda: cfg.authenticate,
)

Pydantic Models

from pydantic import BaseModel, Field
from datetime import datetime
from enum import Enum

class Status(str, Enum):
    ACTIVE = "active"
    PENDING = "pending"

class EntityOut(BaseModel):
    id: str
    name: str
    status: Status
    created_at: datetime

class EntityIn(BaseModel):
    name: str = Field(..., min_length=1)
    status: Status = Status.PENDING

Automated Testing with MCP Servers

Use Chrome DevTools MCP for automated UI testing of deployed apps:

# Navigate to app (local or deployed)
mcp__chrome-devtools__puppeteer_navigate --url "http://localhost:8080"

# Take screenshot
mcp__chrome-devtools__puppeteer_screenshot

# Check for console errors
mcp__chrome-devtools__puppeteer_console_logs

# Test interactive elements
mcp__chrome-devtools__puppeteer_click --selector "button[data-testid='submit']"

# Verify data displayed
mcp__chrome-devtools__puppeteer_evaluate --script "document.querySelector('.data-loaded') !== null"

Test Checklist

• App loads without errors
• UI renders correctly (screenshot verification)
• No JavaScript/console errors
• Interactive elements work (buttons, forms)
• Data loads and displays properly
• API endpoints respond correctly

Testing Deployed Apps

# Get app URL
APP_URL=$(databricks apps get <app-name> -p <profile> | jq -r '.url')

# Navigate and test
mcp__chrome-devtools__puppeteer_navigate --url "$APP_URL"
mcp__chrome-devtools__puppeteer_screenshot --name "deployed-app"

# Check logs for errors
databricks apps logs <app-name> -p <profile> | tail -50

Common Issues

Platform Constraints

Official Documentation

• Databricks Apps Overview — main docs hub
• Apps Cookbook — ready-to-use code snippets (Streamlit, Dash, Reflex, FastAPI)
• Authorization — app auth and user auth
• Resources — SQL warehouse, Lakebase, serving, secrets
• app.yaml Reference — command and env config
• System Environment — pre-installed packages, runtime details

Related Skills

• databricks-app-apx - full-stack apps with FastAPI + React
• databricks-asset-bundles - deploying apps via DABs
• databricks-python-sdk - backend SDK integration
• lakebase-provisioned - adding persistent PostgreSQL state
• databricks-model-serving - serving ML models for app integration