Repository navigation
Mason v0.20.0
Mason no longer leaves a time limit behind on your database's pooled connections. Behind a pooler in transaction
mode, your application's queries could be cancelled after 10 seconds, for up to an hour. After a fatal error in the
synced data, Mason now exits cleanly, and the cause reaches mason logs. A failed sync event now says its code and
where it happened, so you can group failures and report them. Metabase's previews of a join to a table with JSON
fields are faster. A host can show its own icon and who is signed in on the web page. Every project has something
to do first: its pin moves. A script or an alert that filters sync events by kind must change ("Before you upgrade").
Before you upgrade
-
Move the pin:
version: 0.20.0inmason/mason.yml. The 0.20.0 command and image refuse a project pinned to
0.19.x, and say how to fix it. Before 1.0 they only run a project pinned to their own minor version, at their own
patch or an older one. Set the pin and start 0.20.0 in the same step. -
On a hosted replica, upgrade the replica before you deploy a project pinned to 0.20.0.
mason deployrefuses a
pin the replica would not run, before it sends anything, and names both versions.mason replica upgrade <org>/<name>is one way out, where the service offers it. -
Two sync event kinds have new names.
copiedis nowfull_sync, andcopy_failedis nowfull_sync_failed.
You see them in these places:mason logs --eventsand its--json;mason status's Sync errors section, andrecentErrorsin its--json;- the Syncs filter on the web page.
If a script or an alert filters on an old name, change it in the same step. Events recorded before the upgrade keep
their old names. They still show in the full list, but an oldcopy_failedno longer counts as a failure.
What changes
-
A failed sync event says its code and where it happened.
mason logs --events --jsonand/api/eventsgive
each failure acodeand anorigin.- The code is the error's SQLSTATE when your database failed it. It is the system's error when the network or the
disk failed it (ECONNREFUSED,ENOSPC). Otherwise it is the error's class (conversion_error), orunknown. - The origin is a file and a line in Mason's code, such as
src/duck/sync.ts:3637.
Group failures by the code. Give the origin when you report one. An event that is not a failure has neither. The
Sync events page shows both under a failure's message. - The code is the error's SQLSTATE when your database failed it. It is the system's error when the network or the
-
A query that failed inside Mason says where. A request-log row answered with
XX000has anorigininmason logs --requests --jsonand/api/requests. Every other row has none. -
Both keys are new. Events and requests recorded before you upgrade are kept, and read with both keys null.
-
Metabase's preview of a join to a table with JSON fields is faster. This is the preview you see when you join a
table in Metabase's query builder and show fields it unfolds from a JSON column. Over a 3 M-row table, the 2,000-row
preview took about 5 s. It now takes about 0.6 s. Postgres still answers it faster, so there is more to do. The
20-row preview is faster too, when the table you start from is the bigger one. Mason no longer reads the other
table's whole join column before it returns the first rows. Both previews still return any rows of the join, as Postgres allows for a query
with no ORDER BY. -
Three shapes that Metabase and other BI tools send are faster:
- A count grouped by
to_char(created_at, 'YYYY-MM')over 4.5 M rows took 23 to 29 s. It now takes under a second,
about a quarter of Postgres's time. A format with a quarter (Q), a padded month name or an ordinal (DDth) is
still slow. - Metabase's week of the year over 12 M rows now takes about 1 s. Postgres takes about 4.5 s.
- A query that returns many
timestamptzvalues in a session in UTC sends them about three times as fast. 300,000
rows of aDISTINCT ONtook 10 s, and now take under 3 s, about Postgres's time. In a session in another time
zone, these values are still slow to send.
- A count grouped by
-
The SQL support list says plainly how Mason prints a
numericcolumn with no precision. Rails makes one from
t.decimal. Mason prints every value of such a column with the most decimals any of its values has. So12.5
reads12.50, and0reads0.00. The values are right. Only their trailing zeros differ from Postgres's. To get
the same text from Mason and Postgres, cast the column tonumeric(p, s)or useround(x, s). A fix is planned. -
For a host that serves the web page (
mason serve):- The page can show your own icon in the browser's tab. Set
MASON_UI_ICONto adata:URL of a PNG or SVG
image in base64, up to 4096 bytes. The icon is part of the page, so the browser makes no extra request for it. - The page can show who is signed in. Set
MASON_UI_ACCOUNTto JSON with alabeland aurl, such as
{"label":"ada@example.com","url":"/account"}. The label shows at the foot of the sidebar, as a link to the URL.
On a narrow window it is in the menu, with the nav. - A host view's link can be marked as a destructive action. Give it
"danger": true, and the page draws it in
red, like the Remove button on the Tables page. A link that is bothprimaryanddangeris refused, and the
view says why. So is adangerthat is nottrueorfalse.
A value of
MASON_UI_ICONorMASON_UI_ACCOUNTthat Mason cannot use stops the start. The message says what is
wrong and what a valid one looks like. Unset, the page is as before. - The page can show your own icon in the browser's tab. Set
What was wrong and is now right
- Mason no longer leaves a time limit on your database's pooled connections. When the web page checked whether a
table could be kept current by replication, Mason set a 10-second time limit on its connection and never took it off.
Behind a pooler in transaction mode (PgBouncer, or Supabase's default pooler URL), that connection is handed on to
your application next. Your application's queries could then be cancelled after 10 seconds, for up to an hour.
mason mcpdid the same on Mason's own Postgres API, with each tool call's time limit. Now each limit ends with
Mason's own query, whatever pooler sits in between. - After a fatal error in the synced data, Mason no longer aborts on its way out, and the cause reaches
mason logs.
A checkpoint that fails on a full disk is one such error. Mason then ends the run, so that it can start again.
Sometimes the run aborted instead, with exit code 134 andterminate called after throwing an instance of 'Napi::Error'. The cause could then be missing frommason logs. Now the run waits up to 5 seconds for the synced
data to close. Then it writes its log to the end and exits with code 1. If the synced data is still closing after 5
seconds, the log says so, and the run exits anyway. - A polled table no longer costs an extra connection to your database now and then. On some machines, Mason's
timer for the next poll woke a moment early. Mason then connected to your database, found no table due yet, and
connected again a moment later to poll it. Now every timer waits until its time has come. - A table's columns dialog on the web page names the same choice as its row. On the Tables page, a table that
leaves out columns which look like secrets says "All but 7 columns". Its columns dialog said "All columns, … but
password, …", so it read like a different choice. Now the dialog's choice starts with the same words, "All but 7
columns", and names the columns left out.
Known
-
A generated table can't yet hold some kinds of computed
numericcolumn. These are refused:- a division, or an average;
- a variance or a standard deviation;
sqrt,exp,ln,logandpower;- a JSON number cast to
numericwith no scale; - a value with more than 18 decimals;
- a sum, a CASE, a GREATEST, a LEAST or a COALESCE of values with differing decimals;
- a cast from a double.
A domain and a composite type are refused too, and so is
kind: live. Each refusal names the file and the key, and
shows the SQL to write instead. It comes before anything is built. A run that fails, such as one with a value too
big for its column, records Postgres's error and is tried again later. -
mason statusshows generated tables; the web page doesn't yet. -
Pages of every LIMIT with no ORDER BY over a join may overlap:
LIMIT n OFFSET mwith no ORDER BY over a join has
no stable order, so a tool paging one can see a row twice and miss another. Add an ORDER BY where the pages matter. -
A replicated table whose re-read never completes can rejoin the stream with no catch-up, and miss what the stream
passed over, as in every release since 0.8.0. It was found by reading the code and has not been reproduced. -
The web page's errors are not recorded under
MASON_UI_READ_ONLY=1. A read-only page cannot send them. -
A table under
sync: replicationblocksALTER TABLE … DROP COLUMNon your database. This happens on Postgres
15 and later, when Mason made its own publication and the table's replica identity is its primary key (the
default). That publication lists the table's columns, so Postgres refuses
the drop with "publication … depends on column". To drop a column today, run these with Mason running:mason add <table> --sync "poll 5m". Mason takes the table out of its publication, and keeps its synced data.- Drop the column on your database.
mason add <table> --sync replication. Mason reads the table's columns again and syncs the table again, whole.
Or run
mason remove <table>, drop the column, thenmason add <table>. This drops the table's synced data until
it is synced again. A fix is planned. This is so on 0.19.0 too. -
A column added to a table on your database isn't synced until Mason restarts. Until then,
mason statussays
the table is synced. A column renamed or dropped makes that table's syncs fail until a restart. After a migration
that changes a synced table's columns, restart Mason:mason stopthenmason start, or restart the server. Running
mason add <table>again also works, and syncs that table again, whole. A new column that looks like a secret is synced too.
If it should stay out, add it to the entry'sexclude:before you restart. A fix is planned. This is so on 0.19.0
too.