Your first query in two minutes

In this tutorial you start a Postgres server to practice on, connect Alcuin to it with a URL, and run your first queries. You need Alcuin installed and Docker running.

Start a database to practice on

Run this in a terminal:

docker run --name alcuin-tryout -e POSTGRES_PASSWORD=tryout -e POSTGRES_DB=tryout -p 5432:5432 -d postgres:18

Docker starts Postgres 18 with an empty database called tryout, listening on port 5432 of your computer.

Note

If another Postgres server already uses port 5432, Docker refuses to start this one. Change -p 5432:5432 to -p 5433:5432, and use 5433 in the URL below.

Connect with a URL

Paste this into the box at the top of Alcuin’s launcher, then press Return or choose Connect:

Paste the URL into the box at the top.

postgres://postgres:tryout@localhost:5432/tryout

Each part of the URL is one thing Alcuin needs:

Part	Here	What it is
postgres:	postgres:	the scheme; postgresql: works too
user	postgres	the role you sign in as
password	tryout	that role’s password
host	localhost	the computer the server runs on
port	5432	the port it listens on; 5432 if you leave it out
database	tryout	the database to open

Alcuin opens the database on Home. Because tryout is empty, Home starts with This database is empty. Start with…, and the Explorer on the left has no tables yet.

The connection is now under Recent in the launcher. To keep it for good, choose Save beside it there. Connection URLs covers the rest of what a URL can say, such as sslmode.

If it does not connect

The launcher says which step failed, with the details under it. The heading is one of these:

• Couldn't reach the server: nothing answered at that host and port. Check that the container is running with docker ps, and that the port in the URL matches the one Docker published.
• Couldn't sign in: the server answered, but refused the user, the password or the database name. Check all three against the docker run line.
• Couldn't set up encryption: the TLS settings did not match the server’s. See TLS and sslmode.
• The server refused the connection: the server is there, but is still starting up, shutting down, or has no free connections. Right after docker run, wait a few seconds and connect again.

Fix the URL and paste it again.

Make a table and query it

1. Open a query tab with ⌘T on macOS or Ctrl+T on Windows and Linux. Home’s New query button does the same.

2. Type this script:

   CREATE TABLE notes (
     id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
     body text NOT NULL,
     done boolean NOT NULL DEFAULT false
   );
   
   INSERT INTO notes (body) VALUES
     ('Water the plants'),
     ('Book the dentist'),
     ('Return the library books');
   
   SELECT * FROM notes;

3. Run the whole script with ⌘⇧↵ on macOS or Ctrl+Shift+Enter on Windows and Linux.

Alcuin runs each statement in turn and keeps one result per statement. It shows the last one first: the three rows of notes. The notes table appears under Tables in the Explorer.

Now run a single statement. Add a line at the end of the tab:

SELECT id, body FROM notes WHERE NOT done ORDER BY id;

With the cursor on that line, press ⌘↵ on macOS or Ctrl+Enter on Windows and Linux. Run takes the statement your cursor is in, not the whole tab. The result shows the three rows, with how many rows came back and how long the query took.

You have connected and run your first queries. Next, take a tour of the workbench, then make your first safe edit to the notes table.

Connect your own database

When you are ready to leave the tryout database:

• Connect to a hosted provider, such as RDS, Cloud SQL, Supabase or Neon.
• Set up TLS for a server that needs encryption.
• Bring your connections from another tool, such as pgAdmin or DBeaver.

To remove the tryout server when you are done, run docker rm -f alcuin-tryout.