Studio edition /

Editions

Gresbase comes in two editions built from the same code. Studio adds an advanced mode to look inside the database and administer it.

Two editions#

Gresbase is built in two editions from the same code:

• Gresbase, the base edition: everything in the rest of this documentation. Its image is ghcr.io/amtzespinosa/gresbase:latest.
• Gresbase Studio: the base edition plus an advanced mode, with a schema diagram, metrics, a visual EXPLAIN, find and replace, and screens to administer roles, permissions, extensions and other objects. Its image is ghcr.io/amtzespinosa/gresbase:latest-studio:latest.

The Studio edition arrived in v0.5. To build it from the repository, follow Building from source and add --build-arg EDITION=studio.

Everything else is shared: configuration, sign-in, saved connections, free mode, the data volume and the health check. Inside the image the binary is /gresbase in both editions. /gresbase version prints gresbase-studio <version> in the Studio image.

The base edition contains no Studio code. Its Studio routes don't exist (they answer 404) and its interface has no trace of the advanced mode. If you don't need Studio, the base image stays as small and simple as before.

Pick the image#

Change only the image: line. The rest of the Compose file, the variables and the /data volume are the same in both editions, so you can switch from one to the other and keep your settings and saved queries.

services:
  gresbase:
    image: ghcr.io/amtzespinosa/gresbase:latest
    restart: unless-stopped
    environment:
      DATABASE_URL: postgres://USER:PASSWORD@HOST:5432/DBNAME
    volumes:
      - gresbase-data:/data
    ports:
      - "127.0.0.1:8082:8080"

volumes:
  gresbase-data:

services:
  gresbase:
    image: ghcr.io/amtzespinosa/gresbase:latest-studio:latest
    restart: unless-stopped
    environment:
      DATABASE_URL: postgres://USER:PASSWORD@HOST:5432/DBNAME
      GRESBASE_MODE: advanced
    volumes:
      - gresbase-data:/data
    ports:
      - "127.0.0.1:8082:8080"

volumes:
  gresbase-data:

The Quick start explains each line. With plain docker run, use the Studio image name in the last line of the command.

Basic and Advanced#

In the Studio edition, the sidebar has a Mode switch under the search box, with Basic and Advanced. With the sidebar collapsed it is an icon button.

• Basic is the app as in the base edition.
• Advanced adds an Advanced section to the sidebar, with one entry per module: Schema, Metrics, Find and replace, Roles and permissions, Extensions and Objects. It also adds Explain and Explain analyze to the SQL editor.

Each person picks a mode, and the browser remembers it. People who haven't picked one start in the mode of GRESBASE_MODE: basic by default, or advanced. The base edition ignores this variable.

The command palette (Ctrl K, or ⌘ K on a Mac) has Switch to the advanced mode and Switch to the basic mode, and in advanced mode it lists the advanced screens. Opening an advanced screen's address in basic mode takes you back to Tables with the notice “That screen is part of the advanced mode. Switch to it in the sidebar.”

The open screen is highlighted in the sidebar. The section's own address, /advanced, opens Schema.

Who can use it#

The advanced mode can be turned off for a PostgreSQL role, in Roles: Can use the advanced mode. It is a Gresbase setting, kept in the data volume for that role on that server, not a PostgreSQL one. A role without it sees no switch and only the basic mode, and the advanced screens answer 403 to it. Roles nobody has changed can use it, so existing setups keep working; a role created from Gresbase starts without it unless you tick the box. This matters most in free mode, where each person signs in with their own role.

Every change shows its SQL#

The advanced screens that change the database (roles, permissions, row security, extensions and objects) all go through the same steps:

1. You make the change in a form or with a button.
2. Gresbase shows the exact SQL under SQL that will run, with warnings when the change is risky: making a superuser, dropping with CASCADE, something that can't be undone. Passwords appear as '********'.
3. Nothing runs until you confirm. Deletions ask you to type the name of what you delete.
4. The statements run in one transaction, so either all of them apply or none. The few that PostgreSQL can't run in a transaction (such as REFRESH MATERIALIZED VIEW CONCURRENTLY) run one by one, and the dialog says so.

Find and replace works like data editing instead: a preview, one transaction and an undo. See Find and replace.

Permissions and read-only#

Studio does what the PostgreSQL role it connects with can do, nothing more. Each screen checks that role first: without the needed privileges, it shows everything it can read and explains what is missing instead of offering buttons that would fail. Security and networking lists the privileges each module needs.

In read-only mode, or on a server in recovery (a standby), every Studio module is view-only. You can read the diagram, the metrics, the roles and the objects, and preview a find and replace, but nothing changes. The API refuses those changes with read_only too.

In free mode, each person uses Studio with their own PostgreSQL role.