Models

Models extending the ApplicationBackgroundedModel will have the added capability of being able to call any of their underlying static and instance methods in a background job. Similar to the ApplicationScheduledService class, it will have both a static and instance background method, which will be used to call underlying methods in the background.

class User extends ApplicationBackgroundedModel {
  ...
  public static async doSomething(stuff: string, thing: number) {}
}

await User.background('doSomething', 'a little howyadoin', 1)

This will trigger a new job into the background queue system. When a worker picks up this job, it will call await User.doSomething('a little howyadoin', 1).

Keep background arguments small and durable: pass IDs or scalar values, not model instances or large payloads.

instance methods

Models behave differently when calling instance methods in the background. This is because a model is a reflection of a specific row in a specific table in your database. before calling any instance methods on your model instances, psychic will make sure to do a lookup of the model by its primary key.

class User extends ApplicationBackgroundedModel {
  ...
  public async doSomething(stuff: string, thing: number) {}
}

const user = await User.firstOrFail()
await user.background('doSomething', 'howyadoin', 1)

In the above example, Psychic will make sure to store the primaryKey belonging to the user var, and then, once a worker picks up the job, it will do a lookup based on the primary key that was stored.

If the row has been deleted before the worker runs, the lookup should be treated as a no-op rather than a retryable failure.

When calling this.background(...) from a model lifecycle hook, use a commit hook such as @deco.AfterCreateCommit, @deco.AfterUpdateCommit, or @deco.AfterSaveCommit. Regular hooks run inside the surrounding transaction, so the worker can run before a created row is visible or before an update has committed.