Skip to content

Mason v0.23.0

Latest

Choose a tag to compare

@github-actions github-actions released this 16 Nov 20:53
fbf6a67

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.0 in mason/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.22 branch. 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 that exclude: names, one a columns: entry does not list, and a
    secret-looking column mason add left out.
    • Before, you could take a name out of exclude: or add it to columns: 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 in mason status and 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 plain mason 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.
  • Check any script or alert that reads mason status --json, mason wait --json or 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. Its sync.state is waiting, not failed, and a new syncWaits
      gives why and checkedAt.
    • Its event is now sync_waits, which is not a failure. Before, it was full_sync_failed. full_sync_failed is
      still sent when a whole sync fails.
    • mason wait keeps waiting for a first sync that waits, within its --timeout. Before, it exited 1.

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 status and the web page now say Waiting, with the transaction the sync waits for. Before, they said
      Failed.
    • mason wait keeps waiting for a first sync that waits, within its --timeout. Before, it exited 1, so
      mason add <table> && mason wait read the wait as a failure. A table synced before is served meanwhile, so
      mason wait is ready for it.
    • In mason status --json and mason wait --json, the wait is no longer the table's error, and its sync.state
      is waiting. A new syncWaits says why, and when Mason last checked. If a script or an alert looks for failed
      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 was full_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 --check in 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. --json gives 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".
  • A grouped min() or max() of a text or varchar, and a SELECT DISTINCT sorted by one, are faster under a
    libc collation
    , such as a database whose collation is en_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 TIES sorted by a text, a min or
      max with FILTER or under ROLLUP, and a SELECT DISTINCT with no LIMIT over a column whose values are nearly
      all different.
  • mode() WITHIN GROUP (ORDER BY …) of a text or varchar is faster under a libc collation, such as a database
    whose collation is en_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: a mode() of a char(n) or a citext, one ordered with
    USING, and one of a value that calls random() or reads a subquery or an outer query's column.
  • to_char of a date or a time is faster with a quarter, a padded name and most other patterns. Over a million
    rows, a count by to_char(created_at, 'YYYY "Q"Q') or by to_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 with FM,
    with TH after a number. These are still slow: TM, FX, a time zone's TZ, TZH, TZM and OF, 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 run mason mcp through npx,
    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.
  • On the web page's Users page, "Temporary cloud login" is now "Temporary cloud tunnel". Its button is now "Open a
    cloud tunnel". mason share is 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 always require, 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.
  • mason status --json now gives each open share's database and sslmode, 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 a columns: entry does not list, and a secret-looking column mason add left 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 add confirms 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 of exclude:, and a name you
    take out of exclude: or add to columns: by hand. The table's line in mason status and 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. Under sync: replication it is not read
      again by itself, as before.
  • 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: a TRUNCATE, 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.
  • 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 orders reads 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 query with TABLESAMPLE is 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_rid answered 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_x or __mason_k answered NULLs or failed when read with ->, @> or
      jsonb_object_keys;
    • a table named __mason_late or __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.

  • Two generated tables that read each other through a WITH query named like one of them are now refused. Take a
    table a defined as WITH b AS (SELECT * FROM b) SELECT * FROM b, and a table b that reads a. The WITH query's
    own FROM b reads the table b, 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_char with FMMS now pads to three digits, and Y,YYY with TH keeps its ordinal, as on Postgres.