Trigger Inngest events from database changes
How to use Sequin to trigger Inngest events from database changes.
Inngest is a serverless jobs queue. You write and test functions locally in your project, and then deploy them to Inngest where they reliably invoke the functions you write. Inngest handles the infrastructure, observability, and execution.
Often, you want to trigger Inngest events when a record in your database is created, updated, or deleted. For instance, you might want to send a welcome email to a user as soon as they are inserted into the database:
In this guide, you’ll learn how to use Sequin to trigger Inngest events from database changes.
Prerequisites
You are about to create a local Inngest function that sends a welcome email to a user as soon as they are inserted into the database. Sequin ensures that every new user insert
triggers an Inngest event that your function can then process (i.e. exactly once processing guarantee).
You’ll need the following:
- An JavaScript/TypeScript project with Inngest installed
If you don’t have one already, follow Inngest’s Next.js quickstart guide to setup your project. You can return to this guide when you’re ready to write your first Inngest function.
- A Sequin account
- A Postgres database
Create an Inngest function
Start by creating a new Inngest function that sends a welcome email to a user when a webhook/user.inserted
event(we’ll define this event below) is received.
Create a `send-welcome-email` function
In your functions.ts
file (typically located in src/inngest/functions.ts
), create a new function:
import { inngest } from "./client";
export const sendWelcomeEmail = inngest.createFunction(
{ id: "send-welcome-email" },
{ event: "webhook/users.insert" },
async ({ event }) => {
const user = event.data;
//function to send welcome email
return { event, body: `Welcome email sent to ${user.email} with subject "Hi ${user.name}"` };
},
);
This function takes the webhook/users.insert
event as input, extracts the user data, and sends a welcome email to the user.
Add the function to `Inngest.serve()`
The Inngest.serve()
handler registers your function with Inngest so it can invoke the function.
In your route.ts file (typically located in src/app/api/inngest/route.ts
) register the sendWelcomeEmail
function:
import { serve } from "inngest/next";
import { inngest } from "../../../inngest/client";
import { sendWelcomeEmail } from "../../../inngest/functions";
export const { GET, POST, PUT } = serve({
client: inngest,
functions: [sendWelcomeEmail],
});
Trigger the function with a test event
Test the sendWelcomeEmail
function by trigger a test eveng in the Inngest development server:
- Run your Next.js project and Start the Inngest development server:
npm run dev # in a new terminal, start the inngest development server npx inngest-cli@latest dev
- Open the Inngest dashboard in your browser and navigate to the Functions tab.
- You should see the
send-welcome-email
function. Click the Invoke button and enter the following event payload:{ "data": { "name": "John Doe", "email": "john.doe@example.com" } }
- Click the Invoke Function button and then navigate to the Runs tab. You should see the run you just triggered:
You’ve successfully created an Inngest function that sends a welcome email to a user when a webhook/users.insert
event is received. In the next step, you’ll trigger this event with Webhook.
Create an Inngest webhook
Now, create a webhook to trigger the sendWelcomeEmail
function:
Create a new webhook in the Inngest dashboard
In the Inngest Cloud Dashboard, navigate to the Webhooks tab and click the Create Webhook button.
Copy the webhook URL. You’ll provide this URL to Sequin when you create a consumer below.
Transform the Sequin payload into an Inngest event
Sequin will send a payload to your webhook containing the database change:
{
"record": {
"id": 1,
"name": "John Doe",
"email": "john.doe@example.com"
},
"changes": null,
"action": "insert",
"metadata": {
"table_schema": "public",
"table_name": "users",
"commit_timestamp": "2024-02-20T14:30:00Z",
"consumer": {
"id": "e2f9a3b1-7c6d-4b5a-9f8e-1d2c3b4a5e6f",
"name": "new_user_consumer"
}
}
}
You need to transform this payload into an Inngest event that triggers the sendWelcomeEmail
function. To do so, use a Transform to extract the the event name and data from the Sequin payload:
function transform(evt, headers = {}, queryParams = {}) {
return {
// Rename this webhook to give the events a unique name,
// or use a field from the incoming event as the event name.
name: `webhook/${evt.metadata.table_name}.${evt.action}`,
data: evt.record,
};
};
This will create an Inngest event with the name webhook/users.insert
and the data from the Sequin record
field:
You’ve successfully created a webhook endpoint that transforms Sequin payloads into Inngest events. In the next steps, you’ll configure Sequin to send events to your webhook.
Create a Sequin push consumer
You’ll now configure Sequin to capture every new user in your database and send an event to the Inngest webhook you created above.
Connect Sequin to your database
- Login to your Sequin account and click the Add New Database button.
- Enter the connection details for your Postgres database.
- Follow the instructions to create a publication and a replication slot by running two SQL commands in your database:
create publication sequin_pub for all tables;
select pg_create_logical_replication_slot('sequin_slot', 'pgoutput');
- Name your database and click the Connect Database button.
Sequin will connect to your database and ensure that it’s configured properly.
If you need step-by-step connection instructions to connect Sequin to your database, check out our quickstart guide.
Create a Push Consumer
With your database connected, create a push consumer that will send events to Inngest:
- Navigate to the Consumers tab and click the Create Consumer button.
- Select your users table (i.e
public.users
). - Select to process changes and click Continue.
- Configure which kinds of changes you want to capture and apply filters (for instance, ignore internal emails). Since you just want to email all new users, you’ll capture just the
insert
changes and apply no additional filters:
- On the next screen, select Push to have Sequin send the events to your webhook URL. Click Continue.
- Now, give your consumer a name (i.e.
new_user_consumer
) and in the HTTP Endpoint section enter the webhook URL you created in Inngest as the Base URL. You don’t need any headers or a path:
- Click the Create Consumer button. Sequin will verify your database is set up properly and may give you another SQL command to run to ensure every new user is captured.
Your Sequin consumer is now created and ready to send events to Inngest.
Test end-to-end
Create a new user in your database
Insert a new user into your database:
insert into users (name, email) values ('John Doe', 'john.doe@example.com');
Trace the change in the Sequin dashboard
In the Sequin console, navigate to the Trace tab and confirm that Sequin delivered the event to Inngest:
Confirm the event in the Inngest dashboard
In the Inngest Cloud dashboard, navigate to the Events tab, select the webhook/users.insert
event, and open the Logs tab. You should see the event you just created:
Now, click the Send to Dev Server button to forward the event to your local Inngest development server.
Forward the event to your local Inngest development server
Finally, in your local Inngest development server, navigate to the Runs tab and confirm that the event was received and your send-welcome-email
function was invoked:
Every new user will now trigger an Inngest event that sends a welcome email!
Next steps
You’ve implemented a complete workflow that captures every new user in your database, triggers an Inngest event, and sends a welcome email. This is a simple pattern you can expand on to fit your needs.
From here you can tailor your Sequin consumers and Inngest functions to cover more use cases. Then deploy your Inngest functions to production. Here are some resources to help:
- Tailor your Sequin consumers to your use case.
- Deploy your Inngest functions to production.
- Make your Inngest functions more robust with retries, timeouts, and other features.
Was this page helpful?