Meili CDC user guide

meilisearch-cdc copies a table once, then streams every insert, update and delete into a Meilisearch index in near real time. It ships as one self-contained program with an embedded state store and a live dashboard, and it starts with zero configuration.

The meilisearch-cdc dashboard overview with tasks by state, throughput, snapshot progress and Meilisearch destinations — The overview page: every pipeline, its throughput and the health of each Meilisearch instance, updated live.

What it is

meilisearch-cdc is a change data capture (CDC) service for Meilisearch. You connect a database (or a stream, or your own application over HTTP), pick a table, and describe how rows become documents. The service then keeps a Meilisearch index in step with that table: it copies the existing rows once (the snapshot), then follows the database's change log and applies each change.

One binary, one data directory. State (tasks, checkpoints, users, alert history) lives in an embedded bbolt database, cdc.db, in the data directory.
Writes go through the official meilisearch-go SDK.
Everything is managed in the dashboard: sources, Meilisearch destinations, sync tasks, users, alerts and AI access. The same operations are available in the REST API, to AI agents over MCP, and on the server through the admin CLI.

How it works

Each task runs a small pipeline:

Open and validate. The source connects and checks the server's prerequisites (for example wal_level=logical on PostgreSQL or binlog_format=ROW on MySQL). Problems that retrying cannot fix fail the task with a message that says what to change.
Capture the position, then snapshot. The current source position (an LSN, binlog coordinates, a resume token…) is recorded before the copy starts, then every existing row is read in chunks and written to Meilisearch.
Stream. When the snapshot is done, streaming starts from the position captured before it, so changes made during the copy are replayed and nothing falls into a gap.
Checkpoint after confirmation. A position is saved only after Meilisearch confirms the batch that contains it. A crash, even kill -9, replays from the last checkpoint.

At-least-once delivery with idempotent writes

Because the checkpoint trails the confirmed writes, some changes can be delivered twice after a restart. That is harmless: each document is addressed by its primary key, so writing the same row again leaves the index in the same state. Changes to the same document inside one batch are coalesced, so only the final state is sent.

When something goes wrong

Transient errors (network, Meilisearch 5xx or 429, a full task queue) are retried with exponential backoff and jitter. If the pipeline itself fails, a supervisor restarts it with a backoff from 1 s up to 1 minute and the task shows retrying.
A payload that is too large is split in two and retried.
Documents Meilisearch rejects (an invalid id, a malformed _geo or vector…) are isolated by bisecting the batch; the rest is applied and the offenders go to the dead letter queue.
A lost source position (a purged binlog, a dropped replication slot, an expired stream shard) triggers an automatic full resync.
Safety guards hold the task (state held) instead of deleting a large share of the index or applying a TRUNCATE, until an operator decides. See safety guards.

Concepts

Concept	What it is
Connector	A saved source connection: the source type and its credentials, encrypted at rest. It can be tested, and its tables, collections, topics or streams can be browsed. Many tasks can reuse one connector. See Sources and connectors.
Destination	A named Meilisearch instance: URL, API key, gzip, request timeout and a background health check every 5 s to 1 h. Its health, the tasks writing to it and the last sync time update live. See Destinations.
Task	Connector + table → destination + index. A task defines the column mapping, the index settings, batching, retries and safety guards. One table can feed several instances through several tasks. See Create a task.
Index	The Meilisearch index a task writes to. The task creates it on first write with its primary key field, can manage its settings and reports drift. See Index management.
Checkpoint	The last source position confirmed in Meilisearch, plus the position captured before the snapshot. Resetting it makes the next start copy everything again.

Features

11 kinds of sourcesPostgreSQL, MySQL/MariaDB, MongoDB, DynamoDB, CouchDB, SQL Server, CockroachDB, Kafka (Debezium), Redis Streams, SQL polling and an HTTP webhook. Many Meilisearch instancesAny number of destinations, health checked in the background, or a single instance pinned with MEILI_URL. MappingInclude, exclude and rename columns, composite keys, soft deletes, _geo, time formats and static fields. Index managementEvery Meilisearch setting, drift detection, one-click apply, swap, compaction, search playground and documents browser. Zero-downtime resyncRebuild into a shadow index and swap it in, so search never goes empty. Data qualitySchema check, document-level diff with repair, and a dead letter queue with replay and discard. AlertsTask state, lag, dead letters, error bursts, stalled snapshots and Meilisearch down, by email, Telegram or webhook. Team and securityViewer, moderator and admin roles, invitations, sessions with CSRF protection, audit log, AES-256-GCM secrets. AI agentsA Model Context Protocol server with role-scoped tokens, so assistants can inspect and operate pipelines. ObservabilityPrometheus metrics, a live dashboard over Server-Sent Events, structured logs and optional pprof. Operator CLIRecover accounts, transfer ownership, sign everyone out and purge stored data from the server. GitOpsDeclare tasks in a YAML file applied at startup, and import or export tasks as JSON.

Where to go next

New here? Follow the quick start: you will have a table syncing in about five minutes.
Running it for real? Read Install the binary or Docker, then Reverse proxy and TLS and Backups.
Connecting a database? Open its page under Sources for the exact settings and grants.