blender/flamenco
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Website: update developer documentation about the database

Browse Source 
Clarify the uses of SQLC and Goose, remove the last mention of GORM.
This commit is contained in:
Sybren A. Stüvel 2025-08-25 12:55:40 +02:00
parent 64a752dfdb
commit e5215b86b1
1 changed files with 37 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
web/project-website/content/development/database/_index.md
View File

@ -3,60 +3,66 @@ title: Database
weight: 50 weight: 50
--- ---
Flamenco Manager and Worker use SQLite as database, and GORM as Flamenco Manager and Worker use SQLite as database, sqlc as object-relational
object-relational mapper (but see the note below). mapper, and Goose for schema migrations.
Since SQLite has limited support for altering table schemas, migration requires {{< hint type=important >}}
copying old data to a temporary table with the new schema, then swap out the Some of these tools assume that you have your database in
tables. `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 ## SQLC
Flamenco mostly uses [GORM](https://gorm.io/) for interfacing with its SQLite database. This Flamenco uses [sqlc](https://sqlc.dev/) for interfacing with its SQLite database.
is gradually being phased out, to be replaced with [SQLC](https://sqlc.dev/).
### Installing & using SQLC ### Installing SQLC
SQLC can be installed ([installation docs][sqlc-install]) with a `go install` SQLC can be used via `go tool sqlc`. This will run the tool, downloading &
command just like any other Go package, but that does depend on a C/C++ building it if necessary. This does depend on a C/C++ compiler, so if you do not
compiler: have one, or get build errors, the [precompiled sqlc binaries][sqlc-precompiled]
work just as well. Choose whatever works for you.
```sh Because of the above, SQLC is not part of `make with-deps` and not included in
go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest `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 For handling schema changes and database versioning, see below.
whatever works for you.
{{< hint type=important >}} {{< hint type=note >}}
Installing sqlc itself is only necessary to regenerate the database code. Once Running sqlc itself is only necessary to regenerate the database code. Once
generated, the code is independent of sqlc. 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 >}} {{< /hint >}}
[sqlc-install]: https://docs.sqlc.dev/en/latest/overview/install.html
[sqlc-precompiled]: https://docs.sqlc.dev/en/latest/overview/install.html#downloads [sqlc-precompiled]: https://docs.sqlc.dev/en/latest/overview/install.html#downloads
### Handling Schema changes ### Handling Schema changes
Database schema changes are managed with [Goose][goose]. Every change is defined 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 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 ```sh
make db-migrate-up make db-migrate-up
go run ./cmd/sqlc-export-schema go run ./cmd/sqlc-export-schema
``` go tool sqlc generate
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
``` ```
[goose]: https://github.com/pressly/goose [goose]: https://github.com/pressly/goose