Operations¶

This page covers write visibility (batch commit), reindexing, CDC ingestion, replication, observability SQL interfaces, and runtime settings (GUCs) for AkasicDB text search.

Enabling Background Workers¶

The batch-commit, CDC consumer, reindex, and shipping puller workers use background workers and shared memory, so they must be preloaded at postmaster startup. AkasicDB distributions include texton in shared_preload_libraries by default, so no extra configuration is needed.

shared_preload_libraries = 'akasicdb, graphon, vectoron, texton'

In environments where you build it yourself or adjust the preload list, confirm that texton is included and restart the server.

Note

Without preload, USING texton indexes and search functions still work, but background worker features such as automatic batch commit require preload.

Batch Commit & Forced Commit¶

INSERTs are staged into a batch buffer without holding the tantivy write lock, and a background worker commits them in batches. This reduces write-lock contention, but a row you just inserted may not be immediately visible to search. When read-your-writes visibility is required, use akasicdb.text_flush() to commit the pending batch immediately.

INSERT INTO docs (title, body) VALUES ('도쿄 여행', '국제공항에서 출발');
SELECT akasicdb.text_flush('docs_texton_idx');   -- commit the pending batch immediately

Deleted rows are cleaned from the index at VACUUM time.

CDC Ingestion (optional)¶

Enabling logical-decoding-based CDC ingestion applies committed row changes to the index through a background consumer. It requires wal_level = logical and a replication slot.

# postgresql.conf
wal_level = logical                 # postmaster context - requires a server restart
texton.enable_cdc_ingestion = on    # SIGHUP context - requires a reload

texton.enable_cdc_ingestion is a SIGHUP-context parameter, so it cannot be turned on with a session SET (that fails with ERROR: parameter "texton.enable_cdc_ingestion" cannot be changed now). Set it in postgresql.conf and reload the configuration.

SELECT pg_reload_conf();

If you changed wal_level in the same edit, restart the server instead — a reload does not apply it.

For an index with CDC enabled, akasicdb.text_flush() catch-up guarantees read-your-writes.

Reindex¶

To rebuild an index, use the standard REINDEX.

REINDEX INDEX docs_texton_idx;

Note

The engine also supports a non-blocking online reindex (atomic generation swap after a background rebuild) for CDC-enabled indexes, but it is not yet exposed through the akasicdb text-search interface. Use REINDEX INDEX for now.

Replication & Node Role¶

AkasicDB text search supports generation-based atomic index swaps and primary→replica segment shipping. The replica's puller worker polls the primary's watermark and reconstructs segments. Check the current node role with akasicdb.text_node_role() (callable only by members of pg_monitor).

SELECT akasicdb.text_node_role();   -- 'primary' or 'standby'

Observability¶

Four read-only Set-Returning Functions (SRFs) expose slot lag, index state, and segment statistics. They are callable only by members of the pg_monitor role.

SELECT * FROM akasicdb.text_slot_status();                -- replication slot LSN / lag
SELECT * FROM akasicdb.text_index_lag();                  -- per-index apply cursor lag, bootstrap progress
SELECT * FROM akasicdb.text_index_stats();                -- per-index segment / document count
SELECT * FROM akasicdb.text_segments('docs_texton_idx');  -- per-segment document count

Function	Returns
`akasicdb.text_slot_status()`	Replication slot LSN and lag
`akasicdb.text_index_lag()`	Per-index apply cursor lag and bootstrap progress
`akasicdb.text_index_stats()`	Per-index segment and document count
`akasicdb.text_segments(regclass)`	Per-segment document count

Settings (GUCs)¶

Runtime behavior is tuned with the GUCs below. The scope at which a value applies varies by parameter (session SET, postgresql.conf reload, and so on); which context each parameter belongs to is listed in Configuration.

GUC	Default	Description
`texton.dictionary_base_dir`	`''`	Dictionary path allowlist directory. When set, only paths under this directory are allowed as user dictionaries.
`texton.search_num_threads`	`0`	Number of segment threads for a search scan (`0`=auto, `1`=single).
`texton.resolve_pk_to_ctid`	`off`	Re-resolves a matched document's PK to its current ctid across multiple nodes.
`texton.enable_cdc_ingestion`	`off`	Enables CDC (logical decoding) ingestion (requires `wal_level=logical`).
`texton.cdc_poll_interval_ms`	`200`	CDC consumer poll interval (ms).
`texton.cdc_flush_timeout_ms`	`5000`	Timeout for `flush()` catch-up when CDC is enabled (ms).
`texton.recovery_max_rate`	`40`	Write throughput cap for recovery, bootstrap, and reindex (MB/s; `0`=unlimited).
`texton.old_generation_retention`	`60`	GC grace for swapped-out index generations (s; `0`=immediate).
`texton.shipping_poll_interval`	`1000`	Watermark poll interval of the replica puller worker (ms).
`texton.shipping_max_rate`	`40`	Segment shipping throughput cap (MB/s, primary send side; `0`=unlimited).
`texton.bgworker_database`	`postgres`	Database the batch-commit background worker connects to.
`texton.build_num_threads`	`1`	Number of writer threads for bulk build, batch commit, and delete cleanup.
`texton.writer_heap_bytes`	`50000000`	tantivy writer heap budget (bytes, across all threads).
`texton.build_merge`	`auto`	Bulk build merge policy (`auto` / `deferred`).
`texton.commit_batch_size`	`8192`	Soft commit threshold of the write batch buffer (item count).
`texton.staleness_alert_seconds`	`60`	Alert threshold for CDC apply lag (s). Lag above this value is reported as stale on the observability surface.
`texton.free_space_alert_mb`	`512`	Alert threshold for free space on the index filesystem (MiB). Free space below this value is reported as low on the observability surface.

Behavior Notes¶

Index storage location: Each index's tantivy data is stored under $PGDATA/texton/<index_oid>/ (not WAL-logged). If it is corrupted by a crash or similar, rebuild it with REINDEX.
Crash recovery: After a crash, resume bootstrap continues indexing, throttled by texton.recovery_max_rate.
Korean dictionary: The default ko-dic main dictionary is embedded in the extension binary and needs no separate deployment. Only user dictionaries are added via external paths (see Tokenization).