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.

Reach for this only when the model itself needs to background its own methods. For most use cases, prefer a backgrounded service instead — it keeps the two-method (public entry point + _-prefixed implementation) pattern that most background work follows.

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.