Repository navigation
A column your sources file leaves out is no longer served under another name, after a rename or a swap on your
database. A table synced whole is no longer served with rows missing until its catch-up. A sync that waits for an
open transaction on your database now says Waiting, not Failed. A WITH query named like the table it reads now gives
Postgres's answer, and TABLESAMPLE is refused by name. A grouped min() or max() of a text over few groups, a
sorted SELECT DISTINCT and mode() are many times faster under a libc collation, and so is to_char with a quarter
or a padded name. The web page shows how to connect an MCP client. This is a new release line, so every project's
pin moves. No table is read again. Syncing a column the sources file left out now takes mason add. A script that
reads --json or the events for a sync that waits may need to change ("Before you upgrade").
Before you upgrade
- No table is read again. At the first start, Mason records which column is which on your database. It reads no
table's data again. - Move the pin:
version: 0.23.0inmason/mason.yml. The 0.23.0 command and image refuse a project pinned to
0.22.x, and say how to fix it. A 0.22.x command or image refuses a project pinned to 0.23.0. So set the pin and
start 0.23.0 in the same step, once everyone and everything that runs the project has 0.23.0. - The 0.22 line still gets security fixes. They are released as 0.22.x patches, from the
release/0.22branch. A
project pinned to 0.22.0 can stay on that line until you are ready to move. - To sync a column the sources file left out, run
mason add. Mason now knows each column by its identity on your
database, not by its name alone ("What was wrong and is now right"). A column the file left out is synced again
only once you confirm it. This covers a column thatexclude:names, one acolumns:entry does not list, and a
secret-looking columnmason addleft out.- Before, you could take a name out of
exclude:or add it tocolumns:by hand, and Mason synced the column. Now
Mason holds that table instead. It stops syncing the table, and keeps serving the data it holds.
The table's line inmason statusand on the web page says why. - To sync the column, run the
mason add <table> --columns …line that the table's line gives. It names every
column to sync. A plainmason add <table>would leave secret-looking columns out again. You can also remove the
table's entry and add it back. - A script or CI job that edits the sources file to sync such a column must run that command instead.
- In a project deployed read-only (
MASON_PROJECT_READONLY=1), the committed file still syncs a column as it says,
if the column did not move on your database. A column that moved is held, such as one that was renamed. To sync
it, take the entry out of the committed file and start Mason. Then put it back and start Mason again. The table is
read again whole, and is not served from the first start until that sync ends. - Nothing is held at the first start. Mason records which column is which as it takes the columns by name.
- Before, you could take a name out of
- Check any script or alert that reads
mason status --json,mason wait --jsonor the events for a sync that
waits for an open transaction on your database ("What changes" has each):- The wait is no longer the table's
error. Itssync.stateiswaiting, notfailed, and a newsyncWaits
giveswhyandcheckedAt. - Its event is now
sync_waits, which is not a failure. Before, it wasfull_sync_failed.full_sync_failedis
still sent when a whole sync fails. mason waitkeeps waiting for a first sync that waits, within its--timeout. Before, it exited 1.
- The wait is no longer the table's
What changes
- A sync that waits for an open transaction on your database now reads as waiting, never as failed. Mason waits
when a table was rewritten after a transaction that is still open began. It checks again every 30 seconds and goes
on by itself.mason statusand the web page now say Waiting, with the transaction the sync waits for. Before, they said
Failed.mason waitkeeps waiting for a first sync that waits, within its--timeout. Before, it exited 1, so
mason add <table> && mason waitread the wait as a failure. A table synced before is served meanwhile, so
mason waitis ready for it.- In
mason status --jsonandmason wait --json, the wait is no longer the table'serror, and itssync.state
iswaiting. A newsyncWaitssays why, and when Mason last checked. If a script or an alert looks forfailed
to catch this case, it no longer matches. Another error on the table, such as its stream's, is still said. - The event is now
sync_waits, and it is not a failure. Before, it wasfull_sync_failed. - The message names the transaction and its pid only while that transaction is still open. Before, it could name
one that had already ended, whose pid may belong to another session by then.
- You can see, before you upgrade, which synced tables the new release reads again whole. Run
npx @mason-data/cli@<version> upgrade --checkin the project's folder while Mason runs, with the version you are
upgrading to. It lists each table that release's first start reads again from your database, why, how large it is,
and whether it keeps serving its synced data until its new sync is done. It changes nothing.--jsongives the same
as data.- It works only for an upgrade from this release or a later one. An older Mason does not say what its synced data
holds, and the command says so. For an upgrade from 0.22.0 or before, read each release's "Before you upgrade".
- It works only for an upgrade from this release or a later one. An older Mason does not say what its synced data
- A grouped
min()ormax()of atextorvarchar, and aSELECT DISTINCTsorted by one, are faster under a
libc collation, such as a database whose collation isen_US.utf8. Over 4.5 M rows, the min and max of names by
region took 29 s and now take about 3 s, against Postgres's 0.4 s. The distinct values of a code column, sorted, took
13 s and now take 0.2 s, about Postgres's time. The answers are Postgres's, as before. Sixteen such queries at once
under a 1 GB memory limit now finish in a tenth of the time, and Mason's peak memory was about 8 % higher.- A query with many groups (more than a sixteenth of its rows, such as a min and max per name) is not faster. A min
and a max of the same column over many groups is slower: over 3.9 M groups, it took 60 s, where 0.22.0 took 43 s. - These are still slow: a grouped min or max over many groups,
FETCH FIRST … WITH TIESsorted by a text, a min or
max withFILTERor underROLLUP, and aSELECT DISTINCTwith noLIMITover a column whose values are nearly
all different.
- A query with many groups (more than a sixteenth of its rows, such as a min and max per name) is not faster. A min
mode() WITHIN GROUP (ORDER BY …)of atextorvarcharis faster under a libc collation, such as a database
whose collation isen_US.utf8. Over a million rows, the most common status per tenant took 2.2 s and now takes
under 0.1 s, about a fifth of Postgres's time. The answers are Postgres's, as before: of values equally common, the
first in the collation's order wins. Under a locale other than English, a value holding a character Mason cannot order
as the collation does now refuses the query only when it is among the most common values of its group. Before, any
such value it read refused it. These are still slow: amode()of achar(n)or acitext, one ordered with
USING, and one of a value that callsrandom()or reads a subquery or an outer query's column.to_charof a date or a time is faster with a quarter, a padded name and most other patterns. Over a million
rows, a count byto_char(created_at, 'YYYY "Q"Q')or byto_char(created_at, 'Month YYYY')took about 4 s and
now takes 0.1 to 0.15 s, where Postgres takes about 0.4 s. This now holds for most patterns, padded or withFM,
withTHafter a number. These are still slow:TM,FX, a time zone'sTZ,TZH,TZMandOF,SP,FM
before literal text, a backslash, a format passed as a parameter, a year before 1 or after 9999, and a date formatted
with a time of day.- The web page's Users page now shows how to connect an MCP client. The Connect box is now titled "Connect a
Postgres client or BI tool". Under it, a new box, "Connect an MCP client", gives the line to run for Claude Code and
the JSON for Claude Desktop, Cursor and other clients, each with a Copy button. Both runmason mcpthroughnpx,
pinned to the version of Mason you run, so the client's computer needs Node 22.13 or later. The web versions of
ChatGPT and claude.ai can't connect this way yet.- When you add a user, its dialog has the same two in a closed section, "Connect an MCP client", with the user's
password in them. Like the password, they are shown only once.
- When you add a user, its dialog has the same two in a closed section, "Connect an MCP client", with the user's
- On the web page's Users page, "Temporary cloud login" is now "Temporary cloud tunnel". Its button is now "Open a
cloud tunnel".mason shareis unchanged.- Its card now shows the Database and the SSL mode, each with a Copy button, in the order of the Connect box: Host,
Port, Database, SSL mode, Login. A BI tool's form asks for both. The SSL mode is alwaysrequire, and a tool
that connects without SSL is refused. Before, they were only in the URL in the dialog shown once. - It now counts down to its end: "Online · ends in 59 min, at 18:55". The dialog shown once counts down too. A
tunnel with no end says "Online until you stop it". Before, it counted up: "Public for 53 s". - It says it usually opens in a few seconds. Before, it said that opening one can take up to 30 s. Mason still
gives up after 30 s, and says so.
- Its card now shows the Database and the SSL mode, each with a Copy button, in the order of the Connect box: Host,
mason status --jsonnow gives each open share'sdatabaseandsslmode, beside its host and port.- On the web page's Tables list, an added table's columns and its sync have columns of their own: Columns and
Sync. Each is the button that opens its choice, as before. The line under a table now holds only the longer
words: a first sync's progress, an error and the stream's state. In a narrow window, where these columns have no
room, their buttons are in the line under the table, as before. The Not added list has neither column. - The web page's Overview no longer has a Connected tools row. The Usage page shows who is connected now.
What was wrong and is now right
-
A column your sources file leaves out is no longer served under another name. This covers a column that
exclude:names, one acolumns:entry does not list, and a secret-looking columnmason addleft out. Before,
Mason matched columns by name alone. If two columns swapped names in one transaction, the left-out column was served
under the other's name. The same happened after a rename while Mason was stopped, and to a column renamed to a name
columns:lists. Now Mason knows each column by its identity on your database, which a rename keeps. A left-out
column stays out under any name, its old name too. Mason syncs it again only once you confirm it ("Before you
upgrade" says how).mason addconfirms whether Mason runs or not. It confirms the table as it read it. If the
table's columns change on your database before Mason takes the entry, it is not a confirmation, and the table is
held. Until then, if your entry would sync the column, Mason stops syncing that table and keeps serving the data it
holds. That covers a rename, a swap, a column renamed back under a name Mason took out ofexclude:, and a name you
take out ofexclude:or add tocolumns:by hand. The table's line inmason statusand on the web page says why,
and gives the line that keeps the column out.- Two synced tables that swap names on your database no longer pass a left-out column from one entry to the other.
The same holds for two schemas that swap names, and for a table renamed to another entry's name. Before, the entry
that syncs every column served every value of the column the other entry left out. Now the entry that names the
table is held until you confirm. The table that moved to the entry that leaves the column out is read again whole. - Under
sync: poll, a table dropped and created again under its name is now read again whole by itself. Its columns
are decided again by name, and a name the old table left out stays out. Undersync: replicationit is not read
again by itself, as before.
- Two synced tables that swap names on your database no longer pass a left-out column from one entry to the other.
-
A table synced whole is no longer served with rows missing until its catch-up. This is a first sync, or a
table synced again whole, such as after its columns change.- Before, the synced table held only the rows written before the oldest open transaction on your database began.
It was served like that until its catch-up a moment later, or longer when the catch-up failed. In the worst case
it served 0 rows: aTRUNCATE, then another transaction left open, then the reload. - Now each whole sync is caught up before it is served. Until then, a table synced before keeps serving its previous
data, and a new table is not served yet.
- Before, the synced table held only the rows written before the oldest open transaction on your database began.
-
A WITH query named like the table it reads now gives Postgres's answer. In
WITH orders AS (SELECT * FROM orders WHERE status = 'paid') SELECT count(*) FROM orders, the WITH query's own
FROM ordersreads the table, as on Postgres. Before, Mason counted 0 rows. With a join, the query failed with
XX000 "Maximum call stack size exceeded". This also holds when the WITH query is inside a subquery or one arm of a
UNION, and when a later WITH query reads an earlier one named like a table. A WITH query in one arm of a UNION,
named like a synced table, could also read that table instead of itself when the query held a*. It now reads
itself.- A WITH query whose name differs from a table's only in case is now told apart from it, as on Postgres. Before,
WITH small AS (…) SELECT count(*) FROM "Small"counted the WITH query's rows, not the table"Small"'s. Tools
that make PascalCase tables, such as Prisma, write such names. - A whole row of a WITH query with a column list, such as
WITH q(a, b) AS (…) SELECT q FROM q, now answers.
Before, it failed with 42703.
- A WITH query whose name differs from a table's only in case is now told apart from it, as on Postgres. Before,
-
A query with
TABLESAMPLEis now refused by name. A sample is of your database's pages or rows, which the
synced table does not hold. Before, Mason refused it only as something it had not verified yet. Without that check,
TABLESAMPLE SYSTEM (100)was answered with 100 rows, not every row. Now every form is refused with
Mason gap tablesample, wherever the table is read: a subquery, a CTE, a join or a view. A literal percent past 100,
a NULL percent or a NULL seed gets Postgres's own error. To read a part of a table, filter it, such as
WHERE id % 10 = 0. -
A column, table or alias whose name starts with
__mason_now gives Postgres's answer. Mason writes names of
its own into the queries it runs on the synced data, and they all started with__mason_. A name of yours that
matched one, in any case, was taken for Mason's:- a table with a column named
__mason_ridanswered NULLs for its columns in the first rows of a join, such as
SELECT t.*, o.v FROM t LEFT JOIN other o ON o.id = t.id ORDER BY t.id LIMIT 10; - a jsonb column named
__mason_v,__mason_xor__mason_kanswered NULLs or failed when read with->,@>or
jsonb_object_keys; - a table named
__mason_lateor__mason_ties_bound, or a FROM alias named__mason_late, answered another
table's rows or failed; - a subquery with two columns whose names differ only in case, beside a third such as
t__mason_2, answered one
column's values in another.
Now the names Mason writes are chosen so that no name your query can reach holds them, columns read by a
*
included. - a table with a column named
-
Two generated tables that read each other through a WITH query named like one of them are now refused. Take a
tableadefined asWITH b AS (SELECT * FROM b) SELECT * FROM b, and a tablebthat readsa. The WITH query's
ownFROM breads the tableb, as on Postgres. So the two read each other, and each is refused with the cycle,
as any cycle is. Before, Mason missed the cycle. Both said they were waiting for the other, for ever, and neither
was built. -
to_charwithFMMSnow pads to three digits, andY,YYYwithTHkeeps its ordinal, as on Postgres.