How to Use Mathesar: The Beginner’s Guide (First Connect, the Spreadsheet Lesson, Relationships, and the Data Explorer Arc)

CodexFuse Team · 2026-11-02T05:58:53.079Z · 12 min read min read

Learn how to use Mathesar, the open-source spreadsheet UI for Postgres: first connect, the spreadsheet lesson, relationships, Data Explorer, forms, and the Docker install.

Learning how to use Mathesar starts with a mental-model lesson, and it is the most important sentence in this guide: Mathesar is a spreadsheet-like interface on top of your REAL PostgreSQL tables. There is no abstraction layer, no sync layer, no data migration — your actual data lives in your PostgreSQL database, outside Mathesar, and Mathesar only keeps an internal metadata database (users, connection credentials, saved explorations). Edit a cell in Mathesar and you have edited the row in Postgres itself.

That mental model also draws the product's one hard boundary, stated plainly and once: Mathesar only works with PostgreSQL databases. If your data lives in MySQL, SQLite, or MongoDB, this is not your tool — the team hopes to reach other databases through Foreign Data Wrappers someday, but for now it is Postgres or nothing.

The closest sibling most developers know is DBeaver, and the line between them is worth drawing once: DBeaver is a SQL client for people who write SQL; Mathesar is a spreadsheet for people who should not have to. If your team includes non-technical people who need real Postgres data without learning SQL, our DBeaver beginner guide covers the SQL half of the world — this Mathesar tutorial covers the spreadsheet half.

What Is Mathesar, Exactly?

Mathesar is a secure, spreadsheet-like tool for Postgres data: an intuitive, open-source UI to view, edit, and query Postgres data, with easy deployment and robust access control. It combines simplicity and power in a spreadsheet-like UI that works for both DB admins and business users — and the Mathesar Postgres pairing works because the UI never invents its own storage: it works directly with Postgres permissions, schemas, and tables with no extra abstractions or layers, so everything you do in the UI maps to real database operations.

Concretely, that means the UI features you will use most are thin views over database concepts you may already know: "Relationships" in the UI are foreign keys in the database, groups and filters are queries, and the Data Explorer is a visual query builder that writes the joins for you. Mathesar is currently in public beta — the team describes it as stable and feature-rich enough for production — and it is maintained by the Mathesar Foundation, a nonprofit, under the GPLv3 open-source license. If this Mathesar for beginners guide sounds like the right shape for your team, the rest of this article walks the whole path from install to first exploration.

The project also offers Mathesar Cloud, a hosted service currently in early beta with a free plan, for teams that do not want to self-host. This guide covers the self-hosted path, which is how most beginners run it.

How Do You Install Mathesar with Docker?

The Mathesar Docker install is a single Docker Compose stack. The official path requires Docker v23 or newer and Docker Compose v2.10 or newer, and the whole install is three steps.

wget https://github.com/mathesar-foundation/mathesar/raw/0.12.0/docker-compose.yml
# set DOMAIN_NAME, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD
# (and optionally SECRET_KEY) in the x-config section of the file
docker compose -f docker-compose.yml up

Then visit localhost in your browser, and Mathesar walks you through creating your admin account on first launch. The version pinned above is 0.12.0, the current stable release at the time of writing — if a newer release exists when you read this, swap the tag in the wget URL. New to the tooling? Our Docker beginner guide covers containers and Compose before you run your first stack.

There is also an install-from-scratch path for people who want Mathesar running directly on a machine instead of in containers. It requires PostgreSQL 13 or newer and has been tested on Debian 12, Ubuntu 22.04, and macOS 14 (Windows goes through WSL 2). For a beginner, the Docker path is the one to take: it bundles Mathesar and its internal metadata database into one reproducible stack.

How Do You Connect Your First Database?

You connect your first database by clicking the "Connect Database" button on the Mathesar home page and following the prompts. Each Mathesar installation can connect to multiple PostgreSQL databases, and Mathesar remembers the connections even after the application is shut down.

Two things happen during that flow that beginners should understand. First, your Mathesar user is added as a collaborator on the database alongside the PostgreSQL role you entered — so you are connecting with a real database role, not a toy login. Second, the password for that role is stored in Mathesar's internal database, encrypted with Mathesar's SECRET_KEY, which is why the SECRET_KEY env var in the install step matters.

One Docker-specific trap to know about: if your Postgres runs on the same machine outside the Mathesar container, setting the host to localhost may fail, because localhost from inside the container means the container itself. Use host.docker.internal on macOS and Windows, or the Docker gateway IP on Linux.

What Is the Spreadsheet Lesson?

The spreadsheet lesson is this: every table in your database opens as a spreadsheet you can work with directly. You can view, create, update, and delete table records in cells, and you can filter, sort, and group the data to slice it different ways — exactly the moves you would make in a spreadsheet, applied to live database rows.

Two details make this more than a pretty grid. First, you can copy and paste multiple cells across rows and columns, with automatic type conversion, so bulk edits feel like spreadsheet work rather than row-by-row database surgery. Second, Mathesar lets you transfer columns between tables in two clicks — a schema-migration move that would normally mean writing an ALTER TABLE migration by hand. Custom data types for emails and URLs are validated at the database level, so the spreadsheet enforces real data quality rather than just looking like it does.

How Do Relationships Work in Mathesar?

Relationships in Mathesar are foreign keys in your database, surfaced as linked records in the UI. Cells from one table can reference records from another table through foreign key constraints, and Mathesar uses those constraints so you can model your data with real relationships instead of duplicating values across sheets.

In practice this means you can link two tables together from the UI — for example, an orders table to a customers table — and then browse into nested records: click a customer's name in the orders sheet and you see that customer's full record. If you have ever used a spreadsheet's lookup columns, this is the database-native version: the relationship exists in Postgres as a genuine foreign key, not as a fragile text match.

How Do You Explore Data Without Writing SQL?

You explore data without SQL using the Mathesar Data Explorer, a visual query builder that creates reports across multiple tables. You pick the tables, add filters and sorting, and summarize the data to see aggregate values — Mathesar handles the joins itself, which the README sums up as building queries "without knowing anything about SQL or joins."

The Explorer has one rule beginners must internalize: it is read-only and will not let you modify any data. It is a reporting tool, not an editing tool — the spreadsheet view is where edits happen. What you can see in the Explorer is determined by the privileges of the PostgreSQL role you connected with, so different team members see different slices automatically. And once you have constructed an exploration, you can save it to run it again later, which turns ad-hoc questions into reusable reports.

How Do You Collect Data with Mathesar Forms?

You collect data with Mathesar forms by building a form on top of a table and sharing its unique link. Each form is linked to one table, and submissions are automatically saved as new records in that table — so a form is just a public front door into your real database.

The important part of the forms story is who does not need an account: anyone with the link can submit responses, without ever getting access to your Mathesar installation. That makes forms the right tool for collecting signups, applications, feedback, or survey responses into Postgres — the data lands as ordinary rows that your team can then work with in the spreadsheet view, link to other tables, or report on in the Data Explorer.

How Do You Import and Export Data?

You import and export data from the UI, which makes Mathesar the on-ramp for existing datasets. Imports support CSV, TSV, and JSON with automatic column-type inference, so a spreadsheet export from your current tooling usually lands cleanly as a new table.

During import you get to configure the primary key: an auto-incrementing integer, a UUID, or an existing column from your data. That choice is worth thirty seconds of thought, because it becomes the table's real Postgres primary key — Mathesar imports into genuine database structures, not a staging area you have to clean up later. Exports go the other direction, so you can always take your data elsewhere.

Mathesar vs pgAdmin: What's the Difference?

The difference between Mathesar and pgAdmin is who each tool is for. pgAdmin is the official administration and development tool for PostgreSQL: it is built for DBAs and developers who think in SQL, schemas, and server management. Mathesar is built for everyone else — business users, founders, operations teams — who need to work with Postgres data through a spreadsheet.

The practical rule: if the person touching the data writes SQL for a living, they probably already have pgAdmin or DBeaver. If the person touching the data runs the business, Mathesar is the tool that keeps them out of SQL. Many teams run both — the engineers keep their SQL client, the operators get the spreadsheet.

If you are setting either of them up on your own infrastructure, our what is VPS hosting guide explains the server a self-hosted database tool lives on.

What Are the Limits Beginners Hit?

The limits beginners hit are few but real. First, the public-beta status: the project says it is stable enough for production, but a beta still means you should test your workflow on a copy of your database before pointing it at the one that matters. Second, access control inherits from Postgres roles — Mathesar users are mapped to specific PostgreSQL roles, and you configure role privileges at the schema and table level from the UI, which means your permission model is only as clean as your Postgres roles are.

Third, remember the boundary from the top of this guide: Mathesar speaks only PostgreSQL. If you pair it with a managed Postgres — including the Postgres that powers platforms like Supabase — that constraint disappears into the background; our Supabase beginner guide covers that half of the pair.

7 Beginner Mistakes in Mathesar

The mistakes below are the ones that cost beginners the most time, distilled from the project's own docs and release notes.

Sources

1. mathesar.org — product homepage: "Secure, spreadsheet-like tool for Postgres data"
2. docs.mathesar.org — user guide: data lives in PostgreSQL, Postgres-only note
3. mathesar-foundation/mathesar — releases: current stable 0.12.0
4. docs.mathesar.org — install via Docker Compose: Docker v23+, Compose v2.10+, the three-step install
5. docs.mathesar.org — install from scratch: PostgreSQL 13+, tested platforms
6. docs.mathesar.org — connecting databases: multiple databases, Connect Database button, encrypted credential storage, Docker localhost caveat
7. mathesar-foundation/mathesar — README: spreadsheet features, relationships, Data Explorer, forms, import/export, GPLv3 license, Mathesar Cloud
8. docs.mathesar.org — Data Explorer: read-only reports, saved explorations, role-based visibility
9. mathesar.org — 0.5.0 release blog: forms launch details
10. mathesar.org — 0.2.2 release blog: copy-paste with type conversion, import primary-key configuration
11. mathesar.org — 0.2.0 release blog: Mathesar users mapped to PostgreSQL roles

Frequently Asked Questions

Is Mathesar free?

Yes. Mathesar is open source under the GPLv3 license and free to self-host. There is also Mathesar Cloud, a hosted service in early beta with a free plan, for teams that do not want to run it themselves.

Does Mathesar work with MySQL?

No. Mathesar currently works only with PostgreSQL databases. The project has said it hopes to reach other databases through Foreign Data Wrappers in the future, but that is not available today.

Where does my data live when I use Mathesar?

In your PostgreSQL database — not in Mathesar. Editing a cell in the Mathesar UI edits the actual row in Postgres. Mathesar only keeps an internal metadata database of users, connection credentials, and saved explorations.

Is Mathesar a replacement for pgAdmin?

Not exactly. pgAdmin is a DBA and developer tool for administering Postgres servers and writing SQL; Mathesar is a spreadsheet UI for people who work with the data without writing SQL. Many teams use both side by side.

Can I use Mathesar without knowing SQL?

Yes — that is the point. The spreadsheet view, the visual Data Explorer, and forms are all designed for non-SQL users. You only need SQL-level knowledge for the underlying database setup, which your DBA or developer handles.