johnnynguyen882/locklens repository overview

⁠LockLens

PostgreSQL monitoring and investigation in one small image: what your databases are doing now (connections, queries by type, sessions, blocking, replication), how they got there (history, incidents with evidence), and opt-in, read-only data browsing and SQL.

Source, documentation, and issues: https://github.com/Huy-8bit/locklens⁠

⁠Quick start

LockLens keeps its history in its own PostgreSQL database (the store), never in the databases it monitors.

# Generate the master key once and keep it (a password manager, a secret store).
export LOCKLENS_MASTER_KEY="$(openssl rand -base64 32)"

docker network create locklens

docker run -d --name locklens-store --network locklens \
  -e POSTGRES_USER=locklens -e POSTGRES_PASSWORD=change-me -e POSTGRES_DB=locklens \
  -v locklens-store:/var/lib/postgresql \
  postgres:18-alpine

docker run -d --name locklens --network locklens \
  -p 127.0.0.1:8080:8080 \
  -e LOCKLENS_LISTEN=0.0.0.0:8080 \
  -e LOCKLENS_STORE_DSN='postgres://locklens:change-me@locklens-store:5432/locklens?sslmode=disable' \
  -e LOCKLENS_MASTER_KEY \
  -e LOCKLENS_ADMIN_PASSWORD='choose-a-long-password' \
  -e LOCKLENS_COOKIE_SECURE=false \
  johnnynguyen882/locklens:latest

Open http://127.0.0.1:8080⁠, sign in as admin, and add a PostgreSQL instance under Settings → Add instance by pasting its connection string. A regular role is used as is; for a superuser, LockLens offers to create its own least-privilege roles and stores only those.

Keep the master key: it encrypts the stored connection strings, and a new key makes them unreadable. LOCKLENS_COOKIE_SECURE=false is only for plain HTTP on your own machine; behind HTTPS, leave it unset.

⁠Configuration

Full list: configuration⁠.

⁠Image details

• Port 8080. Health: GET /healthz (liveness), GET /readyz (store reachable). Prometheus metrics at /metrics.
• Runs as the non-root user 10001. Platforms: linux/amd64, linux/arm64.
• Tags: latest (main branch), X.Y.Z and X.Y (releases).
• The image also contains locklens CLI commands (inspect, watch, snapshot, doctor) and the locklens-lab scenario runner used by the demo stack; the server never runs lab code.

⁠Safety

LockLens observes; it never kills sessions, cancels queries, changes settings, or runs DDL/DML on monitored databases. Table browsing and the SQL editor are off by default, never use an administrative role, and run in read-only transactions. Paste a superuser connection string once and LockLens creates least-privilege roles for itself (after you confirm) instead of storing it. Connection strings are encrypted and never shown, logged, or exported.