Skip to content

kernel: distribute the kernel via per-platform bindings modules (go get, no build step, all 5 platforms) #440

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
msrathore-db merged 2 commits into from
Aug 28, 2026
+1,080 −83
Merged

kernel: distribute the kernel via per-platform bindings modules (go get, no build step, all 5 platforms) #440

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
321d391
kernel: distribute the backend via prebuilt per-platform bindings mod…
msrathore-db Aug 24, 2026
c53db7b
Merge remote-tracking branch 'origin/main' into kernel-nested-modules
msrathore-db Aug 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,17 @@ _tmp*
__debug_bin
.DS_Store

# Kernel (SEA) backend build artifacts — produced by `make kernel-lib`, never committed.
# Kernel (SEA) backend build artifacts.
#
# The distribution model (see README): this repo commits only the small,
# platform-independent C header (internal/backend/kernel/include/). The prebuilt
# per-platform archives live in the SEPARATE github.com/databricks/databricks-sql-kernel-bindings
# repo (one nested Go module per platform), which this driver requires in go.mod
# — so a kernel opt-in `go get` build needs no build step. The committed header
# is intentionally NOT ignored.
#
# The paths below remain ignored: they are local scratch dirs used only by
# `make kernel-lib` for source builds against a kernel checkout (dev/CI), and are
# never committed — the shipped archives come from the bindings modules.
/build/kernel-src/
/internal/backend/kernel/lib/
/internal/backend/kernel/include/
1 change: 1 addition & 0 deletions .golangci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ linters:
allow:
- $gostd
- github.com/databricks/databricks-sql-go
- github.com/databricks/databricks-sql-kernel-bindings
- github.com/apache/arrow/go/v12
- github.com/apache/thrift/lib/go/thrift
- github.com/coreos/go-oidc/v3/oidc
Expand Down
25 changes: 16 additions & 9 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,8 +102,21 @@ KERNEL_INC_DIR = internal/backend/kernel/include
KERNEL_GO = CGO_ENABLED=1 go
KERNEL_TAGS = -tags databricks_kernel

# SHIPPED PATH (consumers): the kernel archives are NOT built here. They come from
# the external per-platform modules in github.com/databricks/databricks-sql-kernel-bindings
# that this repo requires in go.mod; a kernel opt-in `go get` build downloads only
# the target platform's archive (no Rust, no build step). The targets below are
# for LOCAL DEVELOPMENT against a kernel source checkout only.
#
# Local-dev flow: `make kernel-lib` builds the host-platform archive from the
# pinned KERNEL_REV into $(KERNEL_LIB_DIR) (a .gitignore'd scratch dir). To have a
# `-tags databricks_kernel` build actually LINK that freshly built archive instead
# of the published bindings module, point the matching lib/<platform> module at a
# local bindings checkout via a go.work whose lib/<platform>/ holds the built .a
#. TODO(dev-loop): wire this go.work step into the targets
# so `make test-kernel` links the local build end-to-end without manual setup.
.PHONY: kernel-lib
kernel-lib: ## Build the pinned kernel static lib + header into the cgo link dir (source build).
kernel-lib: ## Build the pinned kernel static lib + header locally (source build, dev only).
KERNEL_REPO="$(KERNEL_REPO)" KERNEL_REV="$(KERNEL_REV)" KERNEL_SRC="$(KERNEL_SRC)" \
KERNEL_LIB_DIR="$(KERNEL_LIB_DIR)" KERNEL_INC_DIR="$(KERNEL_INC_DIR)" \
KERNEL_GOOS="$(KERNEL_GOOS)" KERNEL_GOARCH="$(KERNEL_GOARCH)" \
Expand All @@ -112,15 +125,9 @@ kernel-lib: ## Build the pinned kernel static lib + header into the cgo link di
./build/kernel-lib.sh

.PHONY: build-kernel
build-kernel: kernel-lib ## Build the driver with the kernel backend linked.
build-kernel: ## Build the driver with the kernel backend linked (against the bindings modules).
$(KERNEL_GO) build $(KERNEL_TAGS) ./...

.PHONY: test-kernel
test-kernel: kernel-lib ## Run the kernel-tagged unit tests (no warehouse needed).
test-kernel: ## Run the kernel-tagged unit tests (no warehouse needed; links the bindings modules).
$(KERNEL_GO) test $(KERNEL_TAGS) ./...

.PHONY: kernel-lib-download
kernel-lib-download: ## Prod mode (download prebuilt .a): blocked until the kernel publishes release artifacts.
@echo "kernel-lib-download: blocked — the kernel does not yet publish per-platform .a release artifacts."
@echo "Use 'make kernel-lib' (source build) meanwhile. See the distribution design doc."
@false
37 changes: 37 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ standard `database/sql` interface.
## Contents

- [Quick start](#quick-start)
- [Cloning the repository](#cloning-the-repository)
- [Choosing a backend (Thrift vs SEA/kernel)](#choosing-a-backend-thrift-vs-seakernel)
- [Building](#building)
- [Connecting](#connecting)
Expand Down Expand Up @@ -46,6 +47,42 @@ defer rows.Close()
See [`doc.go`](./doc.go) for full package documentation or the Databricks documentation
for the [SQL Driver for Go](https://docs.databricks.com/dev-tools/go-sql-driver.html).

> **Using the driver in your own project?** You never clone this repository — you
> add it with `go get github.com/databricks/databricks-sql-go` and `go build`.
> `go get` fetches per-version module archives, not git history, and for a
> default Thrift build it pulls **no** kernel binaries at all. The guidance below
> is only for people who `git clone` this repo directly (contributors / CI).

## Cloning the repository

This driver repo itself is **small**: for the SEA/kernel backend it commits only
the platform-independent C header
(`internal/backend/kernel/include/databricks_kernel.h`). The **prebuilt kernel
binaries** (per-platform `libdatabricks_sql_kernel.a`, ~60–95 MB each) live in a
**separate** repository,
[`databricks-sql-kernel-bindings`](https://github.com/databricks/databricks-sql-kernel-bindings),
one nested Go module per platform. This driver `require`s those modules, so the
SEA/kernel backend works straight from `go get` with **no build step** (see
[SEA/kernel](#seakernel--cgo--a-linked-rust-static-library)). A consumer's
`go get` pulls only the **target platform's** archive at the driver-pinned
version — never all platforms.

A plain `git clone` of *this* repo is therefore cheap. The partial/sparse-clone
guidance matters instead for the **bindings** repo, whose committed archives
(which git cannot delta-compress) accumulate across releases:

```bash
# Cheap history + only your platform's archive materialized:
git clone --filter=blob:none --sparse https://github.com/databricks/databricks-sql-kernel-bindings
cd databricks-sql-kernel-bindings
git sparse-checkout set --no-cone '/*' '!/lib' \
'lib/darwin_arm64' # keep only your platform
```

`--filter=blob:none` fetches commits and trees immediately and pulls file blobs
lazily, keeping `.git` small; GitHub serves it by default. CI checkouts of the
bindings repo use `--filter=blob:none` for the same reason.

## Choosing a backend (Thrift vs SEA/kernel)

The driver has **two execution backends**, selected once per connection:
Expand Down
21 changes: 21 additions & 0 deletions go.mod
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,3 +53,24 @@ require (
github.com/rs/zerolog v1.28.0
golang.org/x/sys v0.47.0 // indirect
)

// Per-platform kernel library modules, distributed by the separate
// github.com/databricks/databricks-sql-kernel-bindings repo (one nested Go
// module per platform, lib/<os>_<arch>). Each carries that platform's prebuilt
// kernel static archive + its cgo link directive; a kernel build downloads only
// the archive for the platform it targets (build-tag gated), and a pure-Go
// Thrift build downloads none of them.
//
// The versions are pinned in lockstep with the driver release. A consumer's
// `go get github.com/databricks/databricks-sql-go@vX.Y.Z` transitively pins the
// matching per-platform kernel archive; upgrading the driver moves the kernel
// version. See the databricks-sql-kernel-bindings repo README.
require (

@peco-review-bot peco-review-bot Bot Aug 27, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 High — Adding these five requires to the driver's go.mod while the databricks-sql-kernel-bindings repo is still private will break the default Thrift go get/go build for every external consumer — contradicting the PR's core claim that "the default Thrift CUJ is completely unchanged."

Go's (pruned) module-graph resolution needs the go.mod file of every module listed in a dependency's require block, even for modules whose packages are never imported by the current build. A downstream go build that imports databricks-sql-go therefore has to fetch the go.mod of all five lib/<platform> modules from the proxy/direct git to compute the build list. If that repo is private (410/auth failure from the public proxy), resolution fails before any build-tag gating applies — the databricks_kernel tag only controls whether the zip (archive) is downloaded, not whether the go.mod is read for graph construction. The go.sum hashes present here don't help: they verify content, they don't cache it.

docs/RELEASING.md explicitly acknowledges the repo is private and that public go get "requires it to be made public." Merging this require block before that happens makes the public module un-buildable for OSS users. Recommend gating this merge on the bindings repo being public (or otherwise confirming the module-graph impact on a pure Thrift consumer build from a clean module cache with no GOPRIVATE).

@peco-review-bot peco-review-bot Bot Aug 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium — These 7 bindings modules are added as direct requirements, but the only packages that import them are gated behind //go:build cgo && databricks_kernel (the archives, ~60–95 MB each, are only linked under the kernel tag). That linking gate works. However, go build/go get must resolve the full module graph, which means every consumer — including pure-Thrift users who set no build tags and link none of these archives — now needs the go.mod of all 7 databricks-sql-kernel-bindings/lib/* modules to be resolvable at the pinned versions.

Consequences worth confirming before merge:

  • The PR description says a default Thrift build "fetches nothing kernel-related." That's true for the multi-MB archives, but not for module-graph resolution: the 7 bindings go.mod files must be fetchable, and their go.sum hashes verified, or the build fails. Worth softening the docs claim to "fetches no kernel binaries."
  • If the bindings repo is private (or a consumer's GOPROXY/GONOSUMDB/GOPRIVATE can't reach it), or if any pinned tag is later deleted/retagged, then Thrift-only consumers who never opted into the kernel will fail to build. That's a much wider blast radius than the kernel opt-in path.

If the bindings repo is public and its tags are immutable, this is acceptable coupling — but please verify that's the intent, since it makes the default CUJ depend on kernel-artifact availability.

github.com/databricks/databricks-sql-kernel-bindings/lib/darwin_amd64 v0.2.3

@peco-review-bot peco-review-bot Bot Aug 27, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 High — This adds direct requires on github.com/databricks/databricks-sql-kernel-bindings/lib/*, but docs/RELEASING.md states that repo is currently private. Go must read the go.mod of every module in the require block to compute the build list — including for a pure-Go, Thrift-only go build/go get (the archive zips are skipped for Thrift builds, but the go.mod files are not). So an external consumer without GOPRIVATE + git auth will hit a module-resolution failure (could not read Username for https://github.com) on a plain go get github.com/databricks/databricks-sql-go — which contradicts the PR's headline claim that the default Thrift CUJ is unchanged.

This coupling of the public driver to a private dependency should be resolved (bindings repo made public, or the require gated) before tagging a release, otherwise the default install path breaks for everyone outside the Databricks network. At minimum, confirm the bindings repo will be public at the driver tag that carries this go.mod.

@peco-review-bot peco-review-bot Bot Aug 27, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Low — Version mismatch between the PR narrative and the pinned versions: the PR description (and the vX.Y.Z examples in docs/RELEASING.md) repeatedly reference bindings v0.1.0, but go.mod pins v0.2.3 for all five modules. Not a build bug, but worth reconciling so reviewers can confirm the pinned archives correspond to the intended kernel revision recorded in KERNEL_REV.

github.com/databricks/databricks-sql-kernel-bindings/lib/darwin_arm64 v0.2.3
github.com/databricks/databricks-sql-kernel-bindings/lib/linux_amd64 v0.2.3

@peco-review-bot peco-review-bot Bot Aug 27, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Low — All seven databricks-sql-kernel-bindings/lib/* modules are referenced only by blank imports guarded behind the custom databricks_kernel build tag (cgo_*.go). go mod tidy run without -tags databricks_kernel (the default, and what most contributors/CI invoke) does not enable custom build tags, so it won't see these imports and will drop all seven require lines from this block. Because the default Thrift build never imports them, that removal passes the default build/CI cleanly — only a later -tags databricks_kernel build breaks, with a confusing "missing go.sum entry / module not found" error far from the edit that caused it.

Worth guarding against: either document that go mod tidy must be run with -tags databricks_kernel (and wire that into the Makefile / CI), or keep these pinned via a mechanism tidy preserves. Otherwise the pins here are fragile against a routine go mod tidy.

github.com/databricks/databricks-sql-kernel-bindings/lib/linux_arm v0.2.3
github.com/databricks/databricks-sql-kernel-bindings/lib/linux_arm64 v0.2.3

@peco-review-bot peco-review-bot Bot Aug 27, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 High — The require block pins 7 bindings modules — including .../lib/linux_arm and .../lib/windows_arm64 — but every doc surface in this same PR describes only 5 platforms:

  • PR title/description: "all 5 platforms", "Supports 5 platforms: linux amd64/arm64, darwin arm64/amd64, windows amd64".
  • docs/RELEASING.md "Publishing: path-prefixed tags" enumerates exactly 5 git tag lib/<platform>/vX.Y.Z lines (no linux_arm, no windows_arm64), and step 2 builds/trivy-scans exactly those 5.
  • README.md and the go.mod comment likewise say 5.

Two concrete problems:

  1. Future releases will fail to resolve. RELEASING.md step 4 tags only 5 platforms, but go.mod requires 7. On the next version bump (steps 5–6, go mod tidy), the linux_arm / windows_arm64 modules won't have a matching tag at the new version and resolution will break — unless someone remembers to tag two platforms the runbook never mentions.

  2. Provenance gap. The PR states the v0.2.3 archives were CI-built + trivy-scanned for the 5 listed platforms only. linux_arm and windows_arm64 are required here but were not among the verified/scanned set per the description, and were not runtime-verified.

Either add linux_arm and windows_arm64 to RELEASING.md (publish tags, build/scan steps), README, and the PR's verified-platform set — or drop them from go.mod / the cgo shims / cgo_unsupported.go to match the documented 5.

github.com/databricks/databricks-sql-kernel-bindings/lib/windows_amd64 v0.2.3
github.com/databricks/databricks-sql-kernel-bindings/lib/windows_arm64 v0.2.3
)
14 changes: 14 additions & 0 deletions go.sum
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,20 @@ github.com/coreos/go-oidc/v3 v3.5.0 h1:VxKtbccHZxs8juq7RdJntSqtXFtde9YpNpGn0yqgE
github.com/coreos/go-oidc/v3 v3.5.0/go.mod h1:ecXRtV4romGPeO6ieExAsUK9cb/3fp9hXNz1tlv8PIM=
github.com/coreos/go-systemd/v22 v22.3.3-0.20220203105225-a9a7ef127534/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
github.com/databricks/databricks-sql-kernel-bindings/lib/darwin_amd64 v0.2.3 h1:4rX55RzQ6I0eHquGxBfwZfSl8nV1LWGLFWdN9N9QStw=
github.com/databricks/databricks-sql-kernel-bindings/lib/darwin_amd64 v0.2.3/go.mod h1:ceyJVgJAbNmkwc/2YMUNGuw2gd8nHZwZhP2xpN84VBg=
github.com/databricks/databricks-sql-kernel-bindings/lib/darwin_arm64 v0.2.3 h1:fSMebxE6zXLu1Be+BA1TDzPhD5LerPHn38Oyx5WnasY=
github.com/databricks/databricks-sql-kernel-bindings/lib/darwin_arm64 v0.2.3/go.mod h1:Cr0N6/u4qDUvdbtqm4sVflN4ZXO8qdDcxEBhF5WB9PI=
github.com/databricks/databricks-sql-kernel-bindings/lib/linux_amd64 v0.2.3 h1:ciT+1xFmM47I4C435WVRXi2NIebMsTGsbv7JMMdXm14=
github.com/databricks/databricks-sql-kernel-bindings/lib/linux_amd64 v0.2.3/go.mod h1:KqeZQ/C/GoKAqoGL97/KT3BwLoqsxgSl3qJjje1F7TU=
github.com/databricks/databricks-sql-kernel-bindings/lib/linux_arm v0.2.3 h1:ZsAhogGOcuEilmXug3YNv3CH9I3WaSziR4WBNk3keqs=
github.com/databricks/databricks-sql-kernel-bindings/lib/linux_arm v0.2.3/go.mod h1:5/HsocwYCRUmO4sZKnLTBb/W+ItCdp3Z8lfssNdfqhM=
github.com/databricks/databricks-sql-kernel-bindings/lib/linux_arm64 v0.2.3 h1:vZ5Z6ql1SvkVBPBiN5ikOafIa83wOsTctJMtWHID78w=
github.com/databricks/databricks-sql-kernel-bindings/lib/linux_arm64 v0.2.3/go.mod h1:/1vEJKUPnrWx566kI/Ifl00GrhSyp798Ztl6rjtymCI=
github.com/databricks/databricks-sql-kernel-bindings/lib/windows_amd64 v0.2.3 h1:bhiBp77j1CaNfnT+8gBJlttP8/26ue7vsjZYbgyyZls=
github.com/databricks/databricks-sql-kernel-bindings/lib/windows_amd64 v0.2.3/go.mod h1:OaUVov84uK1IJz1gNk5TIoae0rj0vx+4N1qqRT88MdU=
github.com/databricks/databricks-sql-kernel-bindings/lib/windows_arm64 v0.2.3 h1:w/G2CNc+U2gd6zr/yn0rpyaSalXL9m2z76/JWWAGESA=
github.com/databricks/databricks-sql-kernel-bindings/lib/windows_arm64 v0.2.3/go.mod h1:Z8JD951Nk66P1J8hL6YhkyMp1YAnrRzxE2JMTYRblxc=
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
Expand Down
28 changes: 15 additions & 13 deletions internal/backend/kernel/cgo.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,19 +11,21 @@
// the error mapping to the driver's error surface, and the gated step logger.
// The backend, operation, and rows layers live in sibling files.
//
// Link contract (${SRCDIR}-relative, machine-independent). The header is
// included from ${SRCDIR}/include and the static lib is linked from
// ${SRCDIR}/lib/<os>_<arch>; the per-platform link flags live in the
// cgo_<os>.go files beside this one. Both directories are produced by the
// build step (`make kernel-lib`), which checks out the kernel at the commit
// pinned in the repo-root KERNEL_REV file and `cargo build`s a static lib —
// so the kernel revision is a reviewable pin, never baked into a #cgo line
// (those expand only ${SRCDIR} and cannot run git or read env). The dirs are
// .gitignore'd; nothing kernel-built is committed. For local development
// against an existing checkout, `make kernel-lib KERNEL_LOCAL_A=<path/to>.a
// KERNEL_LOCAL_HEADER=<path/to>databricks_kernel.h` copies those in instead of
// building. The eventual release path downloads a published .a at the pinned
// rev rather than building it (see the driver's distribution design).
// Link contract. This file owns the compile side: the C header is committed at
// ${SRCDIR}/include/databricks_kernel.h and pulled in via the #cgo CFLAGS below.
// The link side lives OUT of this repo: each cgo_<os>[_<arch>].go beside this
// file blank-imports the matching per-platform module from the separate
// github.com/databricks/databricks-sql-kernel-bindings repo, and cgo collects
// THAT module's `#cgo LDFLAGS` at final link time to pull in the prebuilt
// libdatabricks_sql_kernel.a. So a kernel opt-in `go get` build downloads only
// the archive for the platform it targets (build-tag gated) — no Rust toolchain
// and no build step. The committed header and the prebuilt archives are produced
// from the same pinned kernel revision (repo-root KERNEL_REV; the bindings repo
// records the same rev), which is the reviewable pin — never baked into a #cgo
// line. For local development against a kernel checkout, `make kernel-lib` builds
// the archive from source into the .gitignore'd internal/backend/kernel/lib/
// scratch dir (selected via a go.work / replace pointing at that path); the
// committed bindings modules are what ship.
package kernel

/*
Expand Down
23 changes: 7 additions & 16 deletions internal/backend/kernel/cgo_darwin.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,10 @@

package kernel

// Link flags for darwin/arm64. NOTE: this platform is not yet exercised in CI
// (M0 is linux/amd64); the flags below are the intended shape but must be
// validated on a mac before darwin is enabled.
//
// Two darwin-specific differences from linux:
// - Apple's ld64 does NOT accept the GNU `-l:<file>.a` extension, so the
// archive is passed as a positional input by absolute ${SRCDIR} path
// instead. Since only the .a is placed under lib/darwin_arm64 (see
// kernel-lib.sh), there is no .so to accidentally prefer.
// - -lc++ (not -lstdc++) is the macOS C++ runtime; @loader_path keeps any
// dynamic reference resolvable relative to the built binary.

/*
#cgo LDFLAGS: ${SRCDIR}/lib/darwin_arm64/libdatabricks_sql_kernel.a -lc++ -lm -Wl,-rpath,@loader_path
*/
import "C"
// darwin/arm64 link wiring. The kernel static archive and its `#cgo LDFLAGS`
// live in the external per-platform module github.com/databricks/databricks-sql-kernel-bindings/lib/darwin_arm64 (the
// databricks-sql-kernel-bindings repo). This file blank-imports it for the link
// side-effect: cgo collects that module's `#cgo LDFLAGS` at final link time,
// pulling libdatabricks_sql_kernel.a into the binary. Same build constraint as
// that module's prebuilt.go so the two are always selected together.
import _ "github.com/databricks/databricks-sql-kernel-bindings/lib/darwin_arm64"
9 changes: 9 additions & 0 deletions internal/backend/kernel/cgo_darwin_amd64.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
//go:build cgo && databricks_kernel && darwin && amd64

package kernel

// darwin/amd64 link wiring: blank-import the external per-platform module
// github.com/databricks/databricks-sql-kernel-bindings/lib/darwin_amd64 (databricks-sql-kernel-bindings) so cgo collects its
// `#cgo LDFLAGS` at link time and pulls libdatabricks_sql_kernel.a into the
// binary. Same build constraint as that module's prebuilt.go.
import _ "github.com/databricks/databricks-sql-kernel-bindings/lib/darwin_amd64"
18 changes: 5 additions & 13 deletions internal/backend/kernel/cgo_linux.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,8 @@

package kernel

// Link flags for linux/amd64. The static archive is forced with the
// -l:<file>.a form (a GNU-ld extension) so the linker never prefers a
// same-named .so — the kernel's cargo build emits both a .a and a .so into the
// same dir, and a bare -ldatabricks_sql_kernel would pick the .so and bake in
// an rpath. -lstdc++/-lm/-ldl are the kernel's transitive system deps.
//
// The path is ${SRCDIR}-relative; `make kernel-lib` drops the archive at
// ${SRCDIR}/lib/linux_amd64/libdatabricks_sql_kernel.a.

/*
#cgo LDFLAGS: -L${SRCDIR}/lib/linux_amd64 -l:libdatabricks_sql_kernel.a -lstdc++ -lm -ldl
*/
import "C"
// linux/amd64 link wiring: blank-import the external per-platform module
// github.com/databricks/databricks-sql-kernel-bindings/lib/linux_amd64 (databricks-sql-kernel-bindings) so cgo collects its
// `#cgo LDFLAGS` at link time and pulls libdatabricks_sql_kernel.a into the
// binary. Same build constraint as that module's prebuilt.go.
import _ "github.com/databricks/databricks-sql-kernel-bindings/lib/linux_amd64"

@peco-review-bot peco-review-bot Bot Aug 27, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Low — The new blank-imports of github.com/databricks/databricks-sql-kernel-bindings/lib/* (here and in the other four cgo_<os>[_<arch>].go shims) are third-party imports that are not in the depguard allowlist in .golangci.yml. The default make lint won't catch this because golangci-lint runs without -tags databricks_kernel, so these files aren't analyzed — but any kernel-tagged lint (golangci-lint run --build-tags databricks_kernel) will fail with a depguard denial. Per repo convention, a new third-party import must be added to the allowlist. Add github.com/databricks/databricks-sql-kernel-bindings/lib/* (or the five explicit module paths) to the depguard.rules.main.allow list.

9 changes: 9 additions & 0 deletions internal/backend/kernel/cgo_linux_arm.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
//go:build cgo && databricks_kernel && linux && arm

@peco-review-bot peco-review-bot Bot Aug 27, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium — This new shim (and its sibling cgo_windows_arm64.go) enables the kernel backend on linux/arm (32-bit armv7) and windows/arm64 — platforms outside the 5 the PR says were built and runtime-verified. cgo_unsupported.go's exclusion list and const name were also updated to treat all 7 as supported.

Enabling a -tags databricks_kernel build on these targets asserts a working, linkable archive exists at bindings v0.2.3. If the bindings repo does not carry verified archives for linux_arm/windows_arm64 at that tag, a consumer building on those targets gets an opaque link failure (or links an unscanned archive) rather than the legible compile-time "unsupported target" error cgo_unsupported.go is designed to give. Confirm these two archives are actually published and verified before advertising them as supported; otherwise keep them in the cgo_unsupported.go exclusion so the boundary matches what's been validated. 32-bit armv7 in particular is an unusual target for a ~60–95 MB static archive and worth double-checking is intended.


package kernel

// linux/arm (armv7) link wiring: blank-import the external per-platform module
// github.com/databricks/databricks-sql-kernel-bindings/lib/linux_arm (databricks-sql-kernel-bindings) so cgo collects its
// `#cgo LDFLAGS` at link time and pulls libdatabricks_sql_kernel.a into the
// binary. Same build constraint as that module's prebuilt.go.
import _ "github.com/databricks/databricks-sql-kernel-bindings/lib/linux_arm"
9 changes: 9 additions & 0 deletions internal/backend/kernel/cgo_linux_arm64.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
//go:build cgo && databricks_kernel && linux && arm64

package kernel

// linux/arm64 link wiring: blank-import the external per-platform module
// github.com/databricks/databricks-sql-kernel-bindings/lib/linux_arm64 (databricks-sql-kernel-bindings) so cgo collects its
// `#cgo LDFLAGS` at link time and pulls libdatabricks_sql_kernel.a into the
// binary. Same build constraint as that module's prebuilt.go.
import _ "github.com/databricks/databricks-sql-kernel-bindings/lib/linux_arm64"
27 changes: 13 additions & 14 deletions internal/backend/kernel/cgo_unsupported.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,18 @@
//go:build cgo && databricks_kernel && !(linux && amd64) && !(darwin && arm64) && !(windows && amd64)
//go:build cgo && databricks_kernel && !(linux && amd64) && !(linux && arm64) && !(linux && arm) && !(darwin && arm64) && !(darwin && amd64) && !(windows && amd64) && !(windows && arm64)

package kernel

// This file is compiled only on GOOS/GOARCH combinations the kernel backend does
// not support. Per-platform link flags (cgo_<os>.go) exist only for linux/amd64,
// darwin/arm64, and windows/amd64; on any other target there is no static archive
// to link, so cgo.go's C ABI calls would otherwise fail at the LINK step with an
// opaque "undefined reference to kernel_*". The Makefile's host==target guard
// does not catch this — it happily source-builds a host .a on e.g. linux/arm64
// (Graviton) or an Intel Mac, only for the link to fall over with no matching
// LDFLAGS file. Referencing an undefined identifier here fails earlier, at
// COMPILE time, with a message that names the supported targets — a legible build
// error instead of a linker dump.
// not support. Per-platform link shims (cgo_<os>[_<arch>].go) exist for
// linux/amd64, linux/arm64, linux/arm, darwin/arm64, darwin/amd64, windows/amd64,
// and windows/arm64; on any other target there is no static archive to link, so
// cgo.go's C ABI calls would otherwise fail at the LINK step with an opaque
// "undefined reference to kernel_*". Referencing an undefined identifier here
// fails earlier, at COMPILE time, with a message that names the supported
// targets — a legible build error instead of a linker dump.
//
// Broader OS/arch coverage is tracked in the distribution design (native per-OS
// runners or a staged prebuilt .a); until then this guard makes the supported
// boundary explicit rather than latent.
const _ = kernel_backend_supports_only_linux_amd64_darwin_arm64_and_windows_amd64
// The supported set maps 1:1 to the per-platform modules published by
// github.com/databricks/databricks-sql-kernel-bindings. Adding a platform =
// publish its bindings module + add a cgo_<os>_<arch>.go shim + drop it from this
// exclusion list.
const _ = kernel_backend_supports_only_linux_amd64_linux_arm64_linux_arm_darwin_arm64_darwin_amd64_windows_amd64_and_windows_arm64
21 changes: 5 additions & 16 deletions internal/backend/kernel/cgo_windows.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,8 @@

package kernel

// Link flags for windows/amd64. NOTE: this platform is not yet exercised in CI
// (M0 is linux/amd64); the flags below are the intended shape but must be
// validated on windows before it is enabled.
//
// cgo on windows uses the mingw/gcc toolchain, which links GNU archives (.a) —
// NOT the MSVC .lib that `cargo build --target x86_64-pc-windows-msvc` emits.
// So the kernel must be built for the windows-gnu target
// (`--target x86_64-pc-windows-gnu`) to produce a mingw-compatible .a; that
// target selection is the build step's responsibility. -lws2_32/-lwsock32 are
// the kernel's Winsock deps and -lrstrtmgr is Restart Manager (pulled in by the
// Rust std/dep graph on windows).

/*
#cgo LDFLAGS: -L${SRCDIR}/lib/windows_amd64 -l:libdatabricks_sql_kernel.a -lws2_32 -lwsock32 -lrstrtmgr
*/
import "C"
// windows/amd64 link wiring: blank-import the external per-platform module
// github.com/databricks/databricks-sql-kernel-bindings/lib/windows_amd64 (databricks-sql-kernel-bindings) so cgo collects its
// `#cgo LDFLAGS` at link time and pulls libdatabricks_sql_kernel.a into the
// binary. Same build constraint as that module's prebuilt.go.
import _ "github.com/databricks/databricks-sql-kernel-bindings/lib/windows_amd64"
Loading
Loading