Web console

The browser page of kdb serve - run SQL, see results as a grid or a chart, switch databases, check health, make backups and open this help.

• Category: Web console
• Keywords: console, web console, browser, pages, tabs, Home menu, SQL page, Dashboards, Data page, View data, Monitor panel, Settings page, right side, flyout, panel, pin, Samples, Databases panel, Tools panel, Purge trash, Delete all data, Terminal, activity log, log, Timers tab, New timer, Run now, Keep data for, object tabs, web folder, web_dir, KDB_WEB_DIR, console not installed, editor, Run, Run all, Ctrl+Enter, Ctrl+Shift+Enter, F1, history, grid, result grid, chart, candles, Export CSV, table list, health box, Check now, Backup now, database picker, New database, login form, Log out, token box, theme, dark, light, Help menu, Documentation, Examples, Keyboard shortcuts, About KDB, #sql, link with SQL, Try in console, dashboard
• See also: Dashboard page (many charts on one page), View data page (browse and edit rows), Keep data page (how long tables keep their rows), Monitor panel (memory, processor, caches), Settings page (data folder, old log, capacity, program files and users), Comments and suggestions, HTTP API overview (get), Run SQL over HTTP (/exec, /exp), Logins, tokens and roles over HTTP, Databases over HTTP (/api/databases), Health, info, check and backup over HTTP, kdb serve, Databases and the data folder

The web console is a web page inside kdb serve. Open it in a browser to write SQL, run it, and look at the results. It needs no internet and no other software. Its files are plain files in the folder web/ next to the kdb program, not inside the program (where kdb finds them).

Pick a page from the Home menu at the top left. The button shows where you are, for example Home / Dashboard.

The buttons down the right side open panels over the page: Monitor, Health, Samples, Databases, Tools and the Terminal (right side).

Comments and suggestions in the Help menu opens one more page: a form to send a message to whoever runs the server (feedback).

The page you were on last opens again when you come back.

• Start the server, then open http://127.0.0.1:9900 in Chrome, Edge or Firefox.
• Everything the console does goes through the HTTP API, so everything it can do, a program can do too.
• Tutorial: chapter 6, web console.

Command line: Start the server; the console address is on the second line

kdb serve --backups backups

Output:

KDB 0.2.0-dev
  console   http://127.0.0.1:9900
  data      ./kdb-data (from KDB_DATA_DIR; one folder per database)
  default   default (used when a request names no database)
  backups   backups/<database name> (from --backups)
  access    no token
  capacity  32 HTTP threads (default), 500 PostgreSQL connections (default), lock wait 5 s (default)
  lanes     reads using 100 ms of CPU (three times in a row) wait for one of 16 heavy slots, at most 16 HTTP in line (--lanes on)
  reads     32 reads run at once (the CPUs, at least 2; follows the CPU limit), the rest wait in line (--read-slots)
  commits   synced to disk before they are confirmed (--sync-commits always)
  time zone Asia/Katmandu (the computer's); also timers and backup schedules
  readers   read while a long trigger or CALL writes (--reader-yield on); idle open transaction rolled back after 30 s (default)
  memory    26.95 GB for the whole process (85% of the machine's memory); table data 512.0 MB of it (--memory)
  cpu       32 CPUs (the machine's); 16 query threads (half of the CPUs, follows the limit), limits checked every 10 s
  limits    statement timeout 1 min, result memory 1.00 GB, 5000000 groups, 32 statements per user
  safety    writes allowed; DROP TABLE kept 7 days (UNDROP TABLE); audit log on (SHOW AUDIT)
  logs      slow queries >= 1000 ms to ./kdb-data/_logs/slow_queries.jsonl; pg_stat_statements on; metrics at /metrics
  recovery  the default database is created when it is first used

Press Ctrl+C to stop.

Open the console

Syntax:

kdb serve [<database folder>] [--data-dir <folder>] [--port 9900] [--bind 127.0.0.1] [--backups <folder>] [--token <secret>]
http://127.0.0.1:9900/

• Keep the server window open while you use the console. Stop the server with Ctrl+C.
• From another computer, do not open the port to the network: use an SSH tunnel (ssh -L 9900:127.0.0.1:9900 you@server) and open http://127.0.0.1:9900 on your own PC (server security).
• The page only loads files from the KDB server itself (its Content-Security-Policy says so), and it cannot be put inside another site's page.
• The console files are read from the web folder when the browser asks for them. When that folder is missing, the server still runs and the API works; the page at / says the console is not installed and lists the folders KDB looked in. The banner of kdb serve says so too.
• Copying a new console into the folder shows at the next page load, with no restart. The browser keeps its copy only until the file changes (the server answers 304 Not Modified while it is the same).

HTTP: The console page is there (HEAD: only the headers)

HEAD /

Response:

HTTP 200 (text/html)

The screen

+-------------------------------------------------------------------------------------------+
| KDB [Home v]  Database [market v] New database   boss (admin) Log out  * Connected  Help   |
+-----------------------+----------------------------------------------------------+--------+
| OBJECTS       Refresh | [Run Ctrl+Enter] [Run all Ctrl+Shift+Enter] [History]  Rows | Monitor|
| [Tables 6][Views][Trig]|  1  SELECT time, open, high, low, close, volume          | Health |
| [Procs][Funcs][Timers] |  2  FROM ochl_day WHERE symbol = 'CITY';                | Samples|
|  > brokers     REL    |========================= (drag) ============================| Databa.|
|  > ochl_day    TS     | [1 SELECT time, ...] [2 Error]                           | ------ |
|  ...                  | [Grid][Chart]  message                      [Export CSV] | Tools  |
|                       |                                                          |Terminal|
|  > Indexes            |  #  time                      open   high ...            |        |
|                       |========================= (drag) ============================|        |
|                       | TERMINAL [All][Queries][Writes][Timers][Errors]  Pause Clear x|        |
|                       | 14:19:02.114 PG  10.0.0.5  market  3 ms  1 row  SELECT ...    |        |
+-----------------------+----------------------------------------------------------+--------+
| 19 rows | parse 0.05 ms  execute 0.34 ms  round trip 12 ms           Server 2026-09-11 14:19 |
+-------------------------------------------------------------------------------------------+

The lines between the editor, the results and the terminal can be dragged; the console remembers the sizes.

Editor

Write SQL here. Keywords, text and numbers get colors, and lines have numbers.

• Statements are split at ;. "The statement under the cursor" is the text between the ; before and after the cursor.
• The editor text is kept in your browser, so it is still there next time.
• With many statements, each result gets a tab (1 SELECT ..., 2 ...).
• When a statement fails, a red error bar shows the message. Its position (line 2, column 8) is counted in your editor, the line number turns red, and clicking the position moves the cursor there. The statements before the error ran and are kept: the error tab says Before it: 1 statement(s) ran and are kept.
• Statements like INSERT show their message (3 row(s) inserted) and the rows affected.
• After CREATE, DROP, ALTER or RENAME, the table list reloads by itself. After USE name; the database picker switches to that database.
• Ready statements to start with, with Insert and Run buttons, are in the Samples panel on the right. It opens by itself on your first visit.

The console runs each statement with POST /exec?compat=0&limit=<Rows>.

History

History lists the last 50 statements you ran, newest first, with the time. Click one to put it back at the end of the editor.

• The history is kept only in this browser.
• Passwords are never kept: PASSWORD 'secret' and the text in password_hash('...') and password_verify('...') are saved as '***'.
• Escape closes the list.

Results grid

The grid shows the rows of one result.

• The header shows the column's name and type (DOUBLE, TIMESTAMP, ...). Numbers are right-aligned.
• NULL shows as null. Times are UTC, as the API sends them.
• When the result was cut by the Rows limit, the bar says Row limit reached: showing the first N rows.
• The grid draws only the rows you can see, so it stays fast with a million rows.

Chart

Click Chart above a result. The console looks at the columns and picks the chart that fits best: candles for time, open, high, low, close (with volume bars when there is a volume column), a line for a time column with numbers, a bar chart for a text column with numbers, and so on. The button is off when no chart fits (a chart needs at least one number column).

The bar above the chart:

Chart types:

• Times on the chart are in your computer's time zone (for example Nepal time on a PC set to Nepal). The grid shows UTC.
• Big price series (100,000 bars) still zoom and move smoothly.
• The console remembers your chart settings for each statement, and whether you last used Grid or Chart.
• The chart follows the dark or light theme.

Example: A good query for candles (sample data: sample)

SELECT time, open, high, low, close, volume
FROM ochl_day
WHERE symbol = 'CITY'
ORDER BY time;

Result:

(first 5 of 19 rows)

Charts and dashboards

A chart you like can go on a dashboard: a page of several charts, each from its own query, that refresh by themselves. Click Add to dashboard on the chart bar, pick a dashboard (or A new dashboard) and give the panel a title. The dashboard opens with the new panel; click Save there to keep it. The dashboard page is explained in dashboards.

Example: Rows for a bar chart: shares traded per symbol (sample data: sample)

SELECT symbol, sum(quantity) AS shares
FROM trade_log
GROUP BY symbol
ORDER BY shares DESC;

Result:

(4 rows)

Export CSV

Export CSV downloads all rows of the shown result as a CSV file.

• It runs the statement again on the server with GET /exp (up to 1,000,000 rows, not only the rows in the grid). So it is offered only for SELECT, SHOW and EXPLAIN.
• The file name comes from the table after FROM, for example ochl_day.csv (else kdb-export.csv).
• Times are UTC. NULL is an empty field.

Object list

The left side lists the objects of the chosen database, one tab for each kind: Tables, Views, Triggers, Procedures, Functions and Timers. Each tab shows how many there are. The console remembers the tab you picked.

• Indexes are in the Tables tab, under the tables. Click Indexes to close or open that group.
• Click the small arrow of a view, trigger, procedure or function to see its statement. Open in editor puts the statement into the editor.
• A procedure or function also has Run on a timer...: it opens the timer form with CALL name(...) or SELECT name(...) filled in.

Folders. A database with many objects can be tidied into folders: + Folder at the top of a tab makes one, and you drag a table, view, trigger, procedure or function onto it. A folder exists in every tab, so floorsheet can hold the floor-sheet tables in the Tables tab and the floor-sheet procedures in the Procedures tab. Hover a folder's heading to rename (✎) or remove (×) it; removing a folder only puts its objects back in the plain list. Folders change nothing but this list: no name, statement or query is affected. They are saved in the table _console_groups of the database, so every browser sees the same folders; the first folder creates that table, which needs the admin role, and dragging needs the write role.

Tables

The list comes from GET /api/info. It also reloads every 30 seconds while the page is visible.

Timers

A timer runs SQL by itself on a schedule, for example CALL refresh_prices(); every 5 minutes, so a table stays up to date without anybody running anything. The server runs it, so it goes on when no browser is open. Full details: timers.

Schedules: every 30s, every 5m, every 2h, hourly, hourly :15, daily 16:00, daily 02:00,13:30, weekdays 11:00, monthly 1 02:00. The form offers the common ones as quick picks. Times are the server computer's local time.

• A run that is still going when the next one is due is skipped, never started twice.
• A timer belongs to the database chosen at the top, and runs with the rights of the user who saved it.
• Any user who may read the database sees its timers. Saving, changing, deleting and Run now need the admin role on that database, and each of them is written to the audit log.

Right side: Monitor, Health, Samples, Databases

The buttons down the right side open a panel over the page. The same button closes it again; so do the x and Esc.

• A panel floats over the page and closes when you click somewhere else. The pin button keeps it open beside the page instead.
• Drag its left edge to make it wider. Double-click the edge for the normal width.
• The console remembers the open panel, the pin and the widths.

Terminal

The terminal at the bottom of Home is a live log of what the server does: every statement, write, timer run, login and backup, as it happens. It shows where the data comes from, for example a program on the PostgreSQL port or a timer.

14:19:02.114  PG     10.0.0.5 app    market   3 ms       1 row  SELECT price FROM ochl_day WHERE ...
14:19:02.530  HTTP   10.0.0.9        market  12 ms  12,000 rows  12,000 rows into trade_log (line protocol)
14:20:00.004  TIMER  refresh_prices  market  41 ms    350 rows  CALL refresh_prices();

• The terminal is hidden when the page opens. It shows up by itself when you Run a statement, and the Terminal button shows or hides it any time.
• Click a line to see all of its text; double-click a statement to put it into the editor. Failed lines are red.
• While the terminal is hidden, the Terminal button counts the new lines.
• The console's own background reads (the lists on the left, the monitor) are not logged, so they do not fill it.
• Users who are not admins see only their own lines.

Health panel

If Check now finds damage: stop the server and run kdb repair (backup and safety).

Database picker and New database

• The Database list at the top shows the databases of the server. Everything on the page uses the chosen one: the editor, the object lists, the health panel, timers and backups. The console adds db=<name> to each request.
• The Databases panel on the right shows the same databases with their tables, size and folder. Click one to use it.
• The browser remembers the choice. When that database is gone, the console uses the server's default database.
• New database asks for a name (letters, digits, _ and -, at most 64; _trash and Windows device names like con are not allowed). The new, empty database is chosen right away. It uses POST /api/databases.
• USE demo;, CREATE DATABASE x; and DROP DATABASE x; in the editor also update the list. Dropping the chosen database moves the console back to the default database. A dropped database's folder moves to _trash.
• With users, the list shows only the databases you may read, and New database only for a user with ROLE admin.

Login form and token box

Users. When the data folder has users, the console shows Log in. Type the user name and password.

• After the login, the top bar shows the user and role, for example boss (admin), and a Log out button.
• The login is kept in a cookie that scripts cannot read (HttpOnly) and that works only on this site (SameSite=Strict). It ends after 12 hours, at Log out, when the server restarts, or when the password changes.
• A wrong password keeps the form open with Wrong user name or password. After 5 wrong tries, wait a moment.
• Each statement runs with your role. A refused one shows the error, for example INSERT needs role write on database 'shop'; user 'report' has read.

Token. On a server started with --token, the console shows Access token required. Type the token once.

• The server keeps it in a cookie that scripts cannot read (HttpOnly, SameSite=Strict). CSV downloads work with it too.
• Remember on this computer for 30 days is on at first. Clear it and the browser forgets the token when it closes.
• Log out at the top makes this browser forget the token.
• A token an older console kept in the browser's storage is moved into the cookie once, then deleted there.
• The console sends the X-KDB-CSRF header with every change by itself (CSRF).

The connection state at the top says Connected, Offline (the server does not answer), Token required or Login required. More: logins and tokens.

Theme

The button at the top right switches between the dark theme (the default) and the light theme. The browser remembers the choice. The help panel and charts follow the theme.

Help menu

The Help button in the top bar opens a menu:

• In the help panel, every SQL example has Insert into editor, which puts that SQL (with its setup) into the console editor.
• The help comes from GET /help/: a folder of pages next to the kdb program, not inside it. When no help folder is installed, the panel says so and how to build it.
• The menu works with the keyboard: Arrow down opens it, arrows move, Enter chooses, Esc closes.

Keyboard shortcuts

On a Mac, use Cmd instead of Ctrl.

Open the console with SQL in the editor

Syntax:

http://127.0.0.1:9900/#sql=<URL-encoded SQL>

A link of this form opens the console and puts the SQL at the end of the editor, selected, ready for Ctrl+Enter. It does not run the SQL by itself.

• URL-encoded means special characters are written as % codes: a space is %20, a ' is %27, a , is %2C. JavaScript's encodeURIComponent, Python's urllib.parse.quote and PowerShell's [uri]::EscapeDataString do it.
• The #sql=... part is removed from the address after it is read, so reloading the page does not add the SQL again.
• The Try in console button of examples in this help (when the help is opened as a page, not inside the console) uses such a link.
• The part after # never goes to the server, so the SQL does not appear in server logs.

http://127.0.0.1:9900/#sql=SELECT%20symbol%2C%20close%20FROM%20ochl_day%20WHERE%20symbol%20%3D%20%27CITY%27%20LIMIT%205

$sql = "SELECT symbol, close FROM ochl_day WHERE symbol = 'CITY' LIMIT 5"
Start-Process ("http://127.0.0.1:9900/#sql=" + [uri]::EscapeDataString($sql))

import urllib.parse, webbrowser
sql = "SELECT symbol, close FROM ochl_day WHERE symbol = 'CITY' LIMIT 5"
webbrowser.open("http://127.0.0.1:9900/#sql=" + urllib.parse.quote(sql, safe=""))