Document database migrations

[rokf]

Hi Paul,

We've recently discussed the topic of database migrations on the redbean Discord.

You've provided a helpful example to me and agreed that the upgrade method isn't documented well enough. This was the example:

local dbm = fm.makeStorage(DBNAME, SQLSETUP)
local changes, cherr = dbm:upgrade()
if not changes then
  -- execute VACUUM, which may fix some integrity errors and retry
  -- change errors are reported later, if VACUUM fixed the issue
  dbm:execute("VACUUM")
  changes = assert(dbm:upgrade())
end
-- the rest of the module code
-- log the error that was resolved (as a warning)
if cherr then fm.logWarn("upgraded DB with errors resolved: "..cherr) end
if #changes > 0 then
  fm.logWarn("upgraded DB to v%s\n%s",
    dbm:fetchOne("PRAGMA user_version").user_version,
    table.concat(changes, ";\n"))
end

This was the comment (message) you've sent to me alongside the example.

I include PRAGMA user_version=<version>; in the script itself and increment it as needed (just for my reference in case I need to troubleshoot the issue or ask what DB version is in place). It's also logged after a successful upgrade.
The initial setup is no different from any subsequent one; you just write whatever your current version expects to have in the SQLSETUP script (that is passed to makeStorage) and upgrade is supposed to take care of the rest (with some limitations).

I've created this issue for the purpose of potential further discussions on this topic and so that it doesn't get forgotten. I hope you don't mind, otherwise feel free to close it.

Thanks!