⚠️ As always, make sure to have a copy of your pb_data directory before upgrading. If you are using PocketBase v0.7.x or older, it is recommended first to upgrade to v0.8.

This release mostly contains internal code improvements and the long-awaited automigrate feature. Additionally, we also support writing custom db migrations with JavaScript (more documentation and examples will be available soon). This also means that the migrate command now works identically with the prebuilt executable and when PocketBase is used as framework (in the near future there are also plans to allow binding to the app event hooks with JavaScript).

There are no breaking changes to the public apis, but depending which exported internals you use in your app, you may have to update your Go code if you are extending PocketBase. Please refer to the CHANGELOG or the notes below for more details.

Changes

• Fixed concurrent multi-relation cascade update/delete (#1138).

• Added the raw OAuth2 user data (meta.rawUser) and OAuth2 access token (meta.accessToken) to the auth response (#654).

• BaseModel.UnmarkAsNew() method was renamed to BaseModel.MarkAsNotNew(). Additionally, to simplify the insert model queries with custom IDs, it is no longer required to call MarkAsNew() for manually initialized models with set ID since now this is the default state. When the model is populated with values from the database (eg. after row Scan) it will be marked automatically as "not new".

• Added Record.OriginalCopy() method that returns a new Record copy populated with the initially loaded record data (useful if you want to compare old and new field values).

• Added new event hooks:

  app.OnBeforeBootstrap()
  app.OnAfterBootstrap()
  app.OnBeforeApiError()
  app.OnAfterApiError()
  app.OnRealtimeDisconnectRequest()
  app.OnRealtimeBeforeMessageSend()
  app.OnRealtimeAfterMessageSend()
  app.OnRecordBeforeRequestPasswordResetRequest()
  app.OnRecordAfterRequestPasswordResetRequest()
  app.OnRecordBeforeConfirmPasswordResetRequest()
  app.OnRecordAfterConfirmPasswordResetRequest()
  app.OnRecordBeforeRequestVerificationRequest()
  app.OnRecordAfterRequestVerificationRequest()
  app.OnRecordBeforeConfirmVerificationRequest()
  app.OnRecordAfterConfirmVerificationRequest()
  app.OnRecordBeforeRequestEmailChangeRequest()
  app.OnRecordAfterRequestEmailChangeRequest()
  app.OnRecordBeforeConfirmEmailChangeRequest()
  app.OnRecordAfterConfirmEmailChangeRequest()
  

• The original uploaded file name is now stored as metadata under the original_filename key. It could be accessed via:

  fs, _ := app.NewFilesystem()
  defer fs.Close()
  
  attrs, _ := fs.Attributes(fikeKey)
  attrs.Metadata["original_name"]
  

• Added support for Partial/Range file requests (#1125). This is a minor breaking change if you are using filesystem.Serve (eg. as part of a custom OnFileDownloadRequest hook):

  // old
  filesystem.Serve(res, e.ServedPath, e.ServedName)
  
  // new
  filesystem.Serve(res, req, e.ServedPath, e.ServedName)
  

• Refactored the migrate command to support external JavaScript migration files using an embedded JS interpreter (goja). This allow writting custom migration scripts such as programmatically creating collections, initializing default settings, running data imports, etc., with a JavaScript API very similar to the Go one (more documentation will be available soon).

  The migrate command is available by default for the prebult executable, but if you use PocketBase as framework you need register it manually:

  migrationsDir := "" // default to "pb_migrations" (for js) and "migrations" (for go)
  
  // load js files if you want to allow loading external JavaScript migrations
  jsvm.MustRegisterMigrations(app, &jsvm.MigrationsOptions{
    Dir: migrationsDir,
  })
  
  // register the `migrate` command
  migratecmd.MustRegister(app, app.RootCmd, &migratecmd.Options{
    TemplateLang: migratecmd.TemplateLangJS, // or migratecmd.TemplateLangGo (default)
    Dir:          migrationsDir,
    Automigrate:  true,
  })
  

  The refactoring also comes with automigrations support.

  If Automigrate is enabled (true by default for the prebuilt executable; can be disabled with --automigrate=0), PocketBase will generate seamlessly in the background JS (or Go) migration file with your collection changes. The directory with the JS migrations can be committed to your git repo. All migrations (Go and JS) are automatically executed on server start. Also note that the auto generated migrations are granural (in contrast to the migrate collections snapshot command) and allow multiple developers to do changes on the collections independently (even editing the same collection) miniziming the eventual merge conflicts. Here is a sample JS migration file that will be generated if you for example edit a single collection name:

  // pb_migrations/1669663597_updated_posts_old.js
  migrate((db) => {
    // up
    const dao = new Dao(db)
    const collection = dao.findCollectionByNameOrId("lngf8rb3dqu86r3")
    collection.name = "posts_new"
    return dao.saveCollection(collection)
  }, (db) => {
    // down
    const dao = new Dao(db)
    const collection = dao.findCollectionByNameOrId("lngf8rb3dqu86r3")
    collection.name = "posts_old"
    return dao.saveCollection(collection)
  })
  

• Added new Dao helpers to make it easier fetching and updating the app settings from a migration:

  dao.FindSettings([optEncryptionKey])
  dao.SaveSettings(newSettings, [optEncryptionKey])
  

• Moved core.Settings to models/settings.Settings:

  core.Settings{}           -> settings.Settings{}
  core.NewSettings()        -> settings.New()
  core.MetaConfig{}         -> settings.MetaConfig{}
  core.LogsConfig{}         -> settings.LogsConfig{}
  core.SmtpConfig{}         -> settings.SmtpConfig{}
  core.S3Config{}           -> settings.S3Config{}
  core.TokenConfig{}        -> settings.TokenConfig{}
  core.AuthProviderConfig{} -> settings.AuthProviderConfig{}
  

• Changed the mailer.Mailer interface (minor breaking if you are sending custom emails):

  // Old:
  app.NewMailClient().Send(from, to, subject, html, attachments?)
  
  // New:
  app.NewMailClient().Send(&mailer.Message{
    From: from,
    To: to,
    Subject: subject,
    HTML: html,
    Attachments: attachments,
    // new configurable fields
    Bcc: []string{"bcc1@example.com", "bcc2@example.com"},
    Cc: []string{"cc1@example.com", "cc2@example.com"},
    Headers: map[string]string{"Custom-Header": "test"},
    Text: "custom plain text version",
  })
  

  The new *mailer.Message struct is also now a member of the MailerRecordEvent and MailerAdminEvent events.

• Other minor UI fixes and improvements