Skip to content
Tablewalk

Getting started

This page gets you from nothing to a running database browser, then to a running App.

Run the browser

Section titled “Run the browser”

The current release is tablewalk 0.8.1. Use Node 24 or newer.

Terminal window
npx tablewalk --demo          # a throwaway sample database
npx tablewalk mydata.sqlite   # an existing SQLite file
npx tablewalk                 # start empty and add a connection in the browser

It serves http://127.0.0.1:4111; --port picks another port and --open opens a browser. There is no build step.

Database Driver
SQLite Built in (Node’s SQLite)
PostgreSQL pg
MySQL / MariaDB mysql2

Install pg or mysql2 beside tablewalk if your installation lacks it. An HTTP API with an OpenAPI 3 spec can also be read as a connection, in preview: npx tablewalk --openapi <spec> (HTTP sources).

Configure connections

Section titled “Configure connections”

Name your databases in a config file and pass it explicitly:

{
  "connections": [
    { "name": "local", "url": "sqlite:./mydata.sqlite" },
    { "name": "crm", "url": "${DATABASE_URL}" }
  ]
}
Terminal window
npx tablewalk --config ./tablewalk.json

Connections open lazily. ${VAR} reads the environment, and an unset variable is an error, so credentials stay out of committed files. PostgreSQL pool sizing and PgBouncer are covered in Performance; a shared cache and a search engine in Services.

Read-only by default

Section titled “Read-only by default”

Every read runs in a read-only transaction. Writes need "writable": true on the connection, which opens a separate writer; the adapter enforces it, not the UI. Updates and deletes need a complete primary key.

The database role is the boundary that always holds (a PostgreSQL superuser can step around a read-only transaction), so connect as a role that can only read:

-- PostgreSQL
CREATE ROLE tablewalk_reader LOGIN PASSWORD '…';
GRANT USAGE ON SCHEMA public TO tablewalk_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO tablewalk_reader;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO tablewalk_reader;


-- MySQL
CREATE USER 'tablewalk_reader'@'%' IDENTIFIED BY '…';
GRANT SELECT ON appdb.* TO 'tablewalk_reader'@'%';

tablewalk warns once on stderr when a read-only connection’s role could do more. The server binds to loopback; --host widens who can reach it, and host checks are not authentication. Apps that sign people in are covered in Sign-in, roles & data.

Your first walk

Section titled “Your first walk”
  1. Open a table and select a row.
  2. Follow a reference, or a reverse relationship to the rows pointing here.
  3. Edit the query bar to filter or sort.
  4. Walk back to restore the previous view, or copy the URL to share it.

More in Query language & MCP.

Your own App, from the package

Section titled “Your own App, from the package”

--scaffold-app drafts an App from a database’s schema, and the package alone is enough to run it:

Terminal window
npx tablewalk ./ops.db --scaffold-app ./ops-app
cd ops-app
npm install                                # tablewalk and TypeScript
npx tablewalk check --app .                # schema types, typecheck, validation
npx tablewalk --app .                      # serve it at /{app id}

It writes app.ts, resources.ts, views.ts, dashboard.ts, pages/, tablewalk-schema.d.ts (the database’s names, for the typecheck), tsconfig.json, package.json, a README and, for a SQLite file, a tablewalk.json naming it by a path from the App. It passes check as written; curate it from there. A save reloads the App; a change to what it grants, its sources or its sign-in needs a restart (reload and restart).

The App imports tablewalk/app, which resolves from the tablewalk its package.json installs; inside a tablewalk checkout it resolves to the checkout itself, so no package.json is written there. Cannot find module 'tablewalk/app' means neither is the case.

npx tablewalk docs lists the one-screen reference topics, from what an App serves to tablewalk check.

The sample Apps

Section titled “The sample Apps”

The sample Apps run from a source checkout:

Terminal window
git clone https://github.com/rbaljinder/tablewalk.git
cd tablewalk
npm install
node examples/databases/tick/seed.mjs /tmp/my-tick.db
npm run start -- --config /tmp/my-tick.db.json --app examples/apps/tick --open

The seed writes a SQLite database and /tmp/my-tick.db.json, a writable connection named tick; it refuses to overwrite either, so pick a fresh path to start over. The server opens Tick at /tick. Edit examples/apps/tick/app.ts and the page reloads. After each edit:

Terminal window
npm run start -- check --app examples/apps/tick --config /tmp/my-tick.db.json

check regenerates schema types, typechecks and validates the App against the database. For your own database, --scaffold-app ./my-app writes a starting App (Build with a coding agent). For production, tablewalk build bundles an App once (Build and deploy).

Where next

Section titled “Where next”