Databricks SDK for Go

Go SDK for the Databricks platform. Auto-generated API clients from OpenAPI specs, with hand-written authentication, configuration, and transport infrastructure.

For scoped coding rules, skills, and prompt templates, see the .agent/ directory.

Rules (.agent/rules/)

• api-design.md — API design principles for the Databricks SDK.
• error-handling.md — Error handling conventions for the Databricks SDK.
• style-guide.md — Go code style and naming conventions for the Databricks SDK.
• testing.md — Testing standards and anti-patterns for the Databricks SDK.

Skills (.agent/skills/)

• write-pr-description — Write or improve a GitHub pull request description.

Prompts (.agent/prompts/)

• code-review.md — Review PR or code changes for backward compatibility, correctness, and style.

Development

Prerequisites: Go 1.25+ (see go.mod), goimports, staticcheck, gotestsum.

make build      # go build ./...
make test       # Unit tests with coverage
make fmt        # goimports + gofmt
make lint       # staticcheck ./...
make vendor     # Vendor dependencies
make coverage   # View HTML coverage report
make codegen    # Regenerate service/ from OpenAPI specs

CI runs make test across Go 1.25 and 1.26; lint and fmt run on Go 1.26. Code must compile on all CI versions — do not use stdlib APIs newer than Go 1.25 (the module's minimum version in go.mod) without a local shim.

Architecture

├── apierr/         # API error types and handling
├── client/         # High-level DatabricksClient (wraps workspace + account APIs)
├── config/         # Authentication and client configuration (core, hand-written)
├── credentials/    # Credential providers (OAuth, PAT, Azure, GCP, etc.)
├── experimental/   # Experimental features and generated mocks
├── httpclient/     # HTTP transport layer, request/response handling
├── internal/       # Internal utilities
├── listing/        # Iterator patterns for paginated API responses
├── logger/         # Logging infrastructure
├── marshal/        # JSON marshalling utilities
├── openapi/        # Code generator (reads OpenAPI specs, generates service/)
├── retries/        # Retry logic and policies
├── service/        # Auto-generated API service clients (DO NOT EDIT)
├── useragent/      # User-agent string construction
├── .codegen/       # Code generation templates (.tmpl files)
└── qa/             # Test helpers: HTTP fixtures, polling, locking

Generated Code — DO NOT EDIT

• service/ — API service clients, generated from OpenAPI specs. Every file starts with // Code generated from OpenAPI specs by Databricks SDK Generator. DO NOT EDIT.
• experimental/mocks/ — Mock implementations, generated by mockery. Every file starts with // Code generated by mockery. DO NOT EDIT.

To regenerate: make codegen (requires OpenAPI specs). After regenerating, run make fmt and make lint.

Hand-written code lives in: config/, credentials/, httpclient/, apierr/, listing/, retries/, marshal/, logger/, useragent/, client/, internal/, openapi/.

Common Mistakes

• Do NOT edit files in service/ or experimental/mocks/ — they are auto-generated and will be overwritten
• Do NOT use context.Background() in production code (only in tests)
• Do NOT add new files to service/ manually — update OpenAPI specs and run make codegen
• Do NOT add dependencies without checking license compatibility (Apache 2.0 required)
• Do NOT break backwards compatibility of exported APIs without discussion
• Do NOT use os.Exit() outside of main.go entry points

Where to Put New Code

1. New API service client? → Update OpenAPI spec, run make codegen
2. New auth method? → credentials/ (implement CredentialsProvider interface)
3. Auth config change? → config/
4. HTTP transport change? → httpclient/
5. New error type? → apierr/
6. New pagination pattern? → listing/
7. Retry logic change? → retries/
8. Code generation change? → openapi/ and .codegen/ templates
9. Experimental/unstable API? → experimental/ or config/experimental/

Pull Requests

PR template requires: Changes (linked issues + functionality) and Tests sections. All PRs must have the DCO sign-off (git commit -s). Run make fmt test lint before submitting.

Changelog

For changes that need a release note, add a uniquely named .nextchanges/<timestamp>.md fragment in the Universe source checkout, using the format in .nextchanges/README.md. Genkit consumes these fragments into CHANGELOG.md during release preparation. Pending fragments are not published to the public mirror. Changes that do not need a release note do not require a fragment.