Use local PostgreSQL for a development App

New Apps use the Nexia sandbox database by default. To store one App's development data in PostgreSQL on your computer, complete this setup before that App's first nexia dev or database migration. This command does not move an App already allocated on the managed database. You need a connected App folder and an active sandbox prepared in Console Development. If the App is not registered yet, nexia db local registers its metadata first, without requesting runtime execution.

nexia db local does not install or start PostgreSQL or create the database. Inside the dedicated database you provide, it creates exactly two App logins (migrator and runtime), the App schema, and key-only tables containing Core IDs required by App foreign keys. It does not copy Core names or business rows. Your local administrator password is not sent to Nexia or stored in the App connection file.

Existing server and DBeaver

1. Confirm that PostgreSQL is already running on your computer. DBeaver is a client, not the database server.
2. In DBeaver, connect to the server's existing postgres database with an administrator account. Use 127.0.0.1 and the server's actual port (often 5432).
3. Open the SQL editor and create an empty database dedicated to this App. Give each App a different database name.

CREATE DATABASE nexia_app;1

4. Connect DBeaver to nexia_app to confirm it exists. Skip creation if you already have an empty database dedicated to this App. The administrator account used in the next step must be able to create PostgreSQL login roles and a schema.

The same procedure works whether PostgreSQL was installed through a macOS service, a Linux package, or another local installer. What matters is that the CLI can reach it through a loopback address on the computer running the CLI.

Bind the App to the local database

From the App folder, set the connection values for your server. This macOS/zsh or Linux/bash example prompts for the password rather than putting it in shell history. Adjust the port, database name, and administrator account to match your setup.

export PGHOST=127.0.0.1 PGPORT=5432 PGDATABASE=nexia_app PGUSER=postgres
printf 'PostgreSQL administrator password: '
read -rs PGPASSWORD
printf '\n'
export PGPASSWORD
nexia db local
unset PGPASSWORD
nexia dev12345678

On Windows PowerShell, run the equivalent setup from the App folder. Read-Host accepts the password without displaying it:

$env:PGHOST = '127.0.0.1'
$env:PGPORT = '5432'
$env:PGDATABASE = 'nexia_app'
$env:PGUSER = 'postgres'
$secret = Read-Host 'PostgreSQL administrator password' -AsSecureString
$env:PGPASSWORD = [System.Net.NetworkCredential]::new('', $secret).Password
nexia db local
Remove-Item Env:PGPASSWORD
nexia dev123456789

The CLI accepts only 127.0.0.1 or ::1 for PGHOST. PGUSER is your local database administrator, not the App runtime account. Clear the password from your shell after setup.

nexia db local finishes after initial setup. .nexia/local-database.json stores only App, database, and loopback settings, without passwords; do not commit it. Keep terminal 1 running nexia dev so its authenticated tunnel can connect the sandbox App to your PostgreSQL server. In terminal 2, from the same App folder, run migrations:

nexia db migrate
nexia db status12

Rerun nexia db local when the App needs new Core reference IDs. Existing IDs remain so local App foreign keys keep working. If nexia dev or PostgreSQL stops, the App loses database access until they restart. Local mode currently rejects db reset and db fresh; migrate, status, rollback, and refresh use the selected local database.

No PostgreSQL server installed

Docker is optional. This example publishes PostgreSQL port 5432 from the container as 127.0.0.1:55432 on your computer. Both nexia db local and DBeaver connect to the computer's address and published port, not the container name or internal port. Run it from the App folder in macOS/zsh or Linux/bash:

printf 'Local PostgreSQL administrator password: '
read -rs POSTGRES_PASSWORD
printf '\n'
export POSTGRES_PASSWORD
docker run -d --name nexia-local-pg \
  -e POSTGRES_PASSWORD -e POSTGRES_DB=nexia_app \
  -p 127.0.0.1:55432:5432 \
  -v nexia-local-pg-data:/var/lib/postgresql/data \
  postgres:17
docker exec nexia-local-pg pg_isready -U postgres -d nexia_app12345678910

Wait until pg_isready reports that PostgreSQL accepts connections. Docker creates POSTGRES_DB=nexia_app only when it first initializes a new data volume. An existing volume keeps its original database and password. Then bind the App:

export PGHOST=127.0.0.1 PGPORT=55432 PGDATABASE=nexia_app PGUSER=postgres
export PGPASSWORD="$POSTGRES_PASSWORD"
nexia db local
unset POSTGRES_PASSWORD PGPASSWORD
nexia dev12345

For an existing PostgreSQL container, run docker port <container-name> 5432/tcp to find the port published on your computer. Use that port for PGPORT and DBeaver. If the container publishes no host port, this CLI's loopback connection cannot reach it; configure a published loopback port while preserving the data volume. In DBeaver, enter Host 127.0.0.1, Port 55432 (or the actual published port), Database nexia_app, User postgres, and the password chosen when the container was initialized. Use docker start nexia-local-pg after stopping this example container; its named volume retains the App data.

On Windows PowerShell, you can start the same Docker database with a single-line command. After entering the password, run the following from the App folder; it uses the same connection variables as the PowerShell example above, with PGPORT=55432:

$secret = Read-Host 'Local PostgreSQL administrator password' -AsSecureString
$env:POSTGRES_PASSWORD = [System.Net.NetworkCredential]::new('', $secret).Password
docker run -d --name nexia-local-pg -e POSTGRES_PASSWORD -e POSTGRES_DB=nexia_app -p 127.0.0.1:55432:5432 -v nexia-local-pg-data:/var/lib/postgresql/data postgres:17
docker exec nexia-local-pg pg_isready -U postgres -d nexia_app
$env:PGHOST = '127.0.0.1'
$env:PGPORT = '55432'
$env:PGDATABASE = 'nexia_app'
$env:PGUSER = 'postgres'
$env:PGPASSWORD = $env:POSTGRES_PASSWORD
nexia db local
Remove-Item Env:POSTGRES_PASSWORD
Remove-Item Env:PGPASSWORD
nexia dev12345678910111213

When the CLI runs inside an App development container, that container's 127.0.0.1 is not your computer. For this workflow, run the CLI and nexia dev on the computer that can reach PostgreSQL through its loopback port. This developer-local mode does not register another computer's database address or a customer private-network database.

Inspect data with DBeaver

After setup, connect DBeaver to the same 127.0.0.1, port, and nexia_app database to query App tables and import data. You can use your local administrator account, while the App itself uses the restricted runtime login created by nexia db local. App tables live in a dedicated dev_... schema, not public; show that schema in DBeaver's navigator.

Verify the connection

nexia db local should report that the local App database is ready. Keep nexia dev running until it reports the local PostgreSQL tunnel is connected. In another terminal, nexia db status should return the App migration status; after nexia db migrate, check that the App tables appear in the dev_... schema in DBeaver.

See Data model and migrations for App tables and database command recovery.

Related update and public source

• Local database connection update
• Public CLI database command documentation