ORM Studio

Configuration

Configure Axil Studio - axil run defaults, every StudioServer option incl. allowedHosts, maxBodyBytes, openBrowser and cwd, and the security model.

5 min readUpdated DocumentationEdit this page
On this page7

Under axil run Studio needs no configuration: everything comes from package.json and .env. This page covers those defaults, the options for running StudioServer yourself, and how Studio protects your machine.

Defaults under axil run

SettingValue
portPORT from .env (default 3000) plus 1
host127.0.0.1
appPortPORT from .env, default 3000
appNamename from package.json, otherwise axiljs-app
dbDriver / dbFilesqlite and DATABASE_FILENAME, when it is set
dbDriver / dbUrlpostgres or mysql and DATABASE_URL, picked from the URL prefix
enableQRtrue
Other optionsTheir defaults (below)

To change the Studio port, change PORT. The CLI has no flags for the other options; use the programmatic API if you need them.

Running Studio programmatically

@axiljs/studio exports StudioServer and its types (StudioConfig, StudioData, RouteInfo, TableInfo, ColumnInfo, TableSchema, ForeignKeyInfo, IndexInfo, RowFilter, RowQuery).

TypeScript
TS
1import { StudioServer } from '@axiljs/studio'
2
3const studio = new StudioServer({
4  port:     3001,
5  host:     '127.0.0.1',
6  appPort:  3000,
7  appName:  'my-api',
8  dbDriver: 'sqlite',
9  dbFile:   './dev.db',
10  enableQR: true,
11  openBrowser: false,
12})
13
14await studio.start()
15console.log(`Studio on port ${studio.getPort()}`)
16
17// later
18await studio.stop()

Methods

MethodDescription
start()Connects to the database (retrying in the background if it isn't ready), collects data, listens, prints the URL and, unless openBrowser is false, opens the browser
stop()Closes the HTTP server and the database handle or pool Studio opened
getPort()The port actually bound (useful with port: 0)
setDriver(driver, driverType)Use an existing database driver instead of letting Studio connect

StudioConfig options

portnumberrequired

Port Studio listens on. 0 picks a free port; read it with getPort().

hoststringrequired

Address to bind, for example '127.0.0.1'. It is also always accepted as a Host header value.

appPortnumberrequired

Port of your app. The app URL, the request proxy target, the realtime URLs and the app QR code all use http://localhost: plus this port.

appNamestringrequired

Shown in the sidebar, page title and breadcrumbs, and used to name exported collections.

enableQRbooleanrequired

Required by the type. QR codes are currently always generated, so this flag does not change behavior.

dbDriverstring

'sqlite', 'postgres' or 'mysql'. Without it Studio does not connect to a database.

dbFilestringdefault: './dev.db'

SQLite file, resolved against cwd (absolute paths are used as-is). Opened read-only with better-sqlite3.

dbUrlstring

PostgreSQL (pg) or MySQL (mysql2) connection URL.

allowedHostsstring[]default: []

Extra Host header names (host name only, no port) Studio answers to, for example a LAN name. localhost, 127.0.0.1, [::1] and host are always allowed. Any other host gets 403 Invalid Host header. CORS is granted to the same set of hosts.

maxBodyBytesnumberdefault: 1048576

Maximum POST body size for /api/studio/query and /api/studio/proxy (1 MB by default). Larger requests get 413.

openBrowserbooleandefault: true

Open the Studio URL in the default browser on start().

cwdstringdefault: process.cwd()

Project directory. Studio scans cwd/src for routes and resolves dbFile against it.

intentPathstringdefault: '/__axil/studio/intent'

Path on the app that serves the runtime report for the Intent view. Must match intentEndpoint({ path }). New in 0.3.5.

Attaching your own driver

In a single process you can hand Studio an existing driver instead of a connection string:

TypeScript
TS
studio.setDriver(driver, 'sqlite') // or 'postgres' / 'mysql'

The driver must provide query(sql, params) returning { rows } (and optionally affectedRows). If it also provides queryReadOnly(sql), the SQL console uses that method; otherwise it calls query.

Warning

With your own driver, Studio's read-only transaction and read-only SQLite handle don't apply: only the statement-type and OUTFILE/DUMPFILE checks protect the database. Pass a driver on a read-only connection, or implement queryReadOnly. Under axil run this doesn't apply: your app runs in a child process, so Studio always opens its own read-only connection.

Security

Studio has no login. It is safe because it is local and read-only:

  • Loopback by default: axil run binds Studio to 127.0.0.1, so other machines can't connect.
  • DNS-rebinding protection: requests whose Host header isn't localhost, 127.0.0.1, [::1], the bind host or an allowedHosts entry are rejected with 403. This stops a public website whose domain re-resolves to 127.0.0.1 from reading Studio.
  • Restricted CORS: Access-Control-Allow-Origin is only sent back to origins on those same hosts, never *. Other websites can't read Studio's responses.
  • Proxy guarded: POST /api/studio/proxy only accepts JSON bodies (which forces a CORS preflight) and only ever calls your app on localhost, so it can't be used to reach other hosts.
  • Read-only data access: the database browser only runs SELECT/COUNT(*) with checked, quoted identifiers and bound values; the SQL console only accepts read statements and runs them read-only (see SQL console).
  • Body limits: POST bodies above maxBodyBytes are rejected with 413.
  • Safe rendering: the app name and all data are inserted as text, not HTML.

Danger

Never expose Studio on a public network or run it in production. If you bind it to a LAN address, add only names you control to allowedHosts.

Caching and refresh

  • Routes and tables are collected on demand and cached for 5 seconds on the server.
  • GET /api/studio/data always re-collects.
  • The browser reloads data every 30 seconds while the tab is visible, and on Refresh data.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY