drsybren/Flamenco
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Website: document more of the sqlc workflow

Browse Source 
Document installation & use of sqlc.

Installing sqlc is only necessary to regenerate the database code. Once
generated, the code is independent of sqlc.
This commit is contained in:
Sybren A. Stüvel 2024-05-30 09:42:25 +02:00
parent 7a9f809c43
commit 8b01012539
2 changed files with 39 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -8,15 +8,46 @@ object-relational mapper (but see the note below).
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. Because of this, avoid `NOT NULL` columns, as they will be problematic
in this process.
tables.
## 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/).
To generate the SQLC schema file:
### Installing & using 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:
```sh
go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest
```
The [precompiled sqlc binaries][sqlc-precompiled] work just as well, so choose
whatever works for you.
{{< hint type=important >}}
Installing 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.
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
@ -27,3 +58,5 @@ To generate Go code with SQLC after changing `schema.sql` or `queries.sql`:
go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest
sqlc generate
```
[goose]: https://github.com/pressly/goose

3
web/project-website/content/development/getting-started/_index.md
View File

@ -126,7 +126,10 @@ enable the race condition checker, and all other kinds of useful things.
If you're interested in helping out with Flamenco development, please read [Get Involved][get-involved]!
If you need to change or add any database queries, read through the [database section][database].
[get-involved]: {{<ref "development/get-involved" >}}
[database]: {{<ref "development/database" >}}
## Software Design