Guides
Custom Database Clients

Custom database clients

Included clients

We have support for two clients:

  1. pg (opens in a new tab) (included with sidetrack)

  2. prisma (opens in a new tab) (install @sidetrack/client-prisma)

The pg client can be used as follows:

ts
import { usePg, Sidetrack } from "sidetrack";
import { Pool } from "pg";
 
// You can also use a pg.Client instead of a pg.Pool
const pool = new Pool();
 
const sidetrack = new Sidetrack<{
  userOnboarding: { email: string };
}>({
  databaseOptions: {
    connectionString: process.env["DATABASE_URL"]!,
  },
  queues: {
    userOnboarding: {
      handler: async (job) => {
        console.log(`Welcome ${job.payload.email}`);
      },
    },
  },
  // This will apply to all methods available on sidetrack
  dbClient: usePg(pool),
});
 
// You can also override the connection per method
sidetrack.insertJob(
  "userOnboarding",
  { email: "hello@example.com" },
  {
    dbClient: usePg(pool),
  },
);
ts
import { usePg, Sidetrack } from "sidetrack";
import { Pool } from "pg";
 
// You can also use a pg.Client instead of a pg.Pool
const pool = new Pool();
 
const sidetrack = new Sidetrack<{
  userOnboarding: { email: string };
}>({
  databaseOptions: {
    connectionString: process.env["DATABASE_URL"]!,
  },
  queues: {
    userOnboarding: {
      handler: async (job) => {
        console.log(`Welcome ${job.payload.email}`);
      },
    },
  },
  // This will apply to all methods available on sidetrack
  dbClient: usePg(pool),
});
 
// You can also override the connection per method
sidetrack.insertJob(
  "userOnboarding",
  { email: "hello@example.com" },
  {
    dbClient: usePg(pool),
  },
);

Similarly, the @sidetrack/client-prisma package exposes a usePrisma function that can be used to create a client that works with prisma. You can find the documentation for it here (opens in a new tab).

💡

With this custom client, you can now run most of the functions that are available within the Sidetrack class in a transaction. Pass in a client that's running within a transaction, and it "just works"!

Creating your own client

Sidetrack is designed to support working with your database client library of choice, as long as it works with the databases that are supported by sidetrack. To do this, you need to implement the SidetrackDatabaseClient interface, which you can find here (opens in a new tab). It currently has one method called execute.

For example, you can find the implementation of the usePg function here (opens in a new tab)

Running MigrationsTesting Sidetrack