Keep an index in step with PostgreSQL.

How change tracking works

There are no triggers and no replication slots. A worker asks your database a question on a timer: which rows have a cursor value beyond the last one I saw?

1. Each started job has its own worker, which polls every poll_interval.
2. The poll is SELECT … WHERE cursor_column > last_cursor ORDER BY cursor_column LIMIT batch_size. A custom query is wrapped as a subquery and filtered the same way. The first poll has no cursor and reads from the start.
3. Each row becomes a document. The id column becomes _id; the cursor column is used for tracking and is not added to the document; NULL values are skipped; every other column is indexed with a type inferred from its PostgreSQL type.
4. The documents are sent to the search engine in one bulk request, and the cursor and the running total are saved after the batch succeeds.
5. If the batch was full, the worker polls again at once to catch up. Otherwise it waits for the next interval.
6. After 10 consecutive errors the worker stops itself and the job’s status becomes error. When the service restarts, jobs that were running are started again from their saved cursor.

What the cursor can and cannot see

• Inserts and updates are picked up when the row’s cursor value moves beyond the saved one. An updated_at column that is set on every change works; an id column sees new rows only. The row is re-indexed under the same id, so the old version is replaced.
• Deletes are not seen by polling, because a deleted row leaves nothing to read. A full resync removes them from the index.
• Choose a column that only increases. A cursor that can move backward will miss changes.

Connect a data source

A data source is a PostgreSQL connection. Bolt Search connects to the host and port you give it, so the database must be reachable from the hosted service. Add one in the console under Data Sources, or with the API.

curl -X POST https://api.boltsearch.app/v1/_sync/datasources \
  -H 'Authorization: ApiKey bsk_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "production-db",
    "host": "db.example.com",
    "port": 5432,
    "database": "myapp",
    "username": "readonly",
    "password": "••••••••",
    "ssl_mode": "require"
  }'

HTTP 201
{
  "id": "a1b2c3d4-…",
  "name": "production-db",
  "host": "db.example.com",
  "port": 5432,
  "database": "myapp",
  "username": "readonly",
  "ssl_mode": "require",
  "max_conns": 5
}

• Test checks the connection with a five-second ping: POST /v1/_sync/datasources/{id}/_test.
• You can list, read, update and delete data sources. A data source that a sync job uses cannot be deleted.
• The password is never returned by the API or shown in the console again.

Create a sync job

A job says what to read, how to identify and track rows, and which index receives them.

curl -X POST https://api.boltsearch.app/v1/_sync/jobs \
  -H 'Authorization: ApiKey bsk_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "sync-articles",
    "data_source_id": "a1b2c3d4-…",
    "source_table": "articles",
    "cursor_column": "updated_at",
    "id_column": "id",
    "target_index": "articles",
    "poll_interval": "30s",
    "batch_size": 1000
  }'

HTTP 201
{
  "id": "…",
  "name": "sync-articles",
  "status": "stopped",
  …
}

Custom queries

Use custom_query instead of a table for joins and computed columns. Every column in the result is indexed.

curl -X POST https://api.boltsearch.app/v1/_sync/jobs \
  -H 'Authorization: ApiKey bsk_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "sync-enriched-articles",
    "data_source_id": "a1b2c3d4-…",
    "custom_query": "SELECT a.id, a.title, a.body, c.name AS category FROM articles a JOIN categories c ON a.category_id = c.id",
    "cursor_column": "id",
    "id_column": "id",
    "target_index": "articles",
    "poll_interval": "1m",
    "batch_size": 500
  }'

• It must start with SELECT.
• It must not contain semicolons, -- or /* */ comments, $$ dollar-quoting, or the keywords DROP, ALTER, CREATE, TRUNCATE, INSERT, UPDATE, DELETE, GRANT or REVOKE followed by a space.
• The cursor and id columns must be in the result.

Target index

• Give the logical name only, such as articles; the project prefix is handled for you.
• If the index does not exist when the job starts, it is created with every column indexed. Create it yourself first if you want different mappings, for example to make a column a keyword.
• Text columns also get a companion field named column.keyword with the exact value, for exact-match queries.
• Several jobs may write to the same index; each job writes to exactly one.

How column types map

Run and monitor a job

curl https://api.boltsearch.app/v1/_sync/jobs/{id}/_state \
  -H 'Authorization: ApiKey bsk_YOUR_API_KEY'

HTTP 200
{
  "last_cursor_value": "2026-02-21T10:05:00Z",
  "total_docs_synced": 4523,
  "last_sync_at": "2026-02-21T10:05:30Z",
  "consecutive_errors": 0
}

Starting, stopping, resetting and resyncing are also buttons on the Sync Jobs page, shown according to the job’s status. Sync endpoints need the editor role; reading state, logs and history needs viewer.

Full resync

A full resync is the way to remove rows that were deleted at the source. The live index keeps serving searches while it runs, and it only changes when the new index is complete.

Start it

Set resync_schedule for a scheduled resync, or use the Full resync button or POST /v1/_sync/jobs/{id}/_resync for a manual one. Both follow the same steps.

Shadow index

The worker syncs every row, from the beginning, into a shadow index. Its name is the index name, then .resync-, then the first 8 characters of the job id, for example articles.resync-7c1e90ab.

Check

When it is synced, the document count is compared with the live index. If the count fell by more than 20% or any error occurred, the resync is aborted: the shadow index is deleted and the live index and the saved cursor stay as they were.

Swap

Otherwise the shadow index replaces the live index in one step and the old index is discarded. If the server restarts during a resync, the history row is marked failed and the shadow index is deleted at startup.

Every resync is recorded in the resync history with a trigger type (scheduled or manual), an outcome (in_progress, success, aborted or failed) and the document counts before and after.

Sync API summary

Sync endpoints are not metered. Data sources and jobs belong to the project of the key; another project’s ids answer 404.

Webhooks

A webhook posts a sync-job event to a URL you choose. Create one with POST /v1/_sync/webhooks.

• Each request carries X-Bolt-Signature: t=,v1=, where the value is the hex HMAC-SHA256 of "t.body" (the timestamp, a dot, then the raw body) with the webhook secret as the key.
• A delivery that does not get a 2xx response is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then marked failed.