Chronos/DBWaitlist

Gateway

Postgres, MySQL, MariaDB, MongoDB

What works beside each database, what each needs, and what is not there yet.

Self-hostedChronos Gateway runs on your own servers today. Releases and install script. The engine under it: Chronos DB, self-hosted

What is the same everywhere

The gateway works beside Postgres, MySQL, MariaDB and MongoDB. The URL says which. This page is for gateway 0.4.4 on Chronos DB (the engine) 0.6.2.

  • The same connection check, attach, runs, rules, approvals, webhooks and undo.
  • A world per run, holding one tenant’s rows (documents, beside MongoDB).
  • Agents write the same SQL whatever the database: the engine’s, in Postgres’s dialect.
  • A merge is written to the database first, in one transaction, with every row it writes compared with the database. If one changed meanwhile, the merge comes back as a conflict and nothing is written.
  • Each merge is recorded in a table of the gateway’s own in the database, so a merge whose outcome was lost in a crash is settled from it: it either happened whole or not at all.
  • The gateway’s role has rights on the attached tables and its own record tables, and nothing more. See Connect a database.

The four, side by side

PostgresMySQLMariaDBMongoDB
URLpostgres://mysql://mariadb://mongodb://, mongodb+srv://
Versions tested12 to 188.0, 8.410.5, 115.0, 7.0
Oldest accepted12 (11 or older refused)8.010.55.0
Serverthe primary: merges must write to itMySQL 8.0 or laterMariaDB 10.5 or latera replica set, one member is enough; not standalone, not sharded
What attachestables with a primary key, or a unique index on NOT NULL columnsInnoDB tables with a primary keyInnoDB tables with a primary keycollections, by _id
Checked merge, one transactionyes: rows locked and comparedyes: rows locked (FOR UPDATE) and comparedyesyes: documents compared, only changed fields sent
Conflict check and settlingyesyesyesyes
Reads check (check_reads)yesyesyesyes
Dry run (merge_preview)yesyesyesyes
Undo, 30 daysyes; cascades namedyes; cascades not knownyes; cascades not knownyes; no cascades to hold for
GATEWAY_FOLLOWyes: a logical replication slotnot yetnot yetyes: change streams
Refresh on a timeryesyesyesyes
act_as (write as your end user)yesnot yetnot yetnot yet
New rows in numbered columnsids from Postgres’s own sequenceprovisional ids (negative) until the mergeprovisional ids (negative) until the merge_id is a new ObjectId
Generated columnsattached, never writtenattached, never writtenattached, never writtennone
Masksany columnany columnany columnonly a field kept as a column (fields)
Own record tableschronos.merges, chronos.merge_rowschronos_merges, chronos_merge_rowschronos_merges, chronos_merge_rowscollections chronos_merges, chronos_merge_rows
MongoDB’s own tools for a runnononoyes
Managed services triedSupabase, Neonnonenonenone

Postgres

WhatPostgres
Versions12 or newer. 12 to 18 are tested. The connection check refuses 11 or older, saying so: the attach reads catalog columns 12 added.
URLpostgres://user:password@host:5432/database, with sslmode disable, prefer, require, verify-ca or verify-full, and sslrootcert=<file.pem> for a private CA.
PasswordsOn Postgres 12 or 13, run set password_encryption = 'scram-sha-256'; before create role. The engine refuses to send a password as MD5 or in the clear unless the connection is sslmode=verify-full.
PoolerTested through PgBouncer in transaction mode, Supabase’s pooler (session and transaction mode) and Neon’s pooler.
Read replicaThe check warns: the attach reads from it, but merges must write to the primary.

Postgres: what a table must be

  • A key. A primary key, or a unique index on NOT NULL columns to stand for one (no WHERE, no expressions, not deferrable).
  • Not a view. Attach the tables it reads.
  • Not in an inheritance tree (INHERITS): refused.
  • A partitioned table is attached whole, as one table holding its partitions’ rows. The check lists it (partitioned), not its partitions, and Postgres puts each row an agent’s merge writes in its partition. A partition alone is refused.
  • Generated columns are attached. Postgres works them out (the check lists them as generated), and an agent can’t write them.
  • Row-level security (Supabase turns it on for every table): attached when the gateway’s role reads every row. The check’s role_sql gives chronos_gateway a policy that does (USING (true) WITH CHECK (true)), and your app’s policies keep holding everyone else. A table with a restrictive policy for every role is refused.
  • Serial and identity columns take their new values from Postgres’s own sequence, so an id a run gives a row is the id written at the merge. The cost is gaps in the sequence. The role needs USAGE on the sequence, which role_sql grants.

Postgres: what works

FeatureBeside Postgres
MergeOne transaction: each row the merge writes is locked and compared with Postgres, then written, and the merge is recorded in chronos.merges. Values a Postgres trigger or default set come back into main. Triggers stay in Postgres and run as the merge is written.
Conflict checkA row changed in Postgres meanwhile: nothing is written, 409 conflict. Settle with by_columns, resolve or rows: a row where the two sides changed different columns combines.
Reads checkWith check_reads = true (the default rule), what a run read is checked against Postgres inside the merge’s transaction, before anything is written. For a filtered read Postgres is asked only for the rows the conditions can match, however big the table. Only the run’s own tenant’s rows count.
Dry runThe run’s MCP merge_preview compares each row the merge would write with Postgres as it is now, in one read-only transaction with no locks. Triggers aren’t run. Nothing is written.
UndoFor 30 days after the merge, from chronos.merge_rows. The preview’s cascades names the tables Postgres would change rows of besides the run’s own (ON DELETE CASCADE under a row the undo removes). An undo that would cascade is refused (409 cascade) until it says allow_cascade: true.
FollowGATEWAY_FOLLOW=on: main takes Postgres’s changes about a second after they commit, through a logical replication slot. Needs wal_level = logical and a role with REPLICATION.
act_asA run’s merge is written after SET LOCAL ROLE, with your settings (such as request.jwt.claims), so your grants and row-level security judge each write as the end user’s. Once: GRANT authenticated TO <the role the gateway connects as>.
Generated columnsAttached. Never sent by a merge, and never compared.
MasksPUT /v1/masks on any column: hash, null, partial or format. Postgres is never changed.
Schema changesA refresh takes columns added, dropped, renamed or retyped in Postgres, and new enum labels. Until a refresh has taken them, a merge writing to that table is refused and says to refresh.

act_as in detail

POST /v1/runs
{"tenant": {"org_id": 42}, "intent": "clean up leads", "end_user": "u-17", "act_as": {"role": "authenticated", "settings": {"request.jwt.claims": {"sub": "u-17", "role": "authenticated"}}}}
  • The engine locks and compares the rows as its own role, then runs the writes after SET LOCAL ROLE authenticated and set_config(name, value, true) for each setting.
  • A row your policies hide or refuse fails the merge (merge.rejected, code 42501), and nothing is written. It is the same when a person approves the run.
  • Settings must be custom ones (prefix.name). A value that isn’t text is sent as its JSON text. The settings’ values are never shown or logged.
  • A superuser or BYPASSRLS role is refused, since it would judge nothing.
  • The run’s agent keeps its role for the whole run. A new end user is a new run.

Postgres: limits and what is not there

  • A table’s shape is changed in Postgres, not through a run. A change to a key, to row-level security or to a generated column needs a new attach into a new data folder: a refresh leaves such a table as it was and names it (skipped).
  • A read broader than 100,000 rows of the run’s tenant (a range or a whole-table read of a bigger table) can’t be checked against Postgres. The merge is held for a person, saying so. A person can approve with skip_read_check.
  • A merge is limited to 50,000 changed rows by the engine’s default. Every row stays locked until the transaction commits.
  • Each refresh reads the attached tables in full. On big tables, refresh less often, or follow changes.
  • A replication slot keeps WAL while the engine is down. On Postgres 13 or later set max_slot_wal_keep_size.
  • Text sorts by its bytes in a run’s world, so ORDER BY a text column can list rows in another order than a database with a language collation does.
  • A timestamp written without an offset into a timestamptz is read in UTC, not in the database’s own timezone setting.
  • An id typed by hand into a serial or identity column is refused at the merge.

Postgres: managed services

ServiceState
SupabaseTested (Postgres 17), through its pooler in session and transaction mode. Row-level security is on for every table there: use the policy from role_sql. Logical replication is on, for GATEWAY_FOLLOW.
NeonTested, both straight to the database and through its pooler, and waking from a suspend. The connection check takes the connection string its console gives (channel binding). For GATEWAY_FOLLOW, turn on logical replication in the project’s settings.
RDS, Aurora, Cloud SQLNot listed as tested. The check’s follow says what following needs there: RDS, rds.logical_replication = 1 and GRANT rds_replication; Cloud SQL, cloudsql.logical_decoding = on.

The engine keeps one connection to Postgres between merges and closes it after 5 minutes unused, so Neon or Supabase can scale to zero.

MySQL

WhatMySQL
Versions8.0 or later. 8.0 and 8.4 are tested. Older is refused by the check, saying so.
URLmysql://user:password@host:3306/database, with ssl-mode DISABLED, PREFERRED (the default), REQUIRED, VERIFY_CA or VERIFY_IDENTITY, and ssl-ca=<file.pem>.
Loginscaching_sha2_password (MySQL 8’s default) and mysql_native_password. A login that needs the password itself is only sent over TLS.
SchemaThe URL’s database. The check answers source: "mysql" and flavor: "mysql".
TestedRun locally in containers. Not against a managed service.

MySQL: what a table must be

  • InnoDB. A table of another engine (MyISAM) is refused.
  • A primary key. A table without one is refused.
  • Not a view. Attach the tables it reads.
  • No binary, BIT or spatial columns. binary, varbinary, the blob types, bit and spatial types are refused, each named with the reason. Not attached from MySQL yet.
  • Types that attach: the integer types, year, decimal, float, double, char, varchar, the text types, enum, set, time, date, datetime, timestamp and json. datetime and timestamp are read and written in UTC.
  • Defaults. A constant default or CURRENT_TIMESTAMP comes over, so a row added in a run holds the value MySQL would give. A default that is another expression (DEFAULT (uuid())) is MySQL’s to work out: the column is NULL in the run’s world, and the merge writes DEFAULT there.

MySQL: what works

FeatureBeside MySQL
MergeOne InnoDB transaction. Every row the merge writes is read FOR UPDATE by key and compared with main’s copy, by type: 1.5 and 1.50, or two spellings of the same JSON, are the same value. Then the writes, and the merge’s row in chronos_merges. The session runs at READ COMMITTED with STRICT_ALL_TABLES, so a value MySQL would cut or change is an error.
Conflict checkA row MySQL changed meanwhile: a conflict, nothing written. Settled as beside Postgres.
Reads checkWith check_reads, a row a run read that changed in MySQL since, or a row added there that its read would have found, holds the merge. One difference from Postgres: a table read by a filtered scan (where status = 'new') is read whole from MySQL to check it, for the run’s tenant. Past 100,000 rows the read is too broad to check, and a person decides.
Dry runCompares each row the merge would write with MySQL’s, in one snapshot with no locks, and checks the run’s reads. It names the triggers on the tables it would write; they aren’t run.
UndoFor 30 days, from chronos_merge_rows. A row the merge added goes under the id MySQL gave it; a row it deleted comes back with its old id. MySQL doesn’t say what its cascades and triggers wrote, so an undo isn’t held for them and the preview’s cascades is null. Check ON DELETE CASCADE foreign keys yourself before undoing an insert.
AUTO_INCREMENTRuns add rows, with a provisional id until the merge. See below.
Generated columnsAttached (AS (...) STORED or VIRTUAL), listed as generated. Only MySQL gives them values: a run reads them, a merge never writes them.
MasksPUT /v1/masks on any attached column. MySQL is never changed.
RefreshOn the timer (GATEWAY_REFRESH_EVERY) or POST /v1/refresh: each table read whole in one snapshot.

AUTO_INCREMENT and provisional ids

MySQL gives an AUTO_INCREMENT column its value when the row is inserted, and no values can be reserved ahead. So a row a run adds gets a provisional id: a negative number, from -1,000,000,001 down, that no row of MySQL’s has. Leave the column out of the INSERT, as you would in MySQL.

SQL, in a run
insert into orders (customer) values ('ada');          -- id is -1000000001 in this worldinsert into order_lines (order_id, sku) values (-1000000001, 'x');

At the merge the row is inserted without the id, MySQL gives its own, and that id is written wherever the provisional one stood: the row itself, and every row of the merge that refers to it through a foreign key MySQL declares. Parents are inserted before their children. After the merge no provisional id is left anywhere.

  • The id an agent saw in its world isn’t the row’s id after the merge. Read the row again by something else it holds (the order’s reference, the customer and time) to learn it.
  • A provisional id in a column with no declared foreign key to the new row’s table is refused, and nothing is written. Declare the foreign key in MySQL and attach again, or merge the parent first and write its real id in a second run.
  • An id given by hand (insert into orders (id, ...) values (900, ...)) is refused.
  • New rows that refer to each other in a circle are refused: merge them in two steps.
  • A table whose AUTO_INCREMENT column is narrower than INT, or is BIGINT UNSIGNED, takes no inserts from runs: no provisional id fits it. Updates and deletes work. The check says inserts: false for it, and warns.
  • Each new row is its own INSERT, so a merge of many new rows sends more SQL than one of updates.

MySQL: not there yet

  • Binary columns (and BIT and spatial ones): a table with one is refused.
  • Writing as your end user (act_as): Postgres only.
  • Taking changes as they commit (GATEWAY_FOLLOW). The gateway refreshes on a timer. The check’s follow says ready: false.
  • Cascades in an undo preview: MySQL can’t say, so cascades is null.
  • Columns changed in MySQL don’t come over by a refresh: the table is left as it was, and the refresh says to attach again.
  • In the engine, also refused with a message that says so: rehearsals of a merge, merge checks run in the database itself, and loading a tenant at a time.
  • Managed services (RDS, Aurora): not tried.

The check says each of these per table or as a warning, so nobody learns it from a refused merge.

MariaDB

MariaDB works as MySQL does: the same check, the same role statements, the same merge, and the same limits. What differs:

WhatMariaDB
Versions10.5 or later. 10.5 and 11 are tested. Older is refused by the check, saying so.
URLmariadb://user:password@host:3306/database. A mysql:// URL to a MariaDB server works too: the check reads the server’s version and answers flavor: "mariadb".
What a table must beAs for MySQL: InnoDB, a primary key, no binary, BIT or spatial columns, not a view.
What worksAs for MySQL: merge, conflict check, reads check, dry run, undo for 30 days, AUTO_INCREMENT provisional ids, generated columns, masks, refresh on the timer.
Not there yetAs for MySQL: binary columns, act_as, GATEWAY_FOLLOW, cascades in an undo preview.
TestedRun locally in containers. Not against a managed service.

MongoDB

WhatMongoDB
Versions5.0 or later. 5.0 and 7.0 are tested. Older is refused by the check, saying so.
TopologyA replica set: MongoDB has transactions only on one, and a merge must be written all or nothing. One member is enough (mongod --replSet rs0, then rs.initiate()). A standalone server is refused. A sharded cluster (a mongos) is refused for now.
URLMongoDB’s own connection string, mongodb:// or mongodb+srv://. It must name the database: its collections are the ones attached.
EngineNeeds an engine built with MongoDB. The released binaries have it, from 0.5.0.
TestedRun locally in containers. Not against Atlas.

MongoDB: what a collection must be

  • An ordinary collection. Views, time-series collections (their documents can’t be changed one by one) and capped collections (their documents can’t be deleted or grow) are refused.
  • Documents of 4 MB or less. A bigger one is refused at the attach.
  • Named fields of one type. A field named in fields holds one type throughout the collection: string, int, long or ObjectId. A field of mixed types is refused. Documents without it have NULL.
  • Field names. One with a dot or a leading $ can’t be written by a merge.

A collection is attached as a table, a document as a row:

ColumnHolds
_idthe document’s _id: an ObjectId as its 24 hex digits, any other id as JSON ("abc", 7)
one per name in fieldsthat top-level field, as a column of its own. The tenant’s field is added to them for you.
docthe rest of the document, as jsonb
SQL, in a run
select doc->>'name' from customers where org_id = 42;update customers set doc = jsonb_set(doc, '{owner}', '"ada"') where _id = '65f1a2b3c4d5e6f708192a3b';insert into customers (org_id, doc) values (42, '{"name": "NewCo"}');   -- _id is a new ObjectIddelete from customers where _id = '"lead-2"';                            -- a string id, with its quotes

Values are MongoDB’s relaxed Extended JSON: an ObjectId inside doc is {"$oid": "..."}, a date {"$date": "2026-10-01T10:00:00Z"}, a Decimal128 {"$numberDecimal": "1.50"}. Numbers are plain.

MongoDB: what works

FeatureBeside MongoDB
MergeOne multi-document transaction. Every document the merge writes is read and compared with main’s copy; numbers compare by value and objects whatever their fields’ order. An update sends only the fields that changed, as $set and $unset by path, never the whole document: the fields it leaves keep their order and their types. The merge is recorded in chronos_merges.
Conflict checkAny difference is a conflict: nothing is written, and it is settled as any conflict. The console shows its rows to settle, as beside Postgres.
Reads checkWith check_reads, a document a run read that MongoDB changed since, or one added there that its read would have found, holds the merge. A read by _id is checked by that document alone. A read with a condition on a field kept as a column is checked by the documents the condition can match. A read with a condition on a field inside doc counts as a read of the whole collection. A collection read whole is read whole from MongoDB, 100,000 documents at most; past that the merge is held for a person.
Dry runReads MongoDB in one snapshot: each document the merge would write is compared with MongoDB’s, and nothing is written or locked.
UndoFor 30 days, from the collection chronos_merge_rows, which keeps the documents each merge wrote, before and after. MongoDB has no cascades to hold an undo for.
FollowGATEWAY_FOLLOW=on (engine 0.5.1 or later): a change stream on each attached collection. Main takes just the documents that changed, a moment after they change. The role needs changeStream on the attached collections.
MongoDB’s own toolsA run has find, count, insert, update_one, update_many, delete_one, delete_many, over MCP (mongo_find and so on) and POST /v1/runs/:id/mongo, as well as SQL. Each becomes SQL in the run’s world. Filters take $regex (with $options: "i") and compare dates. See MongoDB tools.
MasksOn a field kept as a column only: name it in fields at the attach.
Changes in wordsBy field path: “Change the address.city of lead “Acme” from Pune to Mumbai”. Labels name fields by path.

Numbers and arrays

  • A number written to a field that already holds one keeps that field’s type: a double stays a double when you write 9, a long stays a long.
  • In a new field, a whole number is an int (a long past 32 bits), and a number with a fraction part is a double.
  • To write another type, write its Extended JSON: {"$numberLong": "5"}, {"$numberDecimal": "1.50"}, {"$date": "..."}, {"$oid": "..."}.
  • An array is one value. A change to an array writes the whole array, so two changes to the same array are a conflict even when they touch different elements.

MongoDB: not there yet

  • Standalone servers and sharded clusters.
  • Writing as your end user (act_as): Postgres only.
  • Masks on a field that isn’t a column.
  • In the tools: aggregate, $elemMatch, $not, upserts, replacing a whole document, and changing one element of an array (no positional paths, no $each). Each is refused by name.
  • Regular expressions beyond POSIX: $regex patterns are POSIX regular expressions. What MongoDB’s PCRE has beyond that (lookarounds, backreferences) isn’t matched. The only option is i.
  • In the engine, also refused with a message that says so: rehearsals of a merge, merge checks run in the database itself, and loading a tenant at a time.
  • Atlas: not tried.

Managed services, tried and not tried

ServiceState
Supabase (Postgres)Tested, through its pooler.
Neon (Postgres)Tested, pooled and direct.
Postgres 12 to 18, self-runTested, with TLS verify-full and through PgBouncer in transaction mode.
MySQL 8.0 and 8.4, in containersTested.
MariaDB 10.5 and 11, in containersTested.
MongoDB 5.0 and 7.0, a replica set in containersTested.
RDS and Aurora for MySQL or MariaDBNot tried.
MongoDB AtlasNot tried. Atlas is a replica set, which is what the engine needs.
Postgres, MySQL, MariaDB and MongoDB with Chronos Gateway · Chronos