A drop-in replacement for your Postgres read replica. Same SQL. Same answers. Seconds, not minutes.
- Lightweight: Mason is a single Node.js process you can run anywhere.
- Works like a read replica: Choose which tables and columns to sync from your Postgres database, and how each stays in sync: on demand, polling or logical replication. Mason makes them available to query from any Postgres client.
- Exceptionally fast: Mason rewrites your Postgres queries to run on DuckDB's columnar engine, in the form DuckDB runs fastest. Analytical queries (
COUNT,SUM,GROUP BY, etc.) over large tables run significantly faster than on Postgres. - Same SQL, same answers: Mason is built from the ground up to match Postgres syntax and behaviour, so you can confidently point your existing SQL queries at Mason, without needing to port them to another SQL dialect (where subtle differences change your results).
- Built for AI agents: Give AI agents fast, secure access to your data: a user per agent, role-based access control (RBAC) that limits the tables, columns and rows each one can read, every query logged, and native MCP support.
Contents
- Try it in 2 minutes
- Use it with your database
- Speed and compatibility
- Agents · Where to read more · Community · License
# needs Node 22.13+ (mason doctor checks this machine)
npm i -g @mason-data/cli
# start a demo shop database: nothing else to install
mkdir mason-demo && cd mason-demo
mason init demo && mason start
# add the fourth table and watch its sync start
mason add order_items
# open the tables syncing, the users and the queries in your browser
mason ui
# delete the synced data and the demo database
mason destroyThe demo shop has four tables: customers, products, orders and order_items. A new order arrives every few
seconds. The demo polls every 5 seconds (sync: poll 5s), so mason status shows Mason keeping up. Mason reads the
demo database the same way it reads yours: over the Postgres protocol. The demo also has a
generated table, daily_orders. Nothing is downloaded after npm install on most machines
(cli/README.md).
A Mason project is your app's folder. Run these in it:
cd your-app
# write mason/sources/<database>.yml (commit it) and .mason/ (local, gitignored);
# Mason reads MASON_DATABASE_URL, then DATABASE_URL, from .env.local, .env or the shell
mason init
# choose the tables to sync: list them with their rows and keys, then add some
mason tables
mason add orders customers
# start Mason in the background and wait until every added table is synced
mason start
mason waitSet MASON_DATABASE_URL to sync a different database from your app's. mason init - < db-url.txt reads the URL from
a file and writes it to .env, out of your shell's history. mason init also writes mason/roles.yml
(Access control) and mason/mason.yml (the Mason version). Commit everything in mason/.
The sources file lists the tables Mason syncs. mason add and mason remove edit it for you, and keep your comments.
# mason/sources/app.yml: the database this project syncs from. Commit this file. The URL is not stored in it.
kind: postgres
url: ${DATABASE_URL} # a variable from .env.local, .env or the shell
sync: off # the default for every table, unless a table says otherwise
tables:
orders: # a bare name means the `public` schema; write `billing.invoices` for another schema
columns: [id, customer_id, status, amount, created_at, payload]
sync: poll 30s # this table is polled every 30 seconds
references: # its foreign keys: this column holds a customers.id
customer_id: customers.id
customers: {} # syncs every column
events:
exclude: [raw_body] # syncs every column except these
sessions:
key: [tenant_id, id] # only for a table with no primary key: the columns that identify a rowmason add orders --columns id,status,totalsyncs only those columns.mason add orders --sync "poll 30s"sets how the table stays up to date.mason addleaves out columns that look like secrets (password,token,api_key, …), and lists them underexclude:. Name one with--includeto sync it.references:says how a table joins the others. It lists the table's foreign keys, on the table that holds them.mason addwrites the ones your database declares, between tables the file syncs. When you add the table a foreign key points to later,mason addwrites it then. You can add a relationship your database doesn't declare by hand. A foreign key of several columns is written as in SQL:(tenant_id, customer_id): customers (tenant_id, id).- While Mason runs,
mason addandmason removetake effect at once. A change you make by hand applies at the nextmason start. If an entry has a mistake, Mason names the key and says how to fix it. You never write column types. - A column the file leaves out stays out until you confirm it, even if you rename it, its table or its schema on your
database. If a hand edit or a rename would sync such a column again, Mason holds that table and says why on its line in
mason status. Run themason add <table> --columns …the line gives to sync it. In a project deployed read-only, the committed file is your word, and the line says what to do there.
Mason reads each table once in full: the first sync. After that, each table's sync: says how it stays up to date.
sync: |
off (the default) |
poll 5m |
replication |
|---|---|---|---|
| after the first sync | nothing, until you run mason sync <table> |
a SELECT of the table, at the interval you choose |
reads the database's change log, like a replica |
| needs on your Postgres | a user that can SELECT the tables |
the same | wal_level = logical, a user with REPLICATION (or rds_replication), and a publication |
| creates on your Postgres | nothing | nothing | a replication slot (and a publication, if you don't name one) |
| works on a read replica | yes | yes | yes, on Postgres 16+, with a publication you name |
| good for | trying Mason, and reports that run on a schedule | most tables, every few seconds to every few hours | big, busy tables, and changes within seconds |
Your database stays safe. Mason only reads: it never writes, never changes a table, and never asks your database
to sort. The first sync uses at most 3 connections (MASON_COPY_PARALLEL). If it stops, it resumes where it stopped.
You can point Mason at a read replica, so its queries run there. Mason connects only when it syncs, or when you ask:
mason tables, add, remove, status, wait or doctor, or the web page while it is open.
Off. Mason reads nothing more until you run mason sync orders (or --all): before a report, from cron, or at
the end of a deploy.
Polling. Write sync: poll <interval>, from 1s to 24h. You set up nothing on your Postgres. Each poll reads the
whole table, because Postgres has no index on what changed. So choose an interval that suits the table's size: every
few seconds for a small table, every hour for one of 50 M rows. After each poll, Mason waits at least four times as
long as the poll took, so a table's polls never take more than a fifth of your database's time. When your file polls
by default, mason add writes sync: off for a table of over 1 M rows, and says so.
Logical replication. Write sync: replication. Mason reads the change log through one replication slot per
project, as a Postgres replica does.
- The publication. Name one with
publication:at the top of the sources file (${PG_PUBLICATION}works there). Mason checks it, but never creates, changes or drops it. Otherwise Mason needs the right to create its own. A read replica needs Postgres 16+ and a publication you name. - Two kinds of table can't be replicated. These are a table with no primary key (a
key:entry), and one withREPLICA IDENTITY NOTHING. Give themsync: poll <interval>instead.mason addwrites this for you. - Cap the slot's WAL. A slot keeps WAL until Mason reads it, even while Mason is stopped. Set
max_slot_wal_keep_size(Postgres 13+) on your database to limit it. Mason drops the slot, and checks it is gone, when no table usesreplicationany more, and onmason destroy.
If you change a table's sync:, Mason keeps its data and catches it up with one poll. docs/DESIGN.md
explains how each one works, and why.
Which command depends on where the tool runs:
# a tool that can reach this machine: get a connection URL (shown only once)
mason user add metabase
# a tool in the cloud: get a temporary address and login (Ctrl-C ends it)
mason sharePaste what it prints into your tool's Postgres connection form. Each synced table appears as a table in a database
named mason. To move a tool that reads your Postgres, change its host, port and database name, or keep the name with
database: <name> in the sources file.
A user's password lasts until you remove the user. mason share is for trying Mason with a cloud BI tool, on data
you may send through a free tunnel service. It is encrypted, but the tool does not verify the certificate, and it
lasts about an hour. The web page's Users page offers it as Temporary cloud tunnel. To keep a dashboard running,
run Mason on a server.
docs/POSTGRES-API.md explains how tools connect and which SQL Mason answers.
Every tool and agent connects as a user, and a role says what it may read. A role narrows what the sources file syncs, by table, by column and by row:
# mason/roles.yml: mason init writes it. Commit it next to the sources file, and review it the same way.
default: everything # the role of a user added without --role
roles:
everything:
tables: all # every synced table and column, including tables added later
agent:
tables:
orders: { columns: [id, status, amount, created_at] }
customers: { exclude: [email, phone] } # the same shape as in the sources file
tenant:
attributes: [tenant]
tables:
orders: { where: "tenant_id = :tenant" }
order_items: { through: orders } # filtered through its foreign key to orders# add users: each prints its password once, inside the connection URL
mason user add claude --role agent
mason user add acme --role tenant --set tenant=42
# refuse a user's logins until mason user enable claude (it keeps its password)
mason user disable claude
# block a user's next connection and end its open sessions at their next query
mason user remove claude- A query that reads a table or column outside the user's role is refused with
42501, as Postgres refuses it. ASELECT *over hidden columns is refused too. Mason never quietly returns fewer columns. - Remove the
default:line, and a user with no role reads nothing. - Every user is read-only, and exists only in Mason, never in your database. Changes take effect without a restart.
docs/POSTGRES-API.md has every rule.
# see your database, each synced table, the Postgres API and the queries, or all that and more
# in your browser
mason status
mason ui
# see every query that was refused, failed or cancelled, and why
mason logs --requests --failed
# see the sync's events: failures, restarts, each sync you asked for (--scheduled: every one)
mason logs --events
# see the queries running now (mason cancel <session> stops one)
mason logs --running
# see the last week, one line per hour: queries, the synced data, memory
mason usage --since 7d --step 1h
# stop Mason: the synced data stays, and the next mason start resumes in seconds
mason stopmason status lists the facts (Source, Sources file, Version, Up, Free disk, Connections open), then each table with
how it stays up to date and when it last synced, then the queries. mason ui opens the web page. Its Overview has
cards for the last day's sync and query errors. Tables and Users let you add and remove tables and users, and
Observability shows the queries, usage and sync events, each time range updating by itself.
mason --help lists every command, and cli/README.md documents each one.
On a server, Mason runs as one container, ghcr.io/embeddable-hq/mason-data, with mason serve. You deploy only
the project folder, mason/. It already names your tables and how each one syncs. Run mason help production to read
the whole road offline.
# fetch the compose file into the folder that holds mason/
cd your-app
curl -fsSLO https://raw.githubusercontent.com/embeddable-hq/mason-data/main/deploy/mason-data/compose.yml
# on the server, set in .env the database URL (under the name your sources file uses:
# MASON_DATABASE_URL or DATABASE_URL), MASON_API_KEY (openssl rand -hex 24) and
# MASON_PG_SELF_SIGNED_TLS=1 (see TLS below), then start Mason with your mason/ folder
docker compose up -d
# users are kept on the server, so add them there
docker compose exec mason mason user add metabase- One container per volume. Only one process can write the synced data. Deploy with stop-then-start (in
Kubernetes,
strategy: Recreate). The synced data stays on the volume, so a deploy is a few seconds of downtime, not a sync from scratch. - TLS. Clients from outside the container need it.
MASON_PG_SELF_SIGNED_TLS=1makes a certificate (clients usesslmode=require), or mount one from your CA. - Memory. Give the container 3 GiB or more, and enough for the columns your dashboards read. Memory says how to size it.
- Checks.
/healthzanswers once Mason serves, about 15 seconds after the first start./metricsis for Prometheus, with numbers only.mason ui --ssh <user@server>opens the server's web page from your machine. - Upgrades. Mason is pre-1.0, so a release may rename a command, a key or a setting.
mason.ymlpins the version. Read the release notes before each upgrade.
deploy/mason-data/README.md walks you through it, with
the settings to decide. deploy/README.md has guides for
Fly.io, Kubernetes, Railway and AWS ECS. Mason Cloud can also run it for you.
Mason Cloud runs Mason for you. It keeps a read replica of your Postgres up to date on a machine it manages, and you connect your BI tools to it.
It uses the same project folder and the same mason command. Sign in once, then deploy:
# sign this machine in, in your browser
mason login
# send mason/ to the replica and wait until it runs it
mason deploy --replica <org>/<name>Change a deployed project has the steps for each change after that. Choose the hosted
replica when you would rather not run and upgrade the container, the volume and TLS yourself.
docs/HOSTED-API.md documents the API the mason command uses.
A deployed project runs exactly what you deployed. So its web page is read-only, and you can't add or remove tables
there. Changes go through the project folder in your app's repository instead. This holds on a hosted replica. On your
own server, the page is read-only when you set MASON_PROJECT_READONLY=1, or when Mason cannot write the project
folder.
- Edit
mason/. In its sources file, add or remove a table, or change a table'ssync:or its columns. On your machine,mason addandmason removeedit the file for you. - Commit the change.
- Deploy it with the Mason version that
mason/mason.ymlnames. Mason runs a project pinned to its own release line (the minor version before 1.0), at its own patch or an older one. It refuses any other pin.- On a hosted replica, run
npx @mason-data/cli@<version> deploy --replica <org>/<name>. It shows what the deploy changes before it sends it. - On your own server, ship
mason/with your release and restart the container, which runsghcr.io/embeddable-hq/mason-data:<version>.
- On a hosted replica, run
A table you add is synced once the deploy runs. A table you remove has its synced data dropped.
To move to a newer Mason:
- Read that release's "Before you upgrade" in its
release notes, and make the changes it lists. Where Mason
runs on your machine or your server,
npx @mason-data/cli@<version> upgrade --checkin the project's folder lists which of your synced tables that release reads again whole, and how large each is. It works when the Mason you run now is a release after 0.22.0. - On a hosted replica, an owner of the organisation runs
mason replica upgrade <org>/<name>first. It installs the newest Mason the service offers. Mason on the replica restarts, and its connections drop. On the same release line, it then runs the newest patch. A new release line waits beside the old one until you deploy a project pinned to it.mason replica status <org>/<name>shows the versions the replica has. Skip this step when it already has the version you pin. - Set
version:inmason/mason.ymlto the new version. - Deploy the change as the first list says, with the new version.
Mason and Postgres answered the same 3 queries over the same rows. The primary keys are random UUIDs. The status column has no index, so the count reads every row on both. Each query was sent the first time, after a restart with the page cache dropped. One client sent it, or 10 clients sent it at the same moment. Each time is how long until every client had its answer, the median of 3 runs. Mason and Postgres each ran in a container with the same 4 CPUs and 8 GiB of memory. Postgres's count by status and revenue by month times are from the run of 2026-11-17, where its answers were the same. Its lookup times, and all of Mason's, are from the run of 2026-11-18.
| query | rows | clients | Postgres (s) | Mason (s) | Mason is |
|---|---|---|---|---|---|
| Count by status, every order | 1 M | 1 | 1.21 | 0.0576 | 21× faster |
| 1 M | 10 | 1.24 | 0.153 | 8.1× faster | |
| 10 M | 1 | 21.2 | 0.0932 | 227× faster | |
| 10 M | 10 | 21.7 | 0.241 | 90× faster | |
| 100 M | 1 | 216 | 0.452 | 478× faster | |
| 100 M | 10 | 710 | 1.22 | 583× faster | |
| Revenue by month, orders joined to customers | 1 M | 1 | 1.98 | 0.160 | 12× faster |
| 1 M | 10 | 3.61 | 0.574 | 6.3× faster | |
| 10 M | 1 | 24.0 | 0.965 | 25× faster | |
| 10 M | 10 | 43.9 | 3.87 | 11× faster | |
| 100 M | 1 | 335 | 17.9 | 19× faster | |
| 100 M | 10 | 2036 | 39.2 | 52× faster | |
| One order by its primary key | 1 M | 1 | 0.0345 | 0.131 | 3.8× slower |
| 1 M | 10 | 0.0375 | 0.202 | 5.4× slower | |
| 10 M | 1 | 0.0352 | 0.743 | 21× slower | |
| 10 M | 10 | 0.0392 | 0.826 | 21× slower | |
| 100 M | 1 | 0.0218 | 13.0 | 598× slower | |
| 100 M | 10 | 0.0250 | 13.3 | 531× slower |
Mason is for scans and aggregates. A lookup through an index is faster on Postgres (docs/DESIGN.md "Heap order, no index"). Cold times on Postgres depend on the disk's throughput. Each engine had 4 CPUs, 8 GiB of memory and no swap, on a disk of EBS gp3, 125 MB/s, 3000 IOPS. It was measured on m7g.xlarge, 4 vCPU, 16 GiB RAM, against PostgreSQL 18.7 and Mason at commit 688919542504, on 2026-11-17 and 2026-11-18. docs/MEASUREMENTS.md has every run and how it was measured.
Use Mason for analytical queries, and keep your application's own reads and writes on Postgres. Mason is fast because
DuckDB reads only the columns a query uses, works on batches of values, uses every core for one query, and skips blocks
of rows a filter can't match. Mason also stores the JSON fields your queries keep reading, and rewrites slow query
shapes into fast ones with the same answer. docs/POSTGRES-API.md explains each,
and how to make queries faster. docs/BENCHMARK.md shows how to run the benchmark yourself.
When dashboards keep computing the same aggregate, declare it as a generated table: a file in
mason/generated_tables/ that holds a SELECT. Mason keeps it up to date from the synced tables, inside Mason, and a
query reads it by name. The demo's daily_orders.yml is one. mason help generated has every key and rule.
Mason answers every query exactly as Postgres would: the same column names, type OIDs, text, row order and SQLSTATE error codes. If it can't, it refuses the query, and the error says what to write instead. It never gives a different answer silently, and the few cases it answers differently on purpose are listed. An oracle runs tens of thousands of queries on a real Postgres and on Mason, and allows only what comes back identical. The tests also replay what psql, pgjdbc, node-postgres, Metabase, Grafana, DBeaver and Superset send.
To show what Mason adds over DuckDB by itself, the oracle also sends 7,625 of its queries to a plain DuckDB connection, over the same tables. DuckDB alone answers only 25% of them exactly as Postgres does. Mason answers 93%. It answers 1% differently, each by a decision it lists, and it refuses 6% with an error that says what to write instead. None was answered with a wrong value.
docs/SQL-SUPPORT.md is generated from the code. It lists the 1,153 verified pieces (types, functions, operators, aggregates, window functions, casts, constructs and their forms). It also lists the 64 refused shapes, the 20 that are answered differently and the 8 limits, each with what to write instead.
docs/POSTGRES-API.md says how a query is answered and how this is tested.
An agent connects like any Postgres client, or over MCP, as a user with a role (Access control). If Mason can't answer a query exactly, the agent gets an error that says what to write instead, so it can try again.
mason mcp is an MCP server for Claude Code, Claude Desktop and other agents. Its tools list the tables, describe
one, and run or EXPLAIN a query. To add it to Claude Code, run this in the project's folder while Mason is running:
# get a connection URL for the agent (shown only once)
mason user add claude --role agent
# add Mason's MCP server to Claude Code, with that URL's password
claude mcp add mason --env MASON_URL="postgres://claude:<password>@127.0.0.1:5433/mason" -- mason mcpA hosted agent (claude.ai, ChatGPT) reaches mason serve over HTTPS instead, signed in by your OAuth server: set
MASON_MCP_URL, MASON_MCP_ISSUER and MASON_MCP_JWKS_URL (docs/POSTGRES-API.md).
A coding agent (Claude Code, Codex, …) uses the same commands you do. With --json, a command prints one JSON object
with a documented shape and what to run next, and its exit code says whether it worked. mason help agent is the page
an agent should read first. cli/README.md has the details.
cli/README.md |
every command and option of mason |
docs/POSTGRES-API.md |
the Postgres API: how a tool connects, roles, which SQL is answered, and how to make queries fast |
docs/OBSERVABILITY.md |
what you can see about a running Mason: each command, its endpoint and its JSON |
docs/WEB-UI.md |
the web page (mason ui): its pages, how access to it is protected, and how to extend it |
docs/SQL-SUPPORT.md |
what is verified to answer exactly as Postgres does, and what is not (generated from the code) |
docs/MEASUREMENTS.md |
when Mason is faster than a Postgres read replica: every measurement and how it was taken |
docs/BENCHMARK.md |
how to run the benchmark against a Postgres read replica |
deploy/mason-data/README.md |
how to run the image on a server, and how to size it |
deploy/README.md |
which platforms can run Mason, each with a guide, and which can't |
docs/DESIGN.md |
the design: how a query is answered, the first sync, polling, replication, and the measurements behind them |
release-notes/ |
what each release changes for you, and what to do before upgrading |
CLAUDE.md |
the rules of the codebase, for anyone who changes it, human or AI |
If Mason is slow, gives a wrong answer, or answers anything differently from Postgres, please open an issue. The forms ask for the query, the types, and both answers or both timings. A difference you report becomes a test case. To report a security vulnerability privately, see SECURITY.md. Pull requests with a test are welcome: CONTRIBUTING.md says what one needs.
Apache-2.0 (LICENSE). Copyright Embeddable.