ORM Studio

Getting Started

Install @axiljs/studio, launch it with axil run on app port + 1, point it at SQLite, PostgreSQL or MySQL, and fix common startup problems.

4 min readUpdated DocumentationEdit this page
On this page7

Requirements

  • An AxilJS project run with axil run (from @axiljs/cli).
  • @axiljs/studio in the project.
  • For the database views, the driver for your database installed in the project: better-sqlite3 (SQLite), pg (PostgreSQL) or mysql2 (MySQL). Studio loads it at runtime; without it the database views stay empty and the terminal says which package is missing.

Install

New projects

Existing projects

Start the dev server

Launch output

Once Studio is listening, it prints its URL:

Terminal
[AxilJS Studio] http://127.0.0.1:3001

If the browser does not open, visit that URL yourself. http://localhost:3001 works too.

Ports

Studio always uses app port + 1. The app port is PORT from your .env, or 3000 when it is not set:

PORTAppStudio
not set30003001
400040004001
808080808081
Environment
ENV
PORT=4000

Database detection

Studio reads your .env and opens its own connection:

Environment
ENV
1# SQLite (a path relative to the project directory, or absolute)
2DATABASE_FILENAME=./dev.db
3
4# PostgreSQL
5DATABASE_URL=postgres://user:password@localhost:5432/mydb
6
7# MySQL
8DATABASE_URL=mysql://user:password@localhost:3306/mydb
VariableDriver
DATABASE_FILENAMESQLite (takes precedence when both are set)
DATABASE_URL starting with postgresPostgreSQL
DATABASE_URL starting with mysqlMySQL

The terminal reports the result, for example [Studio] Connected to SQLite: /path/to/dev.db or [Studio] PostgreSQL connection failed: ....

What Studio lists:

  • SQLite: every table except _migrations and SQLite's internal sqlite_* tables.
  • PostgreSQL: base tables in the public schema, except _migrations.
  • MySQL: tables in the current database, except _migrations.

Note

If the SQLite file does not exist yet (your app creates it on first start), Studio retries five times, two seconds apart. Opening a table later also triggers a new connection attempt.

Routes and realtime detection

Studio does not ask your running app for its routes. It scans the .ts and .js files under src/ (skipping node_modules) for calls such as:

TypeScript
TS
app.get('/health', handler)
router.post('/users', authenticate(jwt), validate({ body }), createUser)
this.delete('/users/:id', removeUser)

The first argument must be a string path starting with /. Later arguments become the middleware list and the handler name. WebSocket and SSE endpoints are detected the same way; see Realtime.

Troubleshooting

Studio skipped in the terminal

@axiljs/studio is not installed in the project. Run npm install -D @axiljs/studio and restart axil run.

No tables in Database, Schema or the SQL console

  • Check DATABASE_FILENAME or DATABASE_URL in .env.
  • Install the driver package (better-sqlite3, pg or mysql2). The terminal prints ... not installed — database browser disabled when it is missing.
  • For SQLite, start your app once so it creates the file, then press Refresh data.

"Can't reach your app" when sending a request

The Studio proxy could not connect to http://localhost: followed by your app port. Make sure the app is running (the sidebar shows App not running when it isn't).

Port already in use

Studio needs app port + 1 to be free. Change PORT so both ports are available:

Environment
ENV
PORT=3005
# Studio: 3006

"No routes discovered"

Studio only finds routes registered with a literal path on app, router or this inside src/. Routes built from variables or registered outside src/ are not listed.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY