You can use fixtures to provide initial data for testing and development purposes. You write fixtures in YAML format and load them on demand from tests or migrations.

Creating fixtures

A fixture is a plain YAML file with the only exception being that you can use text/templateopen in new window expressions to generate values. Here is how a fixture for a User model might look like:

- model: User
      name: John Smith
      created_at: '{{ now }}'
    - name: Jonh Doe
      created_at: '{{ now }}'

A single fixture can contain data for multiple models. You can also use the _id field to name rows and reference them from other models using text/template syntax:

- model: User
    - _id: smith
      name: John Smith
      created_at: '{{ now }}'
    - _id: doe
      name: Jonh Doe
      created_at: '{{ now }}'

- model: Org
    - name: "{{ $.User.smith.Name }}'s Org"
      owner_id: '{{ $.User.smith.ID }}'
    - name: "{{ $.User.doe.Name }}'s Org"
      owner_id: '{{ $.User.doe.ID }}'

Loading fixtures

Assuming the fixture is stored in testdata/fixture.yml, you can load it with the following code:

// Let the db know about the models.
db.RegisterModel((*User)(nil), (*Org)(nil))

fixture := dbfixture.New(db)
err := fixture.Load(ctx, os.DirFS("testdata"), "fixture.yml")

By using fixture.WithRecreateTables() option, you can make bun drop existing tables and replace them with new ones. Or you can use fixture.WithTruncateTables() option to truncate tables.

fixture := dbfixture.New(db, dbfixture.WithRecreateTables())
fixture := dbfixture.New(db, dbfixture.WithTruncateTables())

You can also register and use in fixtures custom template functions:

funcMap := template.FuncMap{
	"now": func() string {
		return time.Now().Format(time.RFC3339Nano)

fixture := dbfixture.New(db, dbfixture.WithTemplateFuncs(funcMap))

Retrieving fixture data

Later you can retrieve the loaded models using Row and MustRow methods:

fmt.Println("Smith", fixture.MustRow("User.smith").(*User))

You can also retrieve the rows without the _id field by their primary key:

fmt.Println("Org with id=1", fixture.MustRow("Org.pk1").(*Org))

Source code

You can find the source code for the example above on GitHubopen in new window.