Release notes for 2.9.4 ask users to add a `modes` column that no shipped data layer reads or writes

[dokterbob]

Summary

The 2.9.4 release notes flag a breaking change and instruct persistence users to run:

ALTER TABLE steps ADD COLUMN IF NOT EXISTS modes JSONB;

(https://github.com/Chainlit/chainlit/releases/tag/2.9.4, pointing to #2734.)

After applying this against a real project it became clear that the guidance is doubly inconsistent:

1. No data-layer code reads or writes the column. PR feat: Add Modes #2734 only adds modes to the in-memory Step / Message dataclasses and the emitter that pushes mode metadata to the UI. It does not touch backend/chainlit/data/chainlit_data_layer.py or backend/chainlit/data/sql_alchemy.py. Verified on 2.11.0: grep modes on both files returns zero hits. The create_step upsert in ChainlitDataLayer still enumerates exactly: id, threadId, parentId, input, metadata, name, output, type, startTime, endTime, showInput, isError. _convert_step_row_to_dict never populates modes from the row. So even if a user adds the column, nothing is ever stored there.

2. The table name is wrong for ChainlitDataLayer users. The SQL uses unquoted lowercase steps, which only matches SQLAlchemyDataLayer. The ChainlitDataLayer (which the companion chainlit-datalayer project bootstraps via Prisma) uses quoted PascalCase identifiers — "Step", "Thread", "Element", "Feedback", "User". Running the release-notes SQL against a ChainlitDataLayer database fails with relation "steps" does not exist.

3. Chainlit/chainlit-datalayer's prisma schema has not been updated to add a modes field to the Step model. A schema bootstrapped from that repo will not have the column either, and there is no migration that introduces it. The chainlit-datalayer repo appears unmaintained (last migration 20250108095538_add_tags_to_thread), which compounds the confusion.

Steps to reproduce

1. Bootstrap a Postgres schema from Chainlit/chainlit-datalayer (Prisma). The Step table is created as "Step" with the 13 prisma-defined columns.
2. Upgrade Chainlit to 2.9.4 (or later; 2.11.0 still shows the same behaviour).
3. Follow the release notes: ALTER TABLE steps ADD COLUMN IF NOT EXISTS modes JSONB;
4. Observe: ERROR: relation "steps" does not exist.
5. Fix the table name manually: ALTER TABLE "Step" ADD COLUMN IF NOT EXISTS modes JSONB;
6. Use the mode API (cl.Message(..., modes={...}), emitter.set_modes), observe the UI works, then inspect the database. SELECT modes FROM "Step" is always NULL — the data layer never writes to it.

Expected

Either:

• The release notes accurately reflect what is actually required (which, for ChainlitDataLayer users on the current codebase, is nothing), or
• ChainlitDataLayer.create_step and _convert_step_row_to_dict are updated to persist/read modes, the chainlit-datalayer prisma schema is updated to include modes Json?, and the release-notes SQL is corrected to target the right identifier ("Step" quoted, or added via a prisma migration that targets the correct table name).

Versions checked

• chainlit==2.11.0 (also reviewed the 2.9.4 release notes / PR feat: Add Modes #2734 diff).
• chainlit-datalayer main prisma schema, fetched live: no modes.

Related

• feat: Add Modes #2734 (feat: Add Modes)
• https://github.com/Chainlit/chainlit/releases/tag/2.9.4
• https://github.com/Chainlit/chainlit-datalayer

[github-actions]

This issue is stale because it has been open for 14 days with no activity.