# Mathesar: a spreadsheet interface sitting directly on Postgres

> A Django and Svelte application that puts a grid, a query builder and a form builder in front of a live PostgreSQL database, with no ORM layer in between. Installs with Docker, still at public beta.

**mathesar-foundation/mathesar** — An intuitive spreadsheet-like interface that lets users of all technical skill levels view, edit, query, and collaborate on Postgres data directly. 100% open source and self hosted, with native Postgres access control.

- Repository: https://github.com/mathesar-foundation/mathesar
- Website: https://mathesar.org/
- Stars: 5,148 · Forks: 486
- Language: Svelte
- License: GPL-3.0
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/mathesar-foundation-mathesar

## A grid over the real schema, not over a copy of it

The central design decision is stated in the repository description and repeated in the README: Mathesar works directly against PostgreSQL databases, schemas and tables without extra abstractions. That single sentence separates it from the hosted spreadsheet products it is usually compared with. When the README says relationships in the interface are foreign keys in the database, it means the joins you see in the grid are the joins Postgres already had.

The consequence is that a table you create through the interface is a table your existing `psql` sessions, `pg_dump` schedules and BI tools see immediately. The other consequence is that Mathesar is bounded by what Postgres supports, so a feature request that needs a non-relational document store is a feature request for a different database.

The repository language on GitHub is listed as Svelte, with topics that include both `django` and `sveltejs` plus `python` and `typescript`. Reading the tree confirms the split: a `mathesar/` directory for the Python side, a `mathesar_ui/` directory for the frontend, `manage.py` at the root, and a `db/` directory. It is a conventional Django project with a separate single page app rather than a server rendered one.

## Installing means one compose file and three variables

The README does not carry an install command. It links to docs.mathesar.org and says installation happens in minutes, which leaves the actual steps in documentation you are not reading here. What the repository does contain is a `docker-compose.yml` whose own header comment calls it a viable production setup, plus `Dockerfile.caddy` and a separate `Dockerfile.devdb` for development.

The prerequisites are stated inside that compose file rather than in the README, which is unusual and useful. Docker v23 or newer and Compose v2.10 or newer, on Linux, Mac or Windows under WSL. The file also says explicitly that running Docker in rootless mode is not currently supported, which is the kind of sentence that saves an afternoon.

```bash
$ docker version
$ docker compose version
```

Configuration happens through environment variables declared under a shared `x-config` anchor, so a single block feeds every service:

```yaml
x-config: &config
  DOMAIN_NAME: ${DOMAIN_NAME:-http://localhost}
  POSTGRES_DB: ${POSTGRES_DB:-mathesar_django}
  POSTGRES_USER: ${POSTGRES_USER:-mathesar}
```

Note what the defaults imply. `POSTGRES_DB` names an internal database for the Django application itself, separate from the database Mathesar is being pointed at, and `DOMAIN_NAME` defaults to plain `http://localhost` with no certificate. This is a deployment that assumes a reverse proxy will eventually take over TLS, which the presence of `Caddyfile` and `Dockerfile.caddy` in the tree confirms.

## Access control inherited from Postgres roles

The feature list leads with built on Postgres, install in minutes, and Postgres based access control, in that order, which reflects how the project wants to be judged. The README says you can use existing Postgres roles within the interface, or set up your own, and that access control based on roles and privileges keeps the database secure without adding unnecessary risk.

This is the strongest argument for the project in a regulated or team setting. Mathesar does not implement a parallel permission system that could disagree with the database; it defers to `GRANT` and `REVOKE`. If a role has no `SELECT` on a table, the grid shows nothing for that role, and that behaviour is enforced by Postgres rather than by a Svelte component.

The repository supports this with `django-allauth`, pinned in `requirements.txt` at version 65.14.1 with the `socialaccount` extra, alongside `django-modern-rpc` at 1.0.3 for the JSON RPC surface and `django-fernet-encrypted-fields` for storing credentials at rest. The tree also carries `sso.yml.example` and `login_page.yml.example`, so single sign-on and a custom login page are configuration files rather than code changes.

## Query building, forms and migrations in one application

The features that go beyond a plain grid are worth separating by audience. The Data Explorer builds queries without requiring SQL or join knowledge, which is aimed at people who will never open a psql prompt. Forms publish a unique link and save submissions as new records, which turns the application into a lightweight intake system for external contributors. Schema migrations that transfer columns between tables in two clicks are aimed at the administrator.

A lesser feature is easy to miss and arguably the more telling one: custom data types for emails and URLs validated at the database level. That is not a frontend regex. It means an invalid email never reaches the table, because the constraint lives where `psql` will enforce it too. Given how often spreadsheet-shaped front ends are criticised for moving validation to the browser, the choice to delegate to the database is the right one.

The README documents import and export without specifying formats, and the `requirements.txt` file explains why those features are possible at all: `clevercsv` at 0.8.2 for CSV handling and `CairoSVG` at 2.9.0 for rendering. Import formats are exactly the kind of detail that belongs in the documentation rather than the README, and that is where it lives.

## Public beta, three releases a year, and notes kept elsewhere

The status section is unusually honest for a project with five thousand stars. It shows Public Alpha complete, Public Beta complete, and Public, described as widely used in production environments, still unchecked. The README says plainly that the project is currently in the public beta stage. For an evaluator that is the most useful line in the document, because it tells you the authors themselves do not claim broad production adoption yet.

The default branch is `develop`, which is worth noting before anyone opens a pull request. The release cadence visible on GitHub is three tags in 2026: 0.12.0 on 2026-07-02, 0.11.0 on 2026-05-28 and 0.10.1 on 2026-04-26. Every one of those release bodies contains nothing but a link to release notes hosted on docs.mathesar.org, so the repository itself does not record what changed between versions.

That gap is the practical risk. You cannot read a changelog before upgrading without leaving the repository, and the version numbering suggests active development where features may move. GitHub reports the last push on 2026-09-21, and the repository is not archived, so the work is current.

## Where the README stops and the external docs begin

Everything about running the thing is external. Installation, configuration variables, environment variable reference, release notes and the contributor onboarding all live on docs.mathesar.org or in `CONTRIBUTING.md` and `DEVELOPER_GUIDE.md`. The README is a project page with a table of contents, a features list and fourteen screenshots, and it is honest that it is doing that.

The screenshots carry more specific information than the prose does, because their alt text names actual states. There is a dialog for creating a PostgreSQL database with sample dataset options, a collaborators page showing a read-only user being added, a schema page for a library management dataset, and a table view with the table inspector open. A screenshot showing a read-only collaborator is a stronger statement about the permission model than the feature bullet it illustrates.

For a reader comparing options, the honest framing is this. Mathesar competes with database admin tools on one side and with hosted spreadsheet front ends on the other, and it wins the second comparison for anyone who already has Postgres and cannot send that data to a third party. It loses the first comparison on breadth, because it deliberately does not try to be a full admin console. Check the docs for upgrade guidance and the configuration variables before the second install, because the repository will not tell you either.

## Conclusion

Mathesar is worth an afternoon for any team that already runs Postgres and is tired of writing one-off admin panels, because it reads and writes the same tables through the same roles that already protect them. What the repository does not settle is upgrade behaviour: the README is explicit that public beta is done and public is not, and the release notes live on docs.mathesar.org rather than in the repository. Start with the bundled docker-compose.yml on a copy of a real database, add a read-only Postgres role, and see whether the collaborative editing story matches what your team actually needs.

## FAQ

### What is Mathesar used for?

It is a web application that gives non technical and technical users a spreadsheet-like interface for viewing, creating, updating and deleting records in a PostgreSQL database, plus a query builder, shareable forms and import and export. Because it talks to Postgres directly, tables created through the interface are ordinary tables.

### Does Mathesar need its own database?

The bundled docker-compose.yml defines an internal database for the Django application itself, defaulting to the name mathesar_django, separate from the database you connect to and manage. The POSTGRES_DB and POSTGRES_USER variables are documented as optional replacements if you prefer your own names.

### How do permissions work in Mathesar?

Access control is based on Postgres roles and privileges rather than a separate permission system, and the README says you can use existing roles in the interface or define your own. A role without grants on a table simply sees nothing for that table, enforced by the database itself.

### Is Mathesar ready for production use?

The README's status checklist marks Public Alpha and Public Beta as done and leaves Public, described as widely used in production environments, unchecked. The compose file in the repository is described as a viable production setup, so the intended path exists even though the stage label is public beta.

### What does Mathesar run on?

Docker v23 or newer with Compose v2.10 or newer, on Linux, Mac or Windows under WSL. The compose file states that running Docker in rootless mode is not currently supported.

## Sources

- [License: GPL-3.0](https://github.com/mathesar-foundation/mathesar/blob/develop/LICENSE)
- [mathesar-foundation/mathesar on GitHub](https://github.com/mathesar-foundation/mathesar)
- [Project website](https://mathesar.org/)
- [README](https://github.com/mathesar-foundation/mathesar/blob/develop/README.md)
- [Releases](https://github.com/mathesar-foundation/mathesar/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mathesar-foundation-mathesar