From 7a73baf4fa557cfc8d490eed988a9b22b9e302d3 Mon Sep 17 00:00:00 2001 From: Kevin Minehart Tenorio <5140827+kminehart@users.noreply.github.com> Date: Thu, 5 Mar 2026 12:07:12 +0100 Subject: [PATCH] =?UTF-8?q?Update=20docs=20to=20be=20clearer=20about=20sql?= =?UTF-8?q?ite=20recommendation.=20Fix=20Makefile=20n=E2=80=A6=20(#119591)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Update docs to be clearer about sqlite recommendation. Fix Makefile not forwarding LDDFLAGS and be more explicit about CGO_ENABLED * prettier --- Makefile | 5 +++-- contribute/developer-guide.md | 18 +++++++++++++++++- .../setup-grafana/configure-grafana/_index.md | 4 ++++ .../setup-grafana/installation/_index.md | 4 ++-- 4 files changed, 26 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index 82cddd58c50..06d9a8af788 100644 --- a/Makefile +++ b/Makefile @@ -23,7 +23,8 @@ BUILD_STAMP := $(shell echo $${SOURCE_DATE_EPOCH:-$$(date +%s 2>/dev/null)}) GO_LDFLAGS = -X main.version=$(BUILD_VERSION) \ -X main.commit=$(BUILD_COMMIT) \ -X main.buildBranch=$(BUILD_BRANCH) \ - -X main.buildstamp=$(BUILD_STAMP) + -X main.buildstamp=$(BUILD_STAMP) \ + $(if $(LDFLAGS),-extldflags \"$(LDFLAGS)\") GO_TEST_FLAGS += $(if $(GO_BUILD_TAGS),-tags=$(GO_BUILD_TAGS)) GIT_BASE = remotes/origin/main @@ -285,7 +286,7 @@ update-workspace: gen-go .PHONY: build-go build-go: gen-themes ## Build all Go binaries (grafana, grafana-server, grafana-cli). @echo "build go binaries" - $(if $(GO_BUILD_OS),GOOS=$(GO_BUILD_OS)) $(if $(GO_BUILD_ARCH),GOARCH=$(GO_BUILD_ARCH)) $(GO) build -buildvcs=false -trimpath $(GO_RACE_FLAG) $(if $(GO_BUILD_TAGS),-tags $(GO_BUILD_TAGS)) $(if $(GO_BUILD_GCFLAGS),-gcflags "$(GO_BUILD_GCFLAGS)") -ldflags "$(GO_LDFLAGS)" -o ./bin/grafana ./pkg/cmd/grafana + $(if $(CGO_ENABLED),CGO_ENABLED=$(CGO_ENABLED)) $(if $(GO_BUILD_OS),GOOS=$(GO_BUILD_OS)) $(if $(GO_BUILD_ARCH),GOARCH=$(GO_BUILD_ARCH)) $(GO) build -buildvcs=false -trimpath $(GO_RACE_FLAG) $(if $(GO_BUILD_TAGS),-tags $(GO_BUILD_TAGS)) $(if $(GO_BUILD_GCFLAGS),-gcflags "$(GO_BUILD_GCFLAGS)") -ldflags "$(GO_LDFLAGS)" -o ./bin/grafana ./pkg/cmd/grafana .PHONY: build-backend build-backend: build-go diff --git a/contribute/developer-guide.md b/contribute/developer-guide.md index d50047f87ac..d66bc038aaf 100644 --- a/contribute/developer-guide.md +++ b/contribute/developer-guide.md @@ -9,7 +9,7 @@ Make sure you have the following dependencies installed before setting up your d - [Git](https://git-scm.com/) - [Go](https://golang.org/dl/) (see [go.mod](../go.mod#L3) for minimum required version) - [Node.js (Long Term Support)](https://nodejs.org), with [corepack enabled](https://nodejs.org/api/corepack.html#enabling-the-feature). See [.nvmrc](../.nvmrc) for supported version. We recommend that you use a version manager such as [nvm](https://github.com/nvm-sh/nvm), [fnm](https://github.com/Schniz/fnm), or similar. -- [GCC](https://gcc.gnu.org/) (required for Cgo] dependencies) +- [GCC](https://gcc.gnu.org/) (optional, not recommded; enables CGO for smaller, dynamically linked binaries) ### macOS @@ -154,6 +154,22 @@ Log in using the default credentials: When you log in for the first time, Grafana asks you to change your password. +#### CGO and static builds + +By default, `make build-go` (and `make run`) does **not** set `CGO_ENABLED`. Go's default behavior is to enable CGO when a C compiler (GCC) is detected on the system, and disable it otherwise. For local development this is fine — CGO gives you a working SQLite driver for the embedded database. + +In **production**, Grafana is built with `CGO_ENABLED=0` to produce a fully static, pure Go binary. This is important because the build environment and the runtime environment are often different (for example, building on Debian but running on Alpine or a scratch container). + +You can control both `CGO_ENABLED` and `LDFLAGS` when invoking Make: + +```sh +# Static build without CGO (production-style) +CGO_ENABLED=0 make build-go + +# Build with Go defaults +unset CGO_ENABLED && make build-go +``` + #### Build on Windows The Grafana backend includes SQLite, a database which requires GCC to compile. So in order to compile Grafana on Windows you need to install GCC with binutils version 2.37 or later. diff --git a/docs/sources/setup-grafana/configure-grafana/_index.md b/docs/sources/setup-grafana/configure-grafana/_index.md index 79c9d8441a8..4c1304b24f7 100644 --- a/docs/sources/setup-grafana/configure-grafana/_index.md +++ b/docs/sources/setup-grafana/configure-grafana/_index.md @@ -370,6 +370,10 @@ Grafana needs a database to store users and dashboards (and other things). By default it is configured to use [`sqlite3`](https://www.sqlite.org/index.html) which is an embedded database (included in the main Grafana binary). +{{< admonition type="caution" >}} +SQLite isn't recommended for production environments; use MySQL or PostgreSQL for production deployments. +{{< /admonition >}} + #### `type` Either `mysql`, `postgres` or `sqlite3`, it's your choice. diff --git a/docs/sources/setup-grafana/installation/_index.md b/docs/sources/setup-grafana/installation/_index.md index 75577d3aed1..20ca825460d 100644 --- a/docs/sources/setup-grafana/installation/_index.md +++ b/docs/sources/setup-grafana/installation/_index.md @@ -66,8 +66,8 @@ Grafana supports the following databases: By default Grafana uses an embedded SQLite database, which is stored in the Grafana installation location. If you need to migrate to a different database later, note that database schema and data migrations are customer-managed operations and fall outside the scope of Grafana Support. -{{< admonition type="note" >}} -SQLite works well if your environment is small, but is not recommended when your environment starts growing. For more information about the limitations of SQLite, refer to [Appropriate Uses For SQLite](https://www.sqlite.org/whentouse.html). If you want [high availability](/docs/grafana/latest/setup-grafana/set-up-for-high-availability), you must use either a MySQL or PostgreSQL database. For information about how to define the database configuration parameters inside the `grafana.ini` file, refer to [[database]](/docs/grafana/latest/setup-grafana/configure-grafana/#database). +{{< admonition type="caution" >}} +SQLite isn't recommended for production environments. It works well for local development and small evaluation instances, but it doesn't scale for production workloads. If you want [high availability](/docs/grafana/latest/setup-grafana/set-up-for-high-availability), you must use either a MySQL or PostgreSQL database. For information about how to define the database configuration parameters inside the `grafana.ini` file, refer to [[database]](/docs/grafana/latest/setup-grafana/configure-grafana/#database). {{< /admonition >}} Grafana supports the versions of these databases that are officially supported by the project at the time a version of Grafana is released. When a Grafana version becomes unsupported, Grafana Labs might also drop support for that database version. See the links above for the support policies for each project.