sqlite-web: a browser-based SQLite viewer you run from the command line

The gap sqlite-web fills between the sqlite3 shell and a desktop GUI

SQLite databases are single files, which is convenient until you need to look inside one on a machine where you cannot install a desktop application. The sqlite3 command-line shell works over SSH, but browsing a wide table, following a foreign key, or exporting a subset of columns is tedious there. Desktop tools such as DB Browser for SQLite solve that, but they need a graphical session and they hold the file open locally.

sqlite-web takes a third route. It is a Python package that starts an HTTP server and renders the database as a set of pages: an index with table and index counts plus the file size on disk, a structure tab for columns, indexes, triggers and foreign keys, a content tab with sortable headers and clickable foreign-key links, a query tab, and import and export tabs. The audience is developers and analysts who already have a .db file on a server or in a container and want a browser view of it without moving the file. It is not a database engine, not a hosted service, and not a replacement for SQLite itself.

How sqlite-web works: Flask, peewee and a request-scoped connection

The dependency list in pyproject.toml is short: flask, peewee>=4.0.0 and pygments. Flask serves the routes, peewee wraps the SQLite connection and schema introspection, and pygments handles syntax highlighting in the query view. The project layout confirms this: the sqlite_web/ package holds the application, tests.py sits at the repository root, and there is a docker/ directory plus a run-docker script.

Two entry points are declared under [project.scripts]: sqlite_web maps to sqlite_web.sqlite_web:main and sqlite_wsgi maps to sqlite_web.wsgi_server:main. The second one runs the same application under gevent, which the README calls the high-performance WSGI server and which requires the gevent extra. The --startup-hook option is the interesting piece of the architecture: it takes a dotted path such as my.module.some_callable and calls it with the SqliteDatabase instance before each request, which is how you would attach pragmas, custom functions or per-request setup that the built-in flags do not cover. The --foreign-keys flag separately enables the foreign-key constraint pragma.

Databases are passed as positional arguments, so the process is bound to the files you name at startup. Loading additional databases at runtime is opt-in and split into two flags: --enable-load allows uploading a database file, and --enable-filesystem allows naming an on-disk path. The README warns about the filesystem flag, which is the correct instinct, because it turns a viewer into a file reader for whatever the process user can reach.

Installing sqlite-web with pip and opening your first database

The README gives a single install command for the Python package. It pulls in Flask, peewee and pygments as dependencies, and the two optional extras are wsgi (gevent) and ssl (cryptography).

$ pip install sqlite-web

Start it by passing one or more database paths. The defaults are host 127.0.0.1 and port 8080, and the README says to navigate to http://localhost:8080/ afterwards to view the database.

$ sqlite_web /path/to/database.db

Multiple files are accepted as separate positional arguments, which is useful when you keep a main database and a scratch one side by side. Each becomes selectable in the UI.

$ sqlite_web /path/to/db1.db /path/to/db2.db /path/to/db3.db

If you prefer containers, the README documents both a published image and a local build. The image expects the database filename as the final argument and mounts your data directory at /data.

$ docker run -it --rm \
    -p 8080:8080 \
    -v /path/to/your-data:/data \
    ghcr.io/coleifer/sqlite-web:latest \
    db_filename.db

Command-line options can be appended after the filename. The README's example sets a URL prefix so the application is served under /sqlite-web/ rather than at the root, which matters behind a reverse proxy.

$ docker run -it --rm \
    -p 8080:8080 \
    -v /path/to/your-data:/data \
    ghcr.io/coleifer/sqlite-web:latest \
    db_filename.db \
    --url-prefix="/sqlite-web/"

On the first page you should see basic information about the database: the number of tables and indexes, and its size on disk. From there the structure, content, query, import and export tabs do what their names suggest. Two options are worth setting on day one if the data matters: --read-only opens the database in read-only mode, and -P prompts for a password, which can alternatively be supplied through the SQLITE_WEB_PASSWORD environment variable so the process does not wait on input.

Where sqlite-web stops being the right tool

The security model is the first limitation. The README documents one password option, -P or SQLITE_WEB_PASSWORD, and no notion of users, roles or permissions. Anyone who reaches the port and knows the password has the same access as everyone else. There is no audit trail described, so you cannot tell who changed a row.

The --enable-filesystem flag is the sharpest edge. It exists so you can point the running application at a database by path, and the README warns about it directly. Combined with a reachable port, that is an arbitrary-file-read primitive for the process user, limited only by SQLite's ability to open the file. If you need runtime loading, --enable-load with --upload-dir is the narrower option, since it accepts uploads rather than arbitrary paths.

Concurrency is the second limitation, and it comes from SQLite rather than from sqlite-web. A single writer at a time is the engine's rule. A web UI invites several people to click into the same table, and the application does not present itself as a coordination layer. For a database that is actively written by another process, a browser session that holds transactions open is a good way to collect "database is locked" errors.

Finally, the README does not document rollback, undo, a migration history or a schema diff. Adding and dropping columns and indexes through the structure tab executes against the live file. There is no staging step described. If you need reversible schema changes, this is the wrong layer, and you should be running migrations through a tool that records them.

sqlite-web compared with a desktop SQLite browser

DB Browser for SQLite is the obvious alternative and the difference is architectural, not cosmetic. DB Browser is a Qt desktop application that opens the file through the local filesystem and renders everything in-process. sqlite-web is a server: the file stays where it is, and the browser is a client of a Flask application. That single difference decides most cases. If the database lives on a remote host and you only have SSH, sqlite-web is the one that works without copying the file or forwarding a display. If you want offline use, native performance on a large table, or a tool that never opens a listening socket, the desktop application is the safer choice.

A second alternative is the sqlite3 shell itself, which ships with SQLite and needs no install. For one-off queries it beats both. The case for sqlite-web is the repetitive, visual work: following foreign keys by clicking, sorting a table by a column, exporting a column subset to CSV, or importing a JSON file and letting the importer create columns for unrecognized keys. Those are the tasks where typing SQL every time costs more than starting a server.

Maintenance, packaging and what the MIT licence means here

The repository is not archived and the default branch is master. No releases were retrieved, and the last push date is not available, so there is no basis for describing the project as actively developed. Check the commit history on master before you depend on it for anything long-lived.

The dependency surface is small, which keeps upgrade cost low in normal use: flask, peewee>=4.0.0 and pygments, with gevent and cryptography as optional extras. The pin worth noticing is peewee>=4.0.0, a lower bound rather than an upper one, so a future peewee major release could change behaviour without a corresponding constraint here. The version is read dynamically from sqlite_web.sqlite_web.__version__, so the package version and the code are kept in one place.

sqlite-web is MIT licensed. In practical terms that permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are retained. It says nothing about the licence of the data you point it at, and nothing about the security posture of running it on a network. Those remain your decisions. This is a description of the licence text, not legal advice.

Editorial conclusion

Adopt sqlite-web if you want to inspect or lightly edit a SQLite file from a browser without installing a desktop application, and you are comfortable running it locally on 127.0.0.1. Do not adopt it as a shared, multi-user database console: the README documents a single password flag and no user accounts, roles or audit log, and --enable-filesystem lets a visitor point the app at any path the process can read. Before exposing it beyond localhost, verify how the password is supplied (the SQLITE_WEB_PASSWORD environment variable or the -P prompt), whether --read-only is enough for your use case, and whether you need --ssl-cert and --ssl-key or the --ad-hoc option, which requires the cryptography package. Also check the last commit date on the master branch, since no releases are listed in the README.

Frequently asked questions

Official sources

1. Official README
2. Project repository