FalkorDB/falkordb-browser
FalkorDB/falkordb-browser has 138 GitHub stars and 36 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-16 18:51 UTC. Last push 2026-11-15.
Measured star growth
- in 24h
- 0
- in 7 days
- Collecting history
- in 15 days
- Collecting history
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
FalkorDB-Browser is a visualization UI for FalkorDB.
AIREADME.md
OriginalFalkorDB Browser
🎉 JUNE 2025 NEW UPDATE: Improved UI & Experience
Visualize, manipulate and manage FalkorDB graph data interactively to monitor and explore data changes. The latest version introduced the following improvements
Faster Graph Creation & Querying
Quickly create new graphs and run queries with fewer clicks. The UI now guides you through graph setup with smarter defaults and clearer feedback.
Simplified Node Editing
Editing node properties is now faster and more intuitive. Fewer modal windows, inline property editing, and immediate updates make this flow significantly more usable.
Query History Panel
A new history panel stores your recent queries. This makes it easier to iterate, profile, debug, or rerun past queries without leaving the editor.
Better Search
The search bar now indexes schema, nodes, and metadata. Results are ranked more effectively and load with lower latency.
Expanded Settings & User Controls
New options let you fine-tune database behavior, toggle visual preferences, and manage users without falling back to CLI tools.
Node Style Customization
Customize the visual appearance of nodes per label. Select custom colors from a palette, adjust node sizes, and choose which property to display as the node caption. All customizations are saved per graph and persist across sessions.
Automatic query limiting
When the result limit in Settings is above 0, the browser adds LIMIT <n> to a query
whose final RETURN has none. A limit of 0 (shown as ∞) leaves queries unchanged.
- Trailing semicolons are removed before the limit is added.
- A non-
UNIONquery whose finalRETURNalready has aLIMITkeeps it. UNIONqueries are wrapped asCALL { … } RETURN * LIMIT <n>, even when a branch has its ownLIMIT, so the limit applies to the combined result. A leadingCYPHERparameter header stays outside the wrapper.- Known limitation:
UNIONqueries that contain aCALLclause, or start withEXPLAINorPROFILE, are not wrapped; the limit is added to the last branch only.
Get Started & Demo
Access the Browser: (https://browser.falkordb.com)
Quick start
Run the graph database and browser from one docker container
Step 1:
docker run -p 3000:3000 -p 6379:6379 -it --rm falkordb/falkordb:latest
Step 2:
Open http://localhost:3000 with your browser.
Note: to run the application with a different URL, set the NEXTAUTH_URL environment variable.
docker run -p 3000:3000 -e "NEXTAUTH_URL=https://www.yoururl.com" -p 6379:6379 -it --rm falkordb/falkordb:latest
For reverse-proxy deployments using NEXTAUTH_URL=auto, set TRUST_PROXY_HEADERS=true only when the proxy strips or overwrites incoming X-Forwarded-Host and X-Forwarded-Proto headers.
Note: the image ships no default
AUTH_SECRET. If you do not supply one, a random secret is generated per container, which means every session is invalidated when the container is recreated. For anything long-lived, set your own:-e AUTH_SECRET="$(openssl rand -hex 32)".Supplying one is mandatory, not merely advisable, when more than one container serves the same site: each generates its own signing key, so a session minted by one replica is rejected by every other. Give all replicas the same
AUTH_SECRET.
Note: Alternativly, you can run the browser from source and database using Docker
Run the graph database from Docker container
docker run -p 6379:6379 -it --rm falkordb/falkordb:latest
Run browser-only Docker image (with local LOAD CSV defaults)
If you run the browser separately from FalkorDB, use the browser image and set the same CSV temp defaults used by compose:
docker run -p 3000:3000 --rm \
-e CSV_STORAGE=local \
-e CSV_LOCAL_TEMP_DIR=/var/lib/FalkorDB/import \
-e CSV_LOCAL_LOAD_URI_MODE=file \
-v falkordb-import:/var/lib/FalkorDB/import \
falkordb/falkordb-browser:latest
When FalkorDB runs in a different container, mount the same falkordb-import
volume to /var/lib/FalkorDB/import there as well and configure
IMPORT_FOLDER /var/lib/FalkorDB/import on the DB side.
Start already connected (preconfigured connection)
For GitOps-style deployments the connection can be baked into the environment, so the browser opens straight onto the graph list instead of the login form:
docker run -p 3000:3000 --rm \
-e FALKORDB_CONNECTION_URL=falkor://default:password@falkordb:6379 \
falkordb/falkordb-browser:latest
or with discrete fields instead of a URL:
docker run -p 3000:3000 --rm \
-e FALKORDB_HOST=falkordb \
-e FALKORDB_PORT=6379 \
-e FALKORDB_USERNAME=default \
-e FALKORDB_PASSWORD=password \
falkordb/falkordb-browser:latest
| Variable | Description | Default |
|---|---|---|
FALKORDB_CONNECTION_URL |
falkor://, falkors://, redis:// or rediss:// URL; the s variants imply TLS |
"" |
FALKORDB_HOST |
Hostname. Required unless the URL is set | "" |
FALKORDB_PORT |
Port | 6379 |
FALKORDB_USERNAME |
Username | default |
FALKORDB_PASSWORD |
Password | "" |
FALKORDB_TLS |
true/false; overrides the URL scheme |
from the URL |
FALKORDB_CA |
Base64-encoded CA certificate | "" |
FALKORDB_AUTO_CONNECT |
Sign in automatically on load. false only prefills the login form |
true |
Notes:
- The discrete fields override the URL field by field. An empty
FALKORDB_PASSWORDalso overrides it, so omit the variable entirely to keep the password fromFALKORDB_CONNECTION_URL. - The URL carries a host, a port and credentials and nothing else. A database
selector other than
/0, or any query string, is rejected at startup rather than dropped — the browser only ever talks to database 0. - The password never reaches the browser: the client only asks to log in with "the preconfigured connection" and the server substitutes the credentials.
FALKORDB_AUTO_CONNECT=falseis enforced server-side, not just in the UI: the server refuses to substitute the credentials at all, so the prefilled form needs a password the user knows.- Signing out explicitly returns to the login form and stays there; only a reload after an expired session reconnects automatically.
- Security: with
FALKORDB_AUTO_CONNECT=true, anyone who can reach the browser reaches the database with these credentials. Enable it only where the browser itself is access-controlled, and prefer a read-only FalkorDB user. The server logs a warning on first use when auto-connect is on with a password, and limits these sign-ins toPRECONFIGURED_SIGN_IN_MAX_REQUESTSper minute per client IP (default10,0disables). - The client IP is read from
X-Forwarded-For,TRUSTED_PROXY_HOPSentries from the right (default1, one reverse proxy), because the entries further left are whatever the client sent. Set it to the number of proxies that append to the header; a browser exposed with no proxy in front cannot tell a spoofed address from a real one. - The limiter keeps its counts in memory, so the budget is per instance: with several replicas a client gets each budget once per replica.
The Helm chart exposes the same settings under connection.* — see
Deploy to Kubernetes with Helm.
Use MinIO for CSV temp uploads (S3-compatible)
The CSV upload flow supports any S3-compatible backend, including MinIO. This repo includes a local MinIO stack in docker-compose.minio.yml for exercising the S3 storage provider (streaming multipart upload + presigned GET).
⚠️
LOAD CSVneeds HTTPS. FalkorDB fetches the CSV itself and only acceptshttps://orfile://URIs — plainhttp://is rejected ("Unsupported URI"). A plain‑http MinIO endpoint (http://localhost:9000) works for the browser→store upload, but the presigned URL handed to FalkorDB ishttp://…, so the import fails fast with a clear error. For a full end‑to‑endLOAD CSV, either:
- point at an HTTPS‑reachable object store — real S3 / Cloudflare R2, or MinIO behind a TLS proxy (set
S3_ENDPOINT=https://…), or- use the local backend for local dev —
CSV_STORAGE=localwithCSV_LOCAL_LOAD_URI_MODE=fileand a sharedIMPORT_FOLDER(see above); no HTTPS needed.
- Start MinIO and create the private CSV temp bucket:
docker compose -f docker-compose.minio.yml up -d
- Set these values in
.env.local(the endpoint is how the browser server reaches MinIO; forLOAD CSVto succeed it must resolve to an HTTPS URL the database can reach):
CSV_STORAGE=s3
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_REGION=us-east-1
S3_BUCKET=falkordb-csv-temp
S3_ENDPOINT=https://minio.example.com # must be HTTPS-reachable by FalkorDB
S3_FORCE_PATH_STYLE=true
S3_KEY_PREFIX=csv-temp/
S3_URL_EXPIRES_IN=3600
- Restart the browser server and upload CSV from Manage Graph -> Upload Data.
Notes:
- Keep the bucket private (default in the init container).
- Signed URLs are generated automatically for LOAD CSV and must be HTTPS-reachable by FalkorDB.
- For local non-TLS MinIO (
http://localhost:9000), preferCSV_STORAGE=localwithCSV_LOCAL_LOAD_URI_MODE=file. - MinIO console is available at
http://localhost:9001(user/password:minioadmin/minioadmin).
Deploy to Kubernetes with Helm
Deploy the FalkorDB Browser to your Kubernetes cluster using Helm:
# Install the chart
helm install falkordb-browser oci://ghcr.io/falkordb/helm-charts/falkordb-browser
# Access via port-forward
kubectl port-forward svc/falkordb-browser 3000:3000
Or install from source:
# Clone the repository
git clone https://github.com/FalkorDB/falkordb-browser.git
cd falkordb-browser
# Install the chart
helm install falkordb-browser ./helm/falkordb-browser
# Access via port-forward
kubectl port-forward svc/falkordb-browser 3000:3000
For detailed configuration options and examples, see the Helm chart documentation.
Build and run browser from source
Prerequisites:
- Node.js 24 or higher (
enginesinpackage.json)
Steps:
- Clone the git repository
git clone [email protected]:FalkorDB/falkordb-browser.git - Create .env.local in the clone directory
cp .env.local.template .env.local - Build the node project
npm -i - run the server
npm run dev
Open http://localhost:3000 with your browser.
Error help
When a Cypher query fails, the browser shows the database's message together with an
actionable 💡 hint. For a mistyped function or variable it offers a
"Did you mean…?" suggestion (e.g. Unknown function 'lenght' → Did you mean
length()?), computed from the built-in/UDF function list and the variables in your
query. The error is also surfaced inline in the editor as a red squiggle on the
offending token, with the hint on hover and a one-click quick fix to apply the
suggestion. As you type, unknown node labels that look like a typo of a known label are
flagged with a warning and a quick fix. When the static help isn't enough, a "Fix with
AI" button (shown only when a supported OpenAI-compatible model — OpenAI/Groq/xAI/Ollama/
LM Studio — is configured) sends the query and its error to your configured provider on an
explicit click and returns an explanation + a corrected query you can insert into the editor.
The full server message is always shown — recognized errors display it directly, and when the
toast shows a friendlier summary instead, you can expand "See more" to read the raw text and
use "Copy" for one-click copy into a bug report. Where helpful, a hint includes a
"Learn more →" link to the matching FalkorDB docs page, and the query-timeout hint deep-links
straight to the timeout field in Settings. Hints are currently English-only; localization is a
deliberate follow-up (it pairs with introducing stable structured error codes).
The logic lives in lib/cypherSuggestions.ts, lib/cypherDiagnostics.ts, and lib/aiFix.ts,
with the static hint catalog (and its optional docs/deep-links) in lib/cypherErrors.ts and the
clipboard helper in lib/clipboard.ts.
A few queries parse perfectly but are still certain to be rejected, so there is nothing to learn
from sending them. lib/queryPreflight.ts catches those at submit time — today, a LOAD CSV
source FalkorDB cannot fetch (it only accepts https:// and file://). Run stays enabled,
because the query is not malformed; instead the request is stopped with an explanation and, when
uploading the file is what would fix it, an "Upload CSV" button that opens the Load CSV tab
with the storage and URI handled for you. Whether file:// can resolve depends on the
deployment and nothing the browser can see settles it, so it is assumed to work unless you
set LOAD_CSV_FILE_URI=false.
AI query optimization and drafts
The editor's Optimize action uses the model and provider configuration selected
in Settings, with an API key only for hosted providers.
Before each analysis, optionally describe what to optimize, such as reducing scans
or improving a specific join. This guidance is included only in that request's
prompt and is not saved or reused. Leave it blank for a general review.
Each analysis requires clicking Analyze; there is no remembered-consent checkbox.
Optimize and Fix with AI use the Responses API for hosted OpenAI models, including
GPT-5, the o-series and newer reasoning models, without unsupported temperature
settings. Older OpenAI families (GPT-3.5, GPT-4/GPT-4o/GPT-4.1, chatgpt-*,
gpt-audio* and their fine-tunes) and the other supported providers keep Chat
Completions with temperature: 0 and the 30-second timeout. Responses requests allow
up to four minutes to finish. Reverse proxies, Kubernetes ingress controllers (often
60 seconds by default, e.g. nginx.ingress.kubernetes.io/proxy-read-timeout set via the
Helm chart's ingress.annotations) and serverless platforms must allow that long;
otherwise a slow reply surfaces as a generic Fix/Optimize error. Closing Optimize
cancels the request.
Fix with AI also offers Cancel while loading. Cancelling, changing the query,
tab, graph, connection, or page discards the old request; late replies cannot
replace a newer result.
It analyzes the query, available indexes, and GRAPH.EXPLAIN output without executing
the query. Expand EXPLAIN execution plan to inspect the plan used in the analysis.
If index metadata is unavailable, analysis continues with an explicit warning.
Chat, Fix with AI, and Optimize share a suggested-query card with Copy and Insert into editor actions. Neither action runs the query. The card adapts to mobile screens, and long Chat queries can be collapsed.
Missing AI configuration and provider errors offer Go to Settings. Returning to the graph preserves the editor query and unsent Chat input. Chat drafts are scoped to the connection, tab, and graph, and survive closing and reopening Chat. Submitted Chat input remains saved until the request succeeds; newer edits or an intentional clear take precedence over restoring a failed submission. Optimize failures close the dialog and show only a toast with the Settings action.
Contributing with AI agents
Agent rules (coverage bar, docs and design-doc upkeep, PR readiness including resolving every
review thread) live in .github/copilot-instructions.md,
shared with Claude Code through CLAUDE.md; path-specific rules are in
.github/instructions/. PR readiness needs the superpowers
plugin (install commands in the instructions). Design plans are in docs/design/.
Testing
Unit tests (Node's built-in test runner, no extra tooling):
npm testRuns the*.test.tssuites underapp/andlib/. Gated in CI by the Build workflow. These execute TypeScript directly vianode --test, which relies on native type-stripping, so they need the same Node ≥ 24 as the app (CI runs Node 24).Unit coverage gate:
npm run test:coverage— runs the unit tests and enforces 100% line/branch/function coverage on the modules it lists (lib/cypherSuggestions.ts,lib/cypherDiagnostics.ts,lib/aiFix.ts,lib/cypherErrors.ts,lib/clipboard.ts, …).Codebase coverage (the Codecov badges): measured over every source file —
app/,lib/,components/,auth.ts,proxy.tsand the desktop and mobile shells, without tests, type declarations or the generated grammar — by every kind of test: unit, smoke, e2e (browser and server side), desktop and mobile. A file no test loads counts as 0%. Each CI job records raw V8 coverage and turns it into a report with.github/scripts/coverage-report.mjs, and Codecov merges the reports per commit. The Coverage status workflow is the gate: once every coverage workflow a commit triggers has finished, and Codecov has processed their uploads, it requires 95% of the whole codebase (coverage/projecton PRs,coverage/project (push)on commits pushed tomainandstaging) and of the lines a PR changes (coverage/patch). A coverage job whose tests or report fail, are skipped or are cancelled fails the gate, since its coverage is incomplete; failures in jobs that produce no coverage (installers, the security scan) do not, and a Codecov upload error never fails a test job (.github/scripts/coverage-gate.mjs). Dependabot runs only get Dependabot secrets, soCODECOV_TOKENmust also be set as a Dependabot secret for their coverage to upload. Manual (workflow_dispatch) runs do not upload: the gate does not count them, and their uploads, named like the PR's or push's, would stand in for one that was lost. Each job keeps its report as acoverage-*workflow artifact for 3 days. Locally:rm -rf coverage NODE_V8_COVERAGE=coverage/raw/unit npm run test:coverage node .github/scripts/coverage-report.mjs unit coverage/raw/unit # coverage/unit/index.htmlFor e2e coverage, build with
COVERAGE=1 npm run build, start the server withNODE_V8_COVERAGE=coverage/raw/e2e npm start, run Playwright withE2E_COVERAGE_DIR=$PWD/coverage/raw/e2e, stop the server (it writes its coverage on exit), thennode .github/scripts/coverage-report.mjs e2e coverage/raw/e2e. Pages are recorded in Chromium only; a spec that uses Playwright'spage,contextorbrowserfixtures importstestfrome2e/infra/coverage.tsso its pages are recorded too. Browser-running CI jobs useREQUIRE_BROWSER_COVERAGE=1when generating the report: missing recordings or recorder errors fail collection, even when server coverage exists. Original script responses are captured in case Chromium loses a source during navigation; a source missing from both the recording and its response fails collection. Server-only test jobs do not require or launch a browser. The gate waits for all six shard uploads plus the TLS, cluster and stateless uploads, and the Docker upload when the workflow declares it, not just ane2eflag from one job. It waits up to 15 minutes for required uploads to appear and finish processing before reporting missing names. Docker is required only when the measured commit's workflow declares Docker coverage; reruns of older workflows retain their original requirements.Docker smoke tests still check the normal production image first. They also run against a separate image built with
--build-arg COVERAGE=1; its browser and server coverage is uploaded ase2e-docker. The report uses that container's exact.nextartifacts andCOVERAGE_SERVER_ROOT=/appto translate server paths into the reporting checkout. Server mappings use the V8 source-map cache or the container's copied external map; a missing referenced server map fails reporting rather than silently dropping hits. The default Docker build remains optimized and does not expose browser source maps. Stacked PR branches can validate the same jobs withgh workflow run playwright.yml --ref <branch>before their base reachesstaging.Smoke tests vs a real FalkorDB:
npm run test:smoke— runs everylib/**/*.smoke.tssuite against the actual server error wording. This covers the "Did you mean…?" suggestions and the error-hint drift guard: each entry in the hint catalog (lib/cypherErrors.ts) is paired with a query inlib/cypherErrorDriftCases.ts, and the smoke test asserts the live FalkorDB message still matches — so a server-side rewording is caught instead of silently dropping a hint. The smoke tests are gated: they skip unlessFALKORDB_SMOKE=1, and fail (rather than skipping) if that is set but no server is reachable. Run locally with:docker run -d -p 6379:6379 falkordb/falkordb FALKORDB_SMOKE=1 npm run test:smoke # optional: FALKORDB_URL=redis://host:portIn CI the Build workflow runs these against a pinned FalkorDB release (deterministic for PRs), while the scheduled Cypher error drift canary workflow runs the same tests against
:latestto surface drift early without blocking pull requests.Lint:
npm run lintEnd-to-end tests (Playwright):
npm run test:e2e