Data and migrations
This page explains where Behemoth keeps its data, where the tables come from, and how a change to your declarations reaches your database. Read How Behemoth fits together first.
Behemoth does not create tables when it starts. You declare tables in code, Behemoth writes a migration for them, and you apply it before the first Boot.
The database layer #
Behemoth stores users, sessions, and tokens in your database, through an adapter. An adapter is a small module for one database that you pass to Boot. Each adapter is a separate Go module, so you download only the ones you use.
The following table lists the adapters. Each module path starts with github.com/go-behemoth/behemoth/storage/adapters/:
| Database | Module | Minimum release |
|---|---|---|
| PostgreSQL | postgres | 15 |
| MySQL | mysql | 8.4 |
| SQL Server | sqlserver | 2019 |
| SQLite | sqlite | 3.53, and it needs cgo |
| MongoDB | mongo | 7.0, as a replica set |
| Bun and GORM | bun and gorm | For an application that already uses one of these libraries |
The Supported databases reference lists the releases that each adapter is tested on.
Build the adapter with app.Resolver, the value that Prepare returns. It makes your queries and your migrations agree on table and column names.
db := postgres.NewPostgresAdapter(sqlDB, app.Resolver)Optional key-value storage #
By default, sessions and rate-limit counters live in your database. To keep them in a key-value store instead, pass a Redis adapter in BootConfig.KV. A session is then served from the store without a database read.
The store and the adapter #
Your code reaches data in two ways, both on the AuthContext:
ac.Storereads and writes Behemoth's own tables. It adds what a bare write skips: ids, timestamps, hooks, and a transaction around the write.ac.DBis the adapter. Use it for your own tables.
Where tables come from #
Every table is declared in code during Prepare, in a fixed order. A later declarer can add columns to a table that an earlier one declared.
| Order | Declared by | Examples |
|---|---|---|
| 1 | Behemoth itself | users, accounts, sessions, tokens, verification_codes, reserved_values, rate_limits, audit_log. See Core tables. |
| 2 | Each plugin, in dependency order | A plugin's own tables, or extra columns on users |
| 3 | Your application | Your own tables, or extra columns on any table above |
Declare your own tables #
Pass a function to PrepareConfig.Schema. It declares a model, a Go type that implements behemoth.Model, together with its table:
func declareSchema(reg schema.Registry) error {
return reg.Declare(
&Todo{},
schema.Table{
Name: "todos",
Columns: []schema.Column{
{Name: "id", Type: schema.ColTypeUuid, PrimaryKey: true},
{Name: "title", Type: schema.ColTypeString, Length: 255},
{Name: "done", Type: schema.ColTypeBoolean, Default: false},
},
},
)
}
app, err := engine.Prepare(
plugins,
engine.PrepareConfig{
Schema: declareSchema,
},
)
if err != nil {
log.Fatal(err)
}The examples/init directory in the repository has the complete Todo model. A table can also set a PhysicalName, so that the name in your code differs from the name in the database. The resolver translates between them.
A column that you add to users stays private until you mark it public. Routes that return a user send only its public columns. See Core tables.
Migrations #
A migration is the list of schema operations that makes your database match your declarations. Behemoth compares what you declared with what the database holds, and writes the difference to your migrations folder as a numbered migration.
Because Prepare needs no connection, the behemoth command can read your declarations without starting your application.
Choose a migration path #
Set the path in PrepareConfig.Migration. The two paths differ in who applies the migration:
PathGenerateOnly (default) | PathManaged | |
|---|---|---|
| Behemoth | Writes a .json migration and a .sql script | Writes the same files, then applies the migration itself |
| You | Apply the script with your own tool, such as psql | Run behemoth migrate |
| Compared with | The live database | A snapshot that Behemoth keeps |
| Extra tables | None | Two tables for its own record of applied migrations |
| Use it when | You already have a migration tool, or a team reviews every change | The service has no other migration tool |
The default never touches your database. behemoth generate writes files and changes nothing else.
The workflow #
You repeat the same steps whenever your declarations change, for example when you add a plugin or a table:
- Change your declarations.
- Run
behemoth generateto preview the next migration. It writes nothing but a draft file. - Answer any questions. See Questions.
- Run
behemoth generate -confirmto write the migration to your migrations folder. - Review the
.sqlscript. - Apply it. On the default path, run the script with your own tool. On the managed path, run
behemoth migrate -confirm. - Run
behemoth generateagain. When the database matches your declarations, it answersNo schema changes detected.
Commit the whole migrations folder. Behemoth takes the number of the next migration from the files in it.
Questions #
Some differences have more than one answer. If a column becomes shorter, Behemoth can alter it, which may reject existing rows, or leave it as it is. generate asks you in the terminal, and saves each answer in draft.json in your migrations folder.
In CI, where there is no terminal, a question without an answer stops the command with exit code 1. Commit the draft file, or give the answer with the -answer flag.
Set up the command #
The command reads your plugins and schema from your own code, so you don't describe them in a second place. Put two functions in a file named behemoth.go, in a package other than main:
package auth
func Prepare() (*engine.PreparedApp, error) {
return engine.Prepare(
[]core.Plugin{emailpassword.New(emailpassword.Options{})},
engine.PrepareConfig{
Migration: migration.MigrationConfig{
FolderPath: "migrations",
},
Schema: declareSchema,
},
)
}
func MigrationBackend(
ctx context.Context,
app *engine.PreparedApp,
) (migration.Backend, error) {
db, err := OpenDB(ctx)
if err != nil {
return migration.Backend{}, err
}
return postgres.MigrationBackend(db, app.Resolver), nil
}In this example, OpenDB is your own function that opens a *sql.DB. For MySQL, return mysql.MigrationBackend instead. Your server calls the same Prepare and passes the result to Boot, so the tables a migration creates are the tables your server reads.
Then install the launcher and run it from your application's directory:
go install github.com/go-behemoth/behemoth/cmd/behemoth@latest
cd my-app
behemoth generateThe command line is a first version. It has ready-made setups for PostgreSQL and MySQL, and the launcher needs the Go toolchain. The Migration CLI reference describes the other databases, running without the launcher, and exit codes.
Hand-written migrations #
For a change that Behemoth cannot derive, such as a data backfill, pass a migration.CustomMigration in PrepareConfig.Migrations. Behemoth places it among the generated operations by its DependsOn list. The name of a custom migration is permanent, so never reuse one.
Limits #
- Apply the first migration before
Boot.Bootdoes not create tables, and a missing table fails the first query. - SQLite needs foreign keys switched on.
Bootrefuses a SQLite database that does not enforce them. Add_foreign_keys=onto the DSN. - MongoDB has no migrations. It needs a replica set, and you call
EnsureIndexeson the adapter to create the unique indexes your schema declares.Bootrefuses to start without them. See MongoDB. - Other SQL databases need a hand-built backend. The command has ready-made backends for PostgreSQL and MySQL only. For SQLite or SQL Server, you fill
migration.Backendfrom the adapter module's driver.
Next steps #
To go deeper, read the following pages:
- Migration CLI: Every command, flag, and exit code.
- Core tables: The tables Behemoth declares, and how to write to them.
- MongoDB: Setup and indexes on MongoDB.
- Plugins and hooks: How plugins declare their tables.