ezidam/crates/database/readme.md

sql

sql interactions for ezidam

the purpose of this crate is only to interact with the database

initial setup

• install https://github.com/casey/just (it's like make but simpler)
• install https://github.com/launchbadge/sqlx/tree/main/sqlx-cli (it's the tool to interact with the database)
• install sqlite (if it is not already installed)
• run just create to create an empty database

tools

• just run to run pending migrations (in case they are not already applied)
• just reset to trash the database, create a new one and apply migrations

offline

save

the command just offline is used to verify if all sql queries are valid. the result will be placed in sqlx-data.json and is used to compile the crate. if this command fails the crate will not compile.

since this command will have be executed frequently, find a way to run this command when any files are modified inside this crate.

• vscode: TODO
• clion: https://www.jetbrains.com/help/clion/using-file-watchers.html

check

the command just offline_check is here to verify if offline data is up-to-date. it will return a nonzero exit status if data is not up-to-date.

it is mainly used in CI, but you can also use it to determinate if just offline is required to run.

migrations

new

use just new <name> to create a new SQL migration. the parameter <name> should indicate what the migration is doing.

fix mistakes

if there is a mistake in the latest migration, but it has already been applied, use just revert_last to revert it. make your modifications, and run just run to apply it again.

note: this works only for the most recent migration, if there is a mistake in an earlier migration, you will have to reset the whole database with just reset.

consider making a new migration to fix the broken migration, and document it.

miscellaneous

the command just build_script will create a rust build script build.rs to trigger recompilation when a new migration is added. this action can be done only at the beginning of the project.