From e5215b86b19346838444de66a7acafce6a90d1f0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sybren=20A=2E=20St=C3=BCvel?= <sybren@blender.org>
Date: Mon, 25 Aug 2025 12:55:40 +0200
Subject: [PATCH] Website: update developer documentation about the database

Clarify the uses of SQLC and Goose, remove the last mention of GORM.
---
 .../content/development/database/_index.md    | 68 ++++++++++---------
 1 file changed, 37 insertions(+), 31 deletions(-)

diff --git a/web/project-website/content/development/database/_index.md b/web/project-website/content/development/database/_index.md
index 1230ce57..e227d9c9 100644
--- a/web/project-website/content/development/database/_index.md
+++ b/web/project-website/content/development/database/_index.md
@@ -3,60 +3,66 @@ title: Database
 weight: 50
 ---
 
-Flamenco Manager and Worker use SQLite as database, and GORM as
-object-relational mapper (but see the note below).
+Flamenco Manager and Worker use SQLite as database, sqlc as object-relational
+mapper, and Goose for schema migrations.
 
-Since SQLite has limited support for altering table schemas, migration requires
-copying old data to a temporary table with the new schema, then swap out the
-tables.
+{{< hint type=important >}}
+Some of these tools assume that you have your database in
+`flamenco-manager.sqlite`. Even though Flamenco Manager can store its database
+anywhere, these development tools are not as flexible.
+
+So for simplicity sake, set `database: flamenco-manager.sqlite` in your
+`flamenco-manager.yaml`.
+{{< /hint >}}
 
 ## SQLC
 
-Flamenco mostly uses [GORM](https://gorm.io/) for interfacing with its SQLite database. This
-is gradually being phased out, to be replaced with [SQLC](https://sqlc.dev/).
+Flamenco uses [sqlc](https://sqlc.dev/) for interfacing with its SQLite database.
 
-### Installing & using SQLC
+### Installing SQLC
 
-SQLC can be installed ([installation docs][sqlc-install]) with a `go install`
-command just like any other Go package, but that does depend on a C/C++
-compiler:
+SQLC can be used via `go tool sqlc`. This will run the tool, downloading &
+building it if necessary. This does depend on a C/C++ compiler, so if you do not
+have one, or get build errors, the [precompiled sqlc binaries][sqlc-precompiled]
+work just as well. Choose whatever works for you.
 
-```sh
-go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest
+Because of the above, SQLC is not part of `make with-deps` and not included in
+`make generate-go`.
+
+### Using SQLC
+
+The Manager and Worker SQL files can be found in
+`internal/manager/persistence/sqlc` and `internal/worker/persistence/sqlc`.
+After updating the `.sql` files, run:
+
+```shell
+> go tool sqlc generate   # Easiest to get running, if it works for you.
+> sqlc generate           # If you got the precompiled binaries.
 ```
 
-The [precompiled sqlc binaries][sqlc-precompiled] work just as well, so choose
-whatever works for you.
+For handling schema changes and database versioning, see below.
 
-{{< hint type=important >}}
-Installing sqlc itself is only necessary to regenerate the database code. Once
+{{< hint type=note >}}
+Running sqlc itself is only necessary to regenerate the database code. Once
 generated, the code is independent of sqlc.
-
-Since installing sqlc via `go install` requires a C/C++ compiler, it is **not** part
-of the `make with-deps` script. Because of this, it is also **not** included in the
-`make generate-go` script.
 {{< /hint >}}
 
-[sqlc-install]: https://docs.sqlc.dev/en/latest/overview/install.html
 [sqlc-precompiled]: https://docs.sqlc.dev/en/latest/overview/install.html#downloads
 
 ### Handling Schema changes
 
 Database schema changes are managed with [Goose][goose]. Every change is defined
 in a separate SQL file, and has the queries to make the change and to roll it
-back. Of course the roll-back is only possible when no data was removed.
+back. Of course not all changes can be losslessly rolled back.
+
+SQLC needs to know the final schema those Goose migrations produced. After
+adding a migration, you can use this little helper tool to regenerate the SQLC
+schema file:
 
-SQLC needs to know the final schema those Goose migrations produced. To generate
-the SQLC schema from the database itself, run:
 ```sh
 make db-migrate-up
 go run ./cmd/sqlc-export-schema
-```
-
-To generate Go code with SQLC after changing `schema.sql` or `queries.sql`:
-```sh
-go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest
-sqlc generate
+go tool sqlc generate
 ```
 
 [goose]: https://github.com/pressly/goose