Files, drafts and history

pgjumbo keeps your SQL in three places. A Query Tool tab can belong to a .sql file that you open and save. Every open tab is also kept as a draft, so your tabs come back after you quit or after a crash. And every query you run is written to the server’s history, where you can search it and run it again.

Open a .sql file

Choose File▸Open… (⌘ O (Ctrl+O on Windows and Linux)), or click Open SQL file… on the start page. Your system’s Open SQL File dialog appears; it shows SQL files first and has All files too. Files also open from the start page’s recent files and from the Library’s My scripts.

The file opens in a Query Tool tab named after it:

What is in front when you open the file	Where the file opens
An empty Query Tool tab that has no file	In that tab.
Any other Query Tool tab	In a new tab on the same server and database.
No Query Tool tab in front; a server, database or object selected in the Explorer	In a new tab on that object’s database, or on the maintenance database when the server itself is selected. For a server that is not connected, on its maintenance database.
The start page (Open SQL file…)	In a new tab on the server you connected to last, or the first server in the Explorer, on its maintenance database.

File▸Open… is greyed out while no Query Tool tab is in front and nothing is selected in the Explorer. On the start page, Open SQL file… is greyed out until you have added a server, because a file always opens on one. When the new tab’s server is not connected, the tab opens anyway and waits for it, as a restored tab does. To run the file on another database, change the tab’s database in the toolbar (see The Query Tool).

• 1 The tab carries the file’s name, then the database it runs on: monthly-report.sql · shop. Hover over it to see the file’s whole path, the database and the server.
• 2 A dot after the name means the tab has changes that are not in the file yet. It goes away when you save.
• 3 The History tab, beside Messages, lists what you ran on this server.

What pgjumbo can open

The file is	What happens
UTF-8, with or without a byte order mark	It opens.
UTF-16 with a byte order mark (little or big endian)	It opens.
In any other encoding (Latin-1, Windows-1252…)	It does not open: “name is not UTF-8 or UTF-16 text. Convert it to UTF-8 and open it again.”
Larger than 16 MiB	It does not open: “name is larger than 16 MiB, too large for the editor.”
Gone, or not readable	It does not open: “Could not open path:” and your system’s reason.

A file that cannot be opened shows its reason in a message titled The file could not be opened.

Line endings stay as they were. A file with Windows line endings (CR LF) shows ordinary line breaks in the editor and is written back with CR LF; a file with Unix line endings is written back with LF. The encoding stays too: a UTF-8 file with a byte order mark keeps it, and a UTF-16 file stays UTF-16. A new file is saved as UTF-8 without a byte order mark, with LF line endings.

The UTF-8 in the status bar

The UTF-8 at the right of the status bar is the encoding pgjumbo uses to talk to the server. It does not describe the file.

Save a tab to a file

Menu item	Keys	What it does
File▸Save	⌘ S (Ctrl+S on Windows and Linux)	Writes the tab’s text to its file. A tab that has no file yet shows the Save SQL File dialog, offering the name <database>.sql.
File▸Save As…	⇧ ⌘ S (Ctrl+Shift+S on Windows and Linux)	Always shows the Save SQL File dialog, opened in the file’s folder with its name filled in. From then on the tab belongs to the file you chose.

Once the file is written, the result bar says Saved and the file’s name for about four seconds, and the tab takes the file’s name. If it cannot be written, the same place says Could not save: and the reason.

pgjumbo writes the whole text to a temporary file next to yours, then puts it in place of the old one, so a failed save never leaves half a file behind. The file keeps its permissions, and saving through a symbolic link writes the file the link points to. Save writes without a dialog only to the file the tab was opened from or saved to, including the file of a restored tab. The window itself can never name a file: every other path comes from a dialog you answered.

When you have changed rows in the results

While a tab has changed rows waiting to be saved, ⌘ S (Ctrl+S on Windows and Linux) and File▸Save save those rows to the database, not the tab to its file; they are greyed out while the tab is not connected or is running something. File▸Save As… still saves the file. A data tab has no editor and no file: there Save As… is always greyed out, and Save is greyed out until you change a row.

Open a recent file

The start page lists the last 10 .sql files you opened or saved, newest first. It shows when no tab is open and nothing is selected in the Explorer (see The pgjumbo window). There is no list of recent files in the menu bar.

• 1 Open SQL file… shows the Open dialog.
• 2 Each file shows its name and the folder it is in; hover to see the whole path. Click it to open it in a new tab, on the server you connected to last (or the first server in the Explorer) and its maintenance database.
• 3 × takes the file off the list. The file itself stays where it is.

A file that is no longer where it was says Not found and is greyed out; remove it with ×. The whole list is greyed out until you have added a server. With no files yet, the section says “The .sql files you open or save show here.”; if pgjumbo cannot read the list, it says “The recent files could not be read.”

Files you open from the Library’s My scripts join the list too, and so do scripts you save to a file from a Script menu or from Generate Scripts (see Scripts), because they go through the same Save SQL File dialog.

Your tabs come back

pgjumbo keeps every Query Tool tab as a draft while you work: its text, where the cursor is, its server and database, its file and whether it has changes the file does not have. It also remembers the tabs’ order, which one was in front and which were pinned. A draft is saved half a second after each change, and at once when a tab closes. Drafts live in pgjumbo’s own database on your computer (see Where pgjumbo keeps your data).

Quitting never asks about unsaved tabs. The next time you start pgjumbo, the tabs are back as you left them, including changes you had not saved to a file: such a tab still shows its dot.

What does not come back: results, messages, an open transaction, session settings, and data tabs, which close with the window.

• 1 The tab is back with its text, on the same server and database.
• 2 A restored tab does not connect by itself. The banner says Connect to server to run queries in this tab. Click Connect, or connect the server in the Explorer: every restored tab of that server then opens its own connection.
• 3 The server in the Explorer is not connected yet.

If you deleted the tab’s server meanwhile, the tab says “This tab’s server was deleted. Its SQL is still here to copy.” A tab holding more than 16 MiB of SQL is not kept as a draft, and nothing tells you so; save such a tab to a file.

Close a tab with unsaved work

You close a tab with its ×, with File▸Close Tab (⌘ W (Ctrl+W on Windows and Linux)), or from the tab strip’s right-click menu (see Tabs). A tab that belongs to a file and has changes the file does not have asks first.

• 1 Cancel keeps the tab open.
• 2 Don’t Save closes the tab and drops the changes. The file stays as it was.
• 3 Save writes the file, as File▸Save does, then closes the tab. It is the default: Enter chooses it. If the file cannot be written, the tab stays open.

The same question comes up, worded for rows, when a tab has changed rows that are not saved. When you close several tabs at once, each one that has unsaved work asks in turn, and Cancel stops closing the rest.

A tab without a file closes without asking

A Query Tool tab that has no file (one called Query 1, Query 2…) closes at once, and its text goes with it: its draft is deleted. Save it to a file first, or keep it as a snippet, if you want it again. What you ran from it stays in the History tab.

The History tab

Every Query Tool tab has a History tab beside Messages. It lists the queries run on the tab’s server, from every tab and every database there, newest first. Data tabs have no History tab.

What goes into the history:

• Each Run, Run Statement and Run Script, whether it succeeded, failed or was cancelled: the text that ran, the selection when there was one.
• The SELECT of a data tab.
• A run on several databases: one entry on each server it ran on, naming the database, or how many databases there were.

Explain and Explain Analyze are not recorded. Each server keeps its last 10,000 runs; older ones go as new ones come. A script larger than 1 MiB is not kept.

• 1 Search the server’s history. Every word you type must match the start of a word in the query, in any case: upd ord finds UPDATE orders SET …. Punctuation is ignored.
• 2 Each entry shows an icon (succeeded, failed or cancelled), the query on one line, then when it ran (the time for today, the date and time for earlier days), the database, how long it took and what it did: so many rows, done, failed with its SQLSTATE, or cancelled. The newest entry is selected at first; click another to see it on the right.
• 3 Open in editor puts the query in this tab’s editor, selected: in place of the text when the editor is empty, otherwise below it. Undo takes it out again.
• 4 Run again does the same, then runs the query. It runs in this tab, on this tab’s database, which may not be the database the entry names, and a server that asks before destructive statements asks again. It is greyed out while the tab is not connected or is running something.
• 5 Copy puts the query on the clipboard; the result bar says Copied the query.
• 6 The bin deletes the entry from the history at once, without asking.
• 7 When a password in the query was masked, a note says so and Run again is greyed out.

Under the buttons, a line gives the full date and time, the database and the outcome; the whole query is below it.

In the list	What it does
↑ ↓	Selects the entry above or below.
Page Up Page Down	Moves ten entries.
Enter, or a double-click	Open in editor.

The list loads more entries as you scroll. With nothing run yet it says “Queries you run on server appear here”; when a search finds nothing, “No query matches” and your words.

Clear the history

Clear history… at the right of the search field forgets every query run on the server, whatever the search shows. It is greyed out while the list is empty. It asks first:

Clear history cannot be undone

Clear history deletes the whole history of the server, for every tab and database. To forget one query, select it and use the bin instead.

Passwords are masked

Before a query goes into the history, pgjumbo replaces what looks like a password with ********:

Written as	Example	Kept as
A string right after the word PASSWORD, with or without = (also OPTIONS (password '…'))	ALTER ROLE app PASSWORD 'tiger-lily'	PASSWORD '********'
password= inside a string, as in a connection string	CONNECTION 'host=db1 user=rep password=s3cret'	password=********
user:password@ in a URI inside a string	'postgresql://app:s3cret@db1/shop'	app:********@

It looks inside dollar-quoted bodies too (a DO block, a function’s body) and skips comments. Anything else is kept as you wrote it: a secret written another way, such as a key passed to a function, stays readable in the history. Delete that entry with the bin.

An entry with a masked password cannot run as it is, so Run again is greyed out, and its tooltip says “Put the password back in the editor first”. Click Open in editor, type the password in place of ********, and run it.

The history is the only place that masks. The tab’s draft keeps the editor’s text as you typed it, password included, until you change the text or close the tab, and a file you save holds what the editor holds.