Using Sequin to trigger side effects
Use Sequin to trigger side effects in your application, like sending a welcome email to a new user.
When you insert a new user into your database, you might want to send them a welcome email:
- Sequin captures every
insert
on yourusers
table using a durable replication slot. - It then asynchronously queues and delivers messages to the
sendWelcomeEmail
function. Messages are retried until they are acknowledged by the function. - With a simple HTTP interface, replays, and observability built in you can easily scale this implementation.
This is a common “side effect” pattern. This guide shows you how to implement side effects with Sequin.
Example
Connect your database to Sequin
- Login to your Sequin account and click the Connect Database button on the dashboard.
- Paste the connection string for your database (or enter your connection credentials).
- Create a replication slot and publication for Sequin using the SQL commands in the console.
- Name your database and click Connect Database to finish.
Your database is now connected to Sequin. If you’d like a step-by-step guide, check out our Quickstart.
Create a consumer to captures `inserts` on the `users` table
Create a webhook subscription that captures changes from the users
table. It’ll then send an HTTP request to your application with the new user’s information (which you’ll handle in the next step).
- Click the Create Consumer button and then select the
users
table. - Because you want to capture every
insert
you can leave the Filter field blank. - Select the Changes option and then choose Push for the consumer type.
- Enter the the HTTP endpoint where Sequin will send the changes. Add any headers you need to authenticate the request.
- Click Create Consumer to finish.
Your consumer is now created. If you’d like a step-by-step guide, check out our Quickstart.
Handle messages in your application
Sequin is now capturing every insert
on the users
table and sending it to your HTTP endpoint. When a new user is inserted:
insert into users (name, email) values ('John Doe', 'john.doe@example.com');
Sequin will send the new user’s information to your webhook endpoint:
{
"record": {
"id": 1,
"name": "Chani",
"title": "Fremen Warrior",
"email": "chani@arrakis.gov",
"spice_allocation": 500,
"is_sayyadina": true
},
"changes": null,
"action": "insert",
"metadata": {
"table_schema": "public",
"table_name": "users",
"commit_timestamp": "2023-10-15T14:30:00Z",
"consumer": {
"id": "e2f9a3b1-7c6d-4b5a-9f8e-1d2c3b4a5e6f",
"name": "send_welcome_email_consumer"
}
}
}
You can handle this message in your application and send a welcome email:
// Webhook handler for new user registration
app.post('/webhook/new-user', async (req, res) => {
const { name, email } = req.body;
try {
// Send welcome email
await sendWelcomeEmail(name, email);
res.status(200).send('Welcome email sent successfully');
} catch (error) {
res.status(500).send('Error sending welcome email');
}
});
Importantly, to ensuer every new user receives an email - Sequin will retry message until the HTTP request is acknowledged with a 200 status.
Benefits
Implementing welcome emails as a side effect has several benefits:
- Asynchronous: Sending the email should not halt your application or the user.
- Scalable: You can easily scale this implementation with a simple HTTP endpoint.
Sequin handles the hard parts for you:
- Transactional guarantees: Sequin ensures that the email is sent for every new user. Even if a users is added to your database via a trigger or other means, Sequin will ensure the email is sent.
- Reliable retries: Sequin will retry failed HTTP requests until they are acknowledged.
- No custom infrastructure: You don’t need to run any custom infrastructure to send emails.
- Observability: You can easily see the status of your messages and re-send failed messages.
Next steps
To add a side effect to your application, you might want to:
- Go through our Quickstart guide to connect your database to Sequin and create a consumer.
- Learn more about how Sequin works.