English · Español

gresbase

A modern, self-hosted studio for any PostgreSQL. One container, zero config.

Docs · Quick start · Demo · Changelog · Español

Contents

• Why Gresbase
• Features
• Quick start
  • Try the demo
  • Add it to your project
  • No configuration: the setup wizard
• Screenshots
• How it compares
• Configuration
  • Main variables
  • Settings file
• Security
• Compatibility
• Roadmap
• Contributing
• License

Why Gresbase

Adminer and pgAdmin still do the job, but they feel like another decade, and an edit goes straight to the database. Supabase Studio is a pleasure to use, but it comes with the Supabase stack.

Gresbase is one small container you add next to your Postgres. Every change waits in a queue, shows its SQL, and can be undone even after you save it.

↑ Back to top

Features

Search all tables A value in every table at once, with results arriving live, table by table, plus the names of tables, views and columns.	Fast tables Virtualized grid, keyset pagination, filters and multi-column sort kept in the URL.
Change queue Edits wait with a diff and their SQL, then save in one transaction.	Undo and redo Even after saving, through inverse operations that check for conflicts.
Structure editing Tables, columns, indexes, constraints and foreign keys, previewing the exact DDL.	SQL editor Autocomplete, tabs, :name parameters, transaction mode, history and saved queries.
Spreadsheet friendly Copy a rectangle as TSV, CSV, JSON or INSERT; paste into the queue.	Many connections Saved connections with color labels; each browser tab can use a different one.
Free mode Sign in with any Postgres user, like Adminer, limited to the servers you allow.	Zero config Environment variables or a setup wizard; settings in one file, secrets encrypted.
Safe by default Localhost only without login, read-only mode, timeouts, CSRF and rate limits.	Read-only and roles Searches and screens respect the Postgres role: its privileges and row security.
Import and export CSV into existing tables; exports that stream from the first byte.	Small and private One image, works offline, no telemetry; English and Spanish, light and dark.

_{Search all tables: type a term in ⌘ K, watch the results arrive and open a row.}

↑ Back to top

Quick start

Try the demo

PostgreSQL with sample data and Gresbase, using the published image. You only need Docker:

curl -fsSLO https://raw.githubusercontent.com/amtzespinosa/gresbase/main/deploy/docker-compose.demo.yml
docker compose -f docker-compose.demo.yml up -d

Open http://localhost:8080. Ports 8081 to 8084 run the other ways of using Gresbase: login, read-only, setup wizard and free mode, described at the top of the file.

To remove everything: docker compose -f docker-compose.demo.yml down -v.

Add it to your project

Put Gresbase next to your Postgres in your docker-compose.yml:

services:
  gresbase:
    image: ghcr.io/amtzespinosa/gresbase:0.4
    restart: unless-stopped
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/app?sslmode=disable
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - gresbase-data:/data

volumes:
  gresbase-data:

docker compose up -d

Then open http://localhost:8080. Binaries for Linux, macOS and Windows are attached to each release.

No configuration: the setup wizard

Leave out DATABASE_URL and Gresbase starts a setup wizard. The log prints a link with its token, or print the token with:

docker compose exec gresbase /gresbase setup-token

The quick start guide covers docker run, the wizard and databases outside Docker.

↑ Back to top

Screenshots

Tables · light	SQL editor · dark
Structure · dark	Setup wizard · light

More screens, on desktop and tablet, in docs/screenshots/.

↑ Back to top

How it compares

Every tool here is good at something. This is how they differ for the job Gresbase does: a web UI next to your own Postgres.

	Gresbase	Adminer	pgAdmin	Supabase Studio	DbGate
Self-hosted web UI	Yes	Yes	Yes (also desktop)	With the Supabase stack	Yes (also desktop)
One container, nothing else	Yes	Yes	Yes	No	Yes
Databases	PostgreSQL	Many	PostgreSQL	PostgreSQL	Many, SQL and NoSQL
Edits wait until you save	Yes, with diff and SQL	No	Yes	No	Yes
Undo after saving	Yes	No	No	No	No
Structure editing	Yes	Yes	Yes	Yes	Yes
Search across tables	Values and names, live, with the matching rows	Values: lists the tables that contain them	Object names	Table names	Object and column names
Server administration (roles, backups, monitoring)	Not yet	Partial	Yes	Platform features	Partial
License	Apache-2.0	Apache-2.0 or GPL-2.0	PostgreSQL	Apache-2.0	GPL-3.0

In the search row, Gresbase shows the rows that match, as each table answers, with a time and row limit per table and only what the role can read (privileges and row security). Adminer finds the tables that contain a value and opens each one filtered.

Pick pgAdmin for deep server administration, Adminer or DbGate when you work with several database engines, and Supabase Studio if you run Supabase.

↑ Back to top

Configuration

Every setting is optional. Use environment variables, or change settings from the app.

Main variables

Variable	What it does
DATABASE_URL	The database to open. Without it, the setup wizard or saved connections.
GRESBASE_USER / GRESBASE_PASSWORD	Turn on sign-in. Without an account, only localhost is accepted.
GRESBASE_READ_ONLY	true blocks every write.
GRESBASE_MODE_FREE	true signs in with Postgres credentials, like Adminer.
GRESBASE_ALLOWED_DB_HOSTS	Servers free mode may reach (hosts, IPs or CIDRs).
GRESBASE_ALLOWED_HOSTS	Extra host names accepted without sign-in.
GRESBASE_TRUSTED_PROXIES	Reverse proxies whose X-Forwarded-For gives the client IP.
GRESBASE_BASE_PATH	Serve under a sub-path, such as /gresbase.
GRESBASE_STATEMENT_TIMEOUT	Time limit per query (30s by default).
GRESBASE_DATA_DIR	Settings and saved queries (/data); mount a volume there.

Settings file

Settings changed in the app are kept in gresbase.json, and an environment variable always wins over it. Secrets in that file are encrypted.

All variables, ports and limits are in the configuration reference.

↑ Back to top

Security

• Without an account, Gresbase only answers requests for localhost, against accidental exposure and DNS rebinding.
• Passwords are stored as argon2id hashes, secrets in gresbase.json are encrypted, and logs never contain credentials.
• Sessions use SameSite=Strict cookies and a CSRF header; failed sign-ins are rate limited.
• Read-only mode is enforced twice: by the database session and by the API.
• Every query has a timeout, and long queries stay alive behind Nginx or Cloudflare.
• The real boundary is the Postgres role you connect with: give it only the privileges you want.

Reverse proxies, HTTPS and the setup token are covered in Security and networking.

↑ Back to top

Compatibility

PostgreSQL	Support
14, 15, 16, 17, 18	Full, tested on every change
19	Full, tested against the latest beta until it is released
12, 13	Legacy: tested on every change; a few features depend on the version and the UI says so
11 and older	Not supported; Gresbase explains it when connecting

The image runs on linux/amd64 and linux/arm64. Details per version in docs/compatibility.md (in Spanish).

↑ Back to top

Roadmap

• Studio edition (0.5): advanced mode, visual schema, metrics and a visual EXPLAIN.
• Administration (0.6): roles, extensions, views, functions, triggers, RLS and backups.
• Teams (0.7): multiple users with roles, permissions per connection, SSO and an audit log.

The full plan is in docs/spec.md (in Spanish).

↑ Back to top

Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md; the stack, the security rules and the conventions are in AGENTS.md, for people and coding agents alike.

You only need Docker and git: every toolchain runs in the development container.

docker compose -f dev.compose.yml up -d --build
docker compose -f dev.compose.yml exec workspace bash -lc "task dev"

↑ Back to top

License

Gresbase is licensed under the Apache License 2.0. Copyright 2026 Alex M. Espinosa; see NOTICE.

The Gresbase name and the mammoth logo are not covered by the license: forks use another name and logo, as explained in TRADEMARKS.md. Third-party licenses are listed in docs/third-party-licenses.md.

↑ Back to top