Skip to content
In this guide

Guide

Seqora puts the structure of a database on screen: the plan the planner chose, the page behind every table and index, the diagram of how it all joins. This guide is about reading what you see there, and then changing it without regret.

Start with the question you have. If a query is slow, start at the plan. If you have inherited a database, start with the schema you did not write. If you only want to know what a panel does, the reference is at the end.

Every page uses the same sample database, the commerce sample the home page shows, so the tables stay familiar from one page to the next. Every page says what it was checked against, and is signed, because one person wrote it and would like to hear where it is wrong.

Start here

  • Start here

    What Seqora is for, the first ten minutes with the bundled sample, and which page answers the problem you came with.

Reading

  • Why is this query slow?

    Read the Plan tab on a 4.6-second report: the row flow, where the time went, and the three things to look at first.

  • Will this index help?

    Test an index on a 12-million-row table before you build it, read the cost it reports, and know what a hypothetical index cannot tell you.

  • What does this table do?

    Read a table you did not create from its constraints, indexes, triggers and access before you touch a row in it.

  • Reading the stats

    Know which numbers on Seqora's pages are estimates and which are counters, what correlation, n_distinct, HOT updates and idx_scan mean, and when to worry.

  • A schema you did not write

    Spend the first hour with an inherited database well: the diagram, the hubs, the three schema reports, three tables, a first query, and what to write down.

  • What an index page tells you

    Read an index page: how its entries are ordered, which queries it serves, what every insert pays for it, and when to drop one nobody uses.

  • What a sequence page tells you

    Read a sequence page: how many values are left and when they run out, whether the table has got ahead of it, and what widening an integer column costs.

  • What a view page tells you

    Read a view page: where every column comes from, what breaks if you change it, whose permissions it runs with, and how old a snapshot is.

  • What a function page tells you

    Read a function page: how to call it, who can run it and as whom, what it promises the planner, what it touches, and the SECURITY DEFINER fix.

  • Why does this DELETE take three minutes?

    See what PostgreSQL does on a DELETE when foreign keys point at the row, where Seqora shows it, and the one CREATE INDEX that ends it.

  • Is my JSONB query using the index?

    Tell from the Plan tab whether a GIN index answered your JSONB query, why ->> never can, and which rewrite or index fixes it.

Doing

  • Connect

    Add a PostgreSQL, MySQL, MariaDB or SQLite connection, place it in a workspace and environment, and decide when it may write.

  • Run, cancel, and transactions

    Run one statement or a whole script, stop a query that is taking too long, and hold a change in a transaction until you have checked it.

  • Edit data

    Change, add and delete rows in the grid, review the SQL Seqora will run, and apply it in one transaction.

  • Design a schema change

    Draw a new table, column or foreign key on the ER diagram, read the SQL and its locks as you go, then check, dry-run and apply it.

  • Export

    Get rows out of a result or a table as CSV, JSON or INSERT statements, copy them in six formats, and export the ER diagram.

  • History and SQL files

    Find a query you ran last week, know what Seqora keeps about it, and keep the SQL you care about as .sql files.

  • Keyboard and the command palette

    Reach every command from the palette, learn the default shortcuts on macOS and Windows, and remap the ones you want.

Every panel

  • Sidebar

    The sidebar's three views, workspaces and environments, the connection menu, the explorer tree and its filter.

  • Tabs and panes

    The tab strip, tab groups and their menu, splitting a pane right or down, reopening closed tabs, and what happens when you quit.

  • Connection dialog

    Every field, chip and switch in the two steps of adding a connection, with the text each one shows.

  • Data grid

    The table grid's toolbar, the Filter rows syntax, sorting, columns, saved views, paging, Count and the Pending changes bar.

  • Value inspector

    What the value inspector shows for a JSON, timestamp, UUID, binary or enum cell, and the column facts it reads on each engine.

  • SQL editor

    The SQL editor's buttons and keys, the lock, the status footer, transaction controls, completion, saving, and what each engine refuses.

  • Result pane

    The pane under the SQL editor: the Result and Plan switch, result sets, run details and notices, the row cap, exports and Copy as.

  • Plan tab

    Every part of the Plan tab: header, lenses, row flow notation, table wheels, time strip, node inspector, findings and their actions.

  • Object pages

    The frame every object page shares, what Free shows and Pro adds, the sections of each kind, the table and schema reports, and which engines have which.

  • ER diagram

    Opening the ER diagram, what it draws, its toolbar and inspector, where the layout is kept, and the Export diagram options.

  • Design workbench

    The schema design canvas: its toolbar and menus, column toggles, drawing links, the inspector, the SQL pane with risk tags, and saved designs.

  • Review dialogs

    The four places Seqora stops before a write: unlocking, high-risk SQL, staged row edits, and applying a schema design.

  • Settings

    Every setting in Seqora's eleven categories, with its choices and its default.

  • Terminal

    The terminal panel inside Seqora: how to open it, which shell it runs, its settings, and why it has no link to your database.

  • Status bar

    What the status bar at the bottom of the window shows: the connection and its lock, row counts, selection sums, diagram zoom.

The plan, node by node

  • Seq Scan

    What a Seq Scan reads, the kept-to-read ratio that tells you it is the problem, and the index that replaces it.

  • Index Scan

    How an Index Scan fetches rows, why 206,880 cheap lookups add up, and what the table's physical order does to each one.

  • Index Only Scan

    When an index answers the query alone, what Heap Fetches means, and why VACUUM is the fix.

  • Bitmap Heap Scan

    The two-node scan for the middle ground, what a lossy bitmap costs, and how to read the exact and lossy page counts.

  • Nested Loop

    The join that runs its inner side once per outer row, why it was right for 612 rows and wrong for 206,880, and the one fix.

  • Hash Join

    The join that reads each side once, what Batches above 1 means, and when to raise work_mem for it.

  • Merge Join

    The join that walks two sorted inputs together, when the order comes free, and when it is paying for a Sort it did not need.

  • Sort

    The three sort methods EXPLAIN prints, what Disk against work_mem tells you, and the index that removes the Sort altogether.

  • HashAggregate

    How GROUP BY is computed by hashing, why the number of groups is what matters, and when GroupAggregate is the cheaper plan.

  • Limit

    When a Limit stops the work early and when the work happens anyway, with the index and the paging pattern that make it cheap.

  • CTE Scan

    When a WITH query is computed once and kept, when it is folded into the main query instead, and why the sample's web_orders has no node at all.

  • Gather

    Where parallel workers hand their rows back, Workers Planned against Workers Launched, and when a parallel plan is slower than the serial one.

  • WindowAgg

    How rank() and its relatives are computed, why each window ordering costs a sort, and how to make windows share one.

  • Materialize

    The node that keeps its input for rescanning, when it is doing its job under a Nested Loop, and when the loop count makes it the problem.

  • Rows Removed by Filter

    The line that counts rows read and then thrown away, what it says under a Seq Scan and an Index Scan, and how to make it zero.

  • Loops

    The figure that makes every row count and time in EXPLAIN ANALYZE a per-run average, and how the Plan tab multiplies it back out.

  • Buffers

    The page counts under each node, hit against read, what temp means, and why they are the figure to compare between two runs.

  • Estimated rows

    The planner's bet against the receipt, how to find the node where an estimate first goes wrong, and the three ways to correct it.

Other engines

  • MySQL, MariaDB and SQLite

    Know what works the same on all four engines, what differs on MySQL, MariaDB and SQLite, and the quirks of each, from the Plan tab to design mode.

Found a bug, missing a feature, or just curious? Write to me. Every email lands in my own inbox, not a ticket queue.