Skip to main content
Every session can run its own PostgreSQL 16 server inside the session’s machine. It stays off until your app needs it, starts in about a second, and from then on the Database tab shows it. This page covers turning it on, connecting to it and managing it. To browse tables, edit rows or run SQL, see Browse, edit and query data. For the database a published app uses, see Production database and sign-in. Owner only People you share the session with don’t see the Database tab.
The Harbor bookings session with the Database tab in front. The tab strip reads Plan, Preview, Shell, Database with its ×, then the file tabs README.md and server.js and the round + button, with the GitHub, Share, Publish and files buttons at the right. The toolbar reads PostgreSQL 16.15 · 2 databases · up 3 h in small grey type on the left, shows the database picker pill with a blue dot, a database icon, the name forge and a chevron in the middle, and ends with Connect with a plug icon and the ⋯ Database actions button on the right. The left column has a Tables filter box above the list bookings 8, classes 3, instructors 3, members 6 and schema_migrations 1, with instructors selected and 5 tables · 1 ext at the bottom. Above the grid sits the view switch reading Data, Structure and SQL, with Data active and the table name instructors beside it. The grid toolbar shows Filter and a Search rows box on the left, and Refresh, Delete and Add row on the right. The column headers read id with a key icon, name, email and created_at, with their types uuid, varchar, varchar and timestamptz in small grey text. Three rows follow: Maya Chen, maya.chen@harbor.example; Oliver Brooks, oliver.brooks@harbor.example; and Sophie Laurent, sophie.laurent@harbor.example, each with a uuid and a created_at of 2026-10-27T20:30:21 cut off at the right edge. The footer reads 1–3 of 3 · 0 ms beside the Previous page and Next page arrows, with the page-size picker reading 100 rows on the right. The chat on the left shows the answered The agent has questions card and a Proposed plan card for Automatic class waitlist.

The toolbar holds the server summary, the database picker and Connect; the open table's rows fill the grid below.

​
Turn the database on

Nothing runs until something needs it, so a new session has no database server and no connection details. There are three ways to switch it on. The agent uses this database by default whenever a project needs one, rather than SQLite or an in-memory store unless you ask for one. It doesn’t switch the database on for projects that don’t need it. Alpha will:
  1. Start the session’s PostgreSQL and open the Database tab.
  2. Write the schema as a migration file in your project, and the sample classes as a seed script, so both can be recreated later.
  3. Point the app at DATABASE_URL rather than a hard-coded connection string.

​
Connect from your app

Once the database is on, every command the agent runs and every app it starts has these values in its environment. psql connects with no arguments, and your app should read DATABASE_URL.
The server listens on localhost inside the machine, so only the agent’s commands, the apps it starts and the Shell can reach it. Your own computer can’t connect to it. The role is a superuser, so CREATE EXTENSION and CREATE DATABASE work. To see the values for the database you’re looking at, click Connect in the toolbar. On a narrow workspace it shows as a plug icon only. Each row has a copy button.
The Connect to forge dialog, with an X to close it. Its text reads: PostgreSQL runs inside this session's sandbox and listens on localhost there — reachable from the agent's commands and anything it starts, not from your machine. Every shell command already has these exported, so psql just works and apps should read DATABASE_URL. A secret named DATABASE_URL overrides it with your own server. Below are six rows, each with a copy button: DATABASE_URL, its value postgresql://forge:forge@localhost:5432/f… cut off at the column's edge, PGHOST localhost, PGPORT 5432, PGUSER forge, PGPASSWORD forge and PGDATABASE forge. The bottom line reads PostgreSQL 16.15 (Ubuntu 16.15-0ubuntu0.24.04.1) on x86_64-pc-linux-gnu · up 3 h.

Connect shows the values the agent's commands already have.

To use a hosted PostgreSQL instead, add a secret named DATABASE_URL. Your value wins over the built-in one, and the agent uses it for the app.

​
Switch or create a database

The server can hold more than one database. The picker in the middle of the toolbar lists the session’s databases with their sizes, and a check marks the one in view. The default database is the one DATABASE_URL points at.
The database picker open below its pill in the middle of the Database tab's toolbar. The pill reads forge, with a blue dot, a database icon and an up chevron. The menu lists forge at 7.8 MB with a check mark, then postgres at 7.3 MB, then New database… with a plus icon.

The picker lists the server's databases with their sizes and checks the one in view.

1

Open the picker

Click the database name in the middle of the toolbar, then click New database…. The item appears only while the server is running.
2

Name the database

Type a name made of letters, digits and underscores, starting with a letter or an underscore, such as analytics. A name that’s taken shows “analytics already exists.” under the field.
3

Click Create

The new database is owned by the same role and opens in the tab at once.
The exported DATABASE_URL keeps pointing at the default database. To have an app use another one, copy its URL from Connect, or tell the agent which database to use. Below the session’s databases, a Production section lists the databases of apps you published from this session. Picking one shows that app’s production data, tagged prod. Alpha reads it from its own server, so the session’s machine isn’t woken for it. When a published app has a production database, the Database tab shows even while the session’s own database is off, and opens on production. Production database and sign-in covers that view.
If you don’t see a Production section, either nothing you published from this session has a database, or publishing isn’t turned on for your Alpha.

​
Export, import, reset or drop

The ⋯ button at the right of the toolbar (tooltip “Database actions”) holds the actions for the database in view. Reset and Drop carry its name, such as Reset analytics…. With a production database in view, the menu holds only Refresh. Production’s tables come from the app’s migrations or a push from the session.
Reset and drop can’t be undone. Reset empties every table, row and extension in the database, and the agent’s running apps lose their connections. Drop removes the database for good. Use Export SQL dump first if you might want the data back.
While a reset or an import runs, the tab locks the data and shows “Resetting database…” or “Importing SQL…”. The result appears on the left of the toolbar for a few seconds, such as “analytics was reset — every table is gone.” Click an error there to dismiss it.

​
What happens to your data?

The database lives on the machine’s disk, so it follows the machine. It never follows your app into production. Keep your schema in migration files and your sample data in a seed script, as the agent does by default. Then a reset, a fresh machine or production can be rebuilt from the project.

​
When the database isn’t available

The tab says why it can’t show data, and offers the fix when there is one.

​
Next steps

Browse, edit and query data

Filter rows, stage edits and save them in one transaction, or run SQL with completions.

Production database and sign-in

Fill production with migrations or a push from the session, and browse it here.

Add sign-in to your app

Let people sign in to your app, and see who has in the Auth tab.

The Shell

Open a terminal on the machine, where psql connects with no arguments.