Skip to content

Make your first safe edit

In this tutorial you change one value in the notes table from your first query. You see the change staged, read the exact SQL before anything runs, commit it, and then throw a second change away.

Stage an edit

Section titled “Stage an edit”
  1. In the Explorer, double-click notes under Tables. The table opens on its Data tab.
  2. Double-click any cell in the row Book the dentist. The row panel opens on the right, with every field of that row.
  3. In the row panel, double-click the body field. An editor opens.
  4. Change the text to Book the dentist for Tuesday, then choose Set. You can also press ⌘↵ on macOS or Ctrl+Enter on Windows and Linux.

Double-click a cell, then the field in the row panel, type, and choose Set.

Nothing has been written to the database yet. The edit is a staged change:

  • The body field shows your new text, with was Book the dentist under it in smaller type.
  • The cell is outlined in the grid, and the tab title has a dot.
  • A bar under the rows reads 1 change not saved yet · 1 edit, with Discard changes, Review SQL and Commit 1 row change.
The notes table with one staged edit. The body cell of row 2 is outlined and reads Book the dentist for Tuesday, the row panel shows the new text with was and the old text under it, the notes tab has a dot, and the bar under the rows reads 1 change not saved yet · 1 edit, with Discard changes, Review SQL and Commit 1 row change.

A staged edit: four marks say it, and nothing has reached the database.

  1. The tab title has a dot.
  2. The cell is outlined.
  3. The field shows the new value, and the old one under it.
  4. The bar counts the staged changes.

You can stage more edits, on more rows, before you commit. They all go to the server together.

Review the SQL

Section titled “Review the SQL”

Choose Review SQL. The review opens with 1 change to notes. It lists the change as Update id 2. Beside it, under SQL that will run, is the transaction Alcuin sends:

The review of the notes table: 1 change to notes, a selected checkbox beside Update id 2 with body changed from Book the dentist to Book the dentist for Tuesday, Commit 1 change, and under SQL that will run the transaction from BEGIN to COMMIT, with a Copy button.

The review: the change on the left, the SQL that will run on the right.

BEGIN;
UPDATE public.notes
SET body = 'Book the dentist for Tuesday'
WHERE id = '2'
  AND xmin = '757'::xid;
COMMIT;

Your xmin number differs. It is the row’s version as Alcuin loaded it. The UPDATE matches the row by its primary key and that version, so it changes the row only if nobody else changed it since you loaded it. When it runs, the values are sent as bound parameters; the review shows them inline so you can read them.

How Alcuin protects your data explains what happens when the row did change.

Commit

Section titled “Commit”

In the review, choose Commit 1 change, or press ⌘S on macOS or Ctrl+S on Windows and Linux.

Alcuin runs the transaction and reads the rows again. The bar and the tab’s dot go away, and the row reads Book the dentist for Tuesday. The change is in the database now. A SELECT in a query tab returns the new text too.

Stage a change and discard it

Section titled “Stage a change and discard it”

Not every staged change has to be committed.

  1. Double-click the body field of the same row again, and change it back to Book the dentist. Choose Set.
  2. The bar reads 1 change not saved yet · 1 edit again. This time, choose Discard changes.
  3. Alcuin asks Discard staged changes? and says that nothing has run. Choose Discard changes.

The staged edit is gone, and the row still reads Book the dentist for Tuesday. Discarding never touches the database.

To put the old text back for good, stage the edit again and commit it.

On a production connection

Section titled “On a production connection”

Your tryout connection is a local one, so it lets you stage and commit. A connection marked production opens read-only:

  • A Production banner across the top of the window reads Read-only. Nothing you do here can change data.
  • Fields don’t open an editor, and rows can’t be deleted, so nothing can be staged.
  • To edit, choose Unlock editing… in the banner and confirm. Alcuin locks the connection again after 15 minutes, once no transaction is open, or sooner if your Safety settings say so.
The red Production banner across the top of the window, reading Read-only. Nothing you do here can change data., with an Unlock editing… button.

A production connection opens read-only.

Work on production covers unlocking, and environments covers how a connection gets marked production. To learn more ways to change rows, see edit rows.

Connect your own database

Section titled “Connect your own database”

You have staged, reviewed, committed and discarded a change. To do the same on your own data: