sql-code-graph 1.0.2__py3-none-any.whl → 1.1.3__py3-none-any.whl

sqlcg/cli/commands/git.py

@@ -1,5 +1,7 @@
 """Git integration commands for sqlcg."""
 
+import shutil
+import sys
 from pathlib import Path
 from typing import NamedTuple
 
@@ -14,36 +16,79 @@ app = typer.Typer(name="git", help="Git integration commands")
 class _HookSpec(NamedTuple):
     filename: str
     sentinel: str
-    script: str
+    script_template: str
 
 
+# Hook script templates — use {sqlcg_bin} as the placeholder for the resolved binary.
+# The sentinel comments (e.g. "# sqlcg post-checkout hook") must stay byte-for-byte
+# unchanged so R9 idempotency is preserved: _install_single_hook matches them verbatim.
 _HOOKS: list[_HookSpec] = [
     _HookSpec(
         filename="post-checkout",
         sentinel="# sqlcg post-checkout hook",
-        script=(
+        script_template=(
             "#!/bin/sh\n"
             "# sqlcg post-checkout hook — incremental resync after branch switch\n"
             "# $3 == 1 means branch checkout (not file checkout); skip file checkouts\n"
             '[ "$3" = "1" ] || exit 0\n'
-            'sqlcg reindex --from "$1" --to "$2"'
-            ' "$(git rev-parse --show-toplevel)" --dialect auto --quiet || true\n'
+            '{sqlcg_bin} reindex --from "$1" --to "$2"'
+            ' "$(git rev-parse --show-toplevel)" --dialect auto --quiet --notify'
+            ' || echo "sqlcg: graph not updated (server busy/locked)'
+            " -- run 'sqlcg mcp status'\" >&2\n"
         ),
     ),
     _HookSpec(
         filename="post-merge",
         sentinel="# sqlcg post-merge hook",
-        script="""\
+        script_template="""\
 #!/bin/sh
 # sqlcg post-merge hook — incremental resync after pull/merge
-# post-merge receives only $1 (squash flag), no old/new SHA; use stored-SHA delta
-sqlcg reindex "$(git rev-parse --show-toplevel)" --dialect auto --quiet || true
+# git sets ORIG_HEAD to the pre-merge HEAD; pass it as --from so --notify can route
+# through a running server (same path as post-checkout). If ORIG_HEAD is unset (e.g.
+# first-ever merge / gc'd), fall back to the standalone stored-SHA delta (direct write).
+PREV=$(git rev-parse --verify --quiet ORIG_HEAD)
+TOP=$(git rev-parse --show-toplevel)
+if [ -n "$PREV" ]; then
+  {sqlcg_bin} reindex --from "$PREV" --to HEAD "$TOP" --dialect auto --quiet --notify \\
+    || echo "sqlcg: graph not updated (server busy/locked) -- run 'sqlcg mcp status'" >&2
+else
+  {sqlcg_bin} reindex "$TOP" --dialect auto --quiet --notify \\
+    || echo "sqlcg: graph not updated (server busy/locked) -- run 'sqlcg mcp status'" >&2
+fi
 """,
     ),
 ]
 
 
-def _install_single_hook(hooks_dir: Path, spec: _HookSpec) -> None:
+def _resolve_sqlcg_bin() -> str:
+    """Resolve the absolute path of the installing sqlcg binary.
+
+    Resolution order:
+    1. shutil.which("sqlcg") — the binary on the installer's $PATH.
+    2. sys.argv[0] resolved via Path(...).resolve() if it ends in "sqlcg" and is executable.
+    3. Bare "sqlcg" fallback (current behaviour) — prints a warning so the user knows.
+
+    Returns the resolved path string (absolute when resolvable, bare "sqlcg" otherwise).
+    """
+    # 1. Try $PATH first — the binary the user means
+    which_result = shutil.which("sqlcg")
+    if which_result:
+        return which_result
+
+    # 2. Try sys.argv[0] for python -m / editable-install invocations
+    argv0 = Path(sys.argv[0]).resolve()
+    if argv0.name == "sqlcg" and argv0.is_file() and argv0.stat().st_mode & 0o111:
+        return str(argv0)
+
+    # 3. Bare fallback — still functional but relies on $PATH at hook-run time
+    console.print(
+        "[yellow]Warning: could not resolve the sqlcg binary path; the generated hooks "
+        "will use bare 'sqlcg' and rely on $PATH at hook-run time.[/yellow]"
+    )
+    return "sqlcg"
+
+
+def _install_single_hook(hooks_dir: Path, spec: _HookSpec, sqlcg_bin: str) -> None:
     """Install one git hook idempotently.
 
     If the hook file already contains the sentinel, it is already installed — skip silently.
@@ -51,6 +96,7 @@ def _install_single_hook(hooks_dir: Path, spec: _HookSpec) -> None:
     Otherwise, write the hook file and set 0o755.
     """
     hook_path = hooks_dir / spec.filename
+    script = spec.script_template.format(sqlcg_bin=sqlcg_bin)
 
     if hook_path.exists():
         existing_content = hook_path.read_text()
@@ -68,10 +114,10 @@ def _install_single_hook(hooks_dir: Path, spec: _HookSpec) -> None:
                 f".git/hooks/{spec.filename}:[/yellow]"
             )
             console.print("")
-            console.print("[cyan]" + spec.script.rstrip() + "[/cyan]")
+            console.print("[cyan]" + script.rstrip() + "[/cyan]")
             return
 
-    hook_path.write_text(spec.script)
+    hook_path.write_text(script)
     hook_path.chmod(0o755)
     console.print(f"[green]Installed git hook:[/green] .git/hooks/{spec.filename}")
 
@@ -87,6 +133,8 @@ def install_hooks(
     Writes a post-checkout hook that triggers incremental resync after branch switches
     and a post-merge hook that triggers resync after pulls/merges.
     Idempotent: running multiple times produces one hook entry per hook.
+    The hooks embed the absolute path of the installing sqlcg binary so version skew
+    between the installed binary and the hook command is avoided.
     """
     if repo is None:
         repo = Path.cwd()
@@ -100,5 +148,7 @@ def install_hooks(
 
     hooks_dir.mkdir(parents=True, exist_ok=True)
 
+    sqlcg_bin = _resolve_sqlcg_bin()
+
     for spec in _HOOKS:
-        _install_single_hook(hooks_dir, spec)
+        _install_single_hook(hooks_dir, spec, sqlcg_bin)

sqlcg/cli/commands/index.py

@@ -14,7 +14,7 @@ from rich.progress import (
     TimeRemainingColumn,
 )
 
-from sqlcg.core.config import KuzuConfig, get_backend, get_db_path, get_dialect
+from sqlcg.core.config import KuzuConfig, config_file_present, get_backend, get_db_path, get_dialect
 from sqlcg.indexer.indexer import Indexer
 
 console = Console()
@@ -29,7 +29,7 @@ def index_cmd(  # noqa: B008
         None, "--dbt-manifest", help="Path to dbt manifest"
     ),
     timeout_per_file: int = typer.Option(  # noqa: B008
-        5, "--timeout-per-file", help="Timeout per file in seconds"
+        10, "--timeout-per-file", help="Timeout per file in seconds"
     ),
     buffer_pool_size: int = typer.Option(  # noqa: B008
         0,
@@ -63,6 +63,14 @@ def index_cmd(  # noqa: B008
     profile: bool = typer.Option(  # noqa: B008
         False, "--profile/--no-profile", help="Emit per-stage timing after indexing"
     ),
+    include_working_tree: bool = typer.Option(  # noqa: B008
+        False,
+        "--include-working-tree",
+        help=(
+            "Index the working tree including uncommitted changes. "
+            "Marks freshness as 'indexed with working-tree changes'."
+        ),
+    ),
 ) -> None:
     """Index SQL files in a directory.
 
@@ -113,6 +121,13 @@ def index_cmd(  # noqa: B008
     if dialect == "auto":
         dialect = get_dialect(path)
 
+    if not quiet and not config_file_present(path):
+        console.print(
+            f"[yellow]No .sqlcg.toml found at {path}/.sqlcg.toml — "
+            "using defaults (snowflake dialect, no aliases/prefixes). "
+            "Create .sqlcg.toml in the index directory to customise.[/yellow]"
+        )
+
     db_path = get_db_path()
     db_path.parent.mkdir(parents=True, exist_ok=True)
 
@@ -137,6 +152,19 @@ def index_cmd(  # noqa: B008
         sqlcg_log.removeHandler(_counter)
         _warn_handler.close()
 
+    # --include-working-tree: if the working tree is dirty, overwrite the stored SHA
+    # with a "<head>+dirty" sentinel so 'db info' can distinguish clean-HEAD index
+    # from working-tree-inclusive index.  The backend was closed inside _run_index,
+    # so we open a fresh context here for the single sentinel write.
+    if include_working_tree:
+        from sqlcg.core.freshness import _git
+
+        dirty_out = _git(path, "status", "--porcelain")
+        if dirty_out:  # non-empty string → working tree is dirty
+            head = _git(path, "rev-parse", "HEAD") or "unknown"
+            with get_backend() as _b2:
+                _b2.set_indexed_sha(f"{head}+dirty")
+
     if not verbose and not quiet and _counter.count > 0 and _warn_log_path is not None:
         console.print(
             f"[yellow]Parse warnings written to {_warn_log_path} "

sqlcg/cli/commands/mcp.py

@@ -71,3 +71,106 @@ def mcp_best_practices() -> None:
     from sqlcg.server.skill import render_body
 
     typer.echo(render_body())
+
+
+@app.command("status")
+def mcp_status() -> None:
+    """Print server status JSON (connects to control socket).
+
+    Returns JSON with fields: running, pid, db_path, indexed_sha, head_sha,
+    stale_by_commits, connected_clients, uptime when a server is live.
+
+    When no server is found: {"running": false}.
+    When the PID file exists with a live process but the socket is unavailable:
+    {"running": true, "degraded": "socket unavailable", ...}.
+
+    R3 (stale socket): if the socket file exists but the server is not
+    responding (ConnectionRefusedError / FileNotFoundError), falls through
+    to the PID-file probe — never hangs or errors on a dead socket.
+    """
+    import socket as _socket
+
+    from sqlcg.server.control import is_pid_alive, read_pid, sock_path
+
+    sp = sock_path()
+    try:
+        with _socket.socket(_socket.AF_UNIX, _socket.SOCK_STREAM) as s:
+            s.settimeout(2)
+            s.connect(str(sp))
+            s.sendall(json.dumps({"op": "status"}).encode() + b"\n")
+            data = s.recv(4096)
+        console.print_json(data.decode())
+    except (FileNotFoundError, ConnectionRefusedError, OSError):
+        # Socket unavailable — probe via PID file (R3: stale-socket fall-through)
+        rec = read_pid()
+        if rec and is_pid_alive(rec["pid"]):
+            console.print_json(
+                json.dumps(
+                    {
+                        "running": True,
+                        "degraded": "socket unavailable",
+                        "pid": rec["pid"],
+                        "db_path": rec["db_path"],
+                    }
+                )
+            )
+        else:
+            console.print_json(json.dumps({"running": False}))
+
+
+@app.command("stop")
+def mcp_stop() -> None:
+    """Stop the running MCP server gracefully.
+
+    Sends a ``stop`` op via the control socket; waits up to 5 s for the
+    socket file to disappear (confirming clean exit).  Falls back to SIGTERM
+    on the PID-file PID if the socket is unavailable.
+
+    R3 (stale socket): ``ConnectionRefusedError`` / ``FileNotFoundError`` are
+    caught — never hangs on a dead socket.
+    """
+    import socket as _socket
+    import time
+
+    from sqlcg.server.control import is_pid_alive, read_pid, sock_path
+
+    sp = sock_path()
+    try:
+        with _socket.socket(_socket.AF_UNIX, _socket.SOCK_STREAM) as s:
+            s.settimeout(2)
+            s.connect(str(sp))
+            s.sendall(json.dumps({"op": "stop"}).encode() + b"\n")
+            s.recv(128)
+        # Wait up to 5 s for the socket file to disappear (confirms clean exit)
+        for _ in range(10):
+            if not sp.exists():
+                break
+            time.sleep(0.5)
+        console.print("[green]Server stopped.[/green]")
+    except (FileNotFoundError, ConnectionRefusedError, OSError):
+        # Socket unavailable — fall back to SIGTERM via PID file
+        import signal
+
+        rec = read_pid()
+        if rec and is_pid_alive(rec["pid"]):
+            os.kill(rec["pid"], signal.SIGTERM)
+            console.print(f"[yellow]Socket unavailable — sent SIGTERM to PID {rec['pid']}[/yellow]")
+        else:
+            console.print("[yellow]No server found to stop.[/yellow]")
+
+
+@app.command("restart")
+def mcp_restart() -> None:
+    """Stop the server. The client (editor) must respawn.
+
+    v1.1 cannot re-parent an editor-spawned stdio process.  This command
+    stops the current server and prints guidance for the user to restart
+    the MCP server via their editor's MCP configuration.
+
+    True auto-restart (re-parenting stdio) is deferred to v1.2.
+    """
+    mcp_stop()
+    console.print(
+        "[yellow]Server stopped. Please restart via your editor's MCP configuration.[/yellow]"
+    )
+    console.print("[dim]True auto-restart (re-parenting stdio) is deferred to v1.2.[/dim]")

sqlcg/cli/commands/reindex.py

@@ -18,6 +18,12 @@ from rich.console import Console
 
 console = Console()
 
+# Client-side socket timeout for the --notify control-socket path.
+# A real DWH server-side resync_changed measured ~89 s (41 changed files + closure);
+# 300 s covers that with headroom while keeping the wait bounded on a wedged server.
+# This is a CLI transport bound, NOT a KuzuConfig/indexer constant.
+_NOTIFY_SOCKET_TIMEOUT_S = 300
+
 
 def reindex_cmd(  # noqa: B008
     path: Path = typer.Argument(..., help="Repository root directory to resync"),  # noqa: B008
@@ -39,10 +45,18 @@ def reindex_cmd(  # noqa: B008
         help="Files per KuzuDB transaction (same default as index command)",
     ),
     timeout_per_file: int = typer.Option(  # noqa: B008
-        5,
+        10,
         "--timeout-per-file",
         help="Per-file parse timeout in seconds",
     ),
+    notify: bool = typer.Option(  # noqa: B008
+        False,
+        "--notify",
+        help=(
+            "If a server is live on this DB, route the reindex through the server "
+            "(avoids lock contention). Falls back to direct write if no server is found."
+        ),
+    ),
 ) -> None:
     """Incrementally resync the graph after a git branch change or pull.
 
@@ -56,17 +70,99 @@ def reindex_cmd(  # noqa: B008
     Exits with an error if the database schema version does not match the current
     build — run 'sqlcg db reset && sqlcg db init && sqlcg index <path>' to re-init.
     """
-    from sqlcg.core.config import get_backend, get_db_path, get_dialect
+    import json
+    import socket as _socket
+
+    from sqlcg.core.config import config_file_present, get_backend, get_db_path, get_dialect
     from sqlcg.core.schema import SCHEMA_VERSION
     from sqlcg.indexer.indexer import Indexer
+    from sqlcg.server.control import sock_path
 
     # Resolve to absolute path so ignore-spec and git delta receive an absolute root
     path = path.resolve()
 
+    # --notify: if a server is live, route reindex through the socket (R3 fallback)
+    if notify:
+        sp = sock_path()
+        try:
+            with _socket.socket(_socket.AF_UNIX, _socket.SOCK_STREAM) as s:
+                s.settimeout(_NOTIFY_SOCKET_TIMEOUT_S)
+                s.connect(str(sp))
+                # Resolve SHAs before sending — standalone mode reads from DB via socket
+                effective_from = from_sha
+                if effective_from is None:
+                    # Standalone mode: we cannot read stored SHA here without opening the
+                    # DB (which would conflict with the running server).  If no --from is
+                    # given with --notify, we send from="stored" as a sentinel and fall
+                    # back to direct write; the caller should pass --from explicitly.
+                    raise OSError(  # noqa: TRY301
+                        "--notify without --from requires direct DB access; falling through"
+                    )
+                # Resolve symbolic refs (HEAD, branch names) to concrete 40-char SHAs
+                # before sending — prevents literal "HEAD" from being stored in the graph.
+                effective_from = _resolve_ref(path, effective_from)
+                effective_to = _resolve_ref(path, to_sha) if to_sha else _get_head(path)
+                payload = {
+                    "op": "reindex",
+                    "root": str(path),
+                    "from": effective_from,
+                    "to": effective_to,
+                    "dialect": dialect,
+                }
+                s.sendall(json.dumps(payload).encode() + b"\n")
+                data = s.recv(65536)
+            result = json.loads(data)
+            if "error" in result:
+                console.print(f"[red]Server reindex error: {result['error']}[/red]")
+                raise typer.Exit(1)
+            if not quiet:
+                srv_summary = result.get("summary", {})
+                console.print(
+                    f"[green]Resynced via server[/green] "
+                    f"+{srv_summary.get('added', 0)} added, "
+                    f"~{srv_summary.get('modified', 0)} modified, "
+                    f"-{srv_summary.get('deleted', 0)} deleted"
+                )
+            raise typer.Exit(0)
+        except TimeoutError:
+            # Bug 1 fix: server is alive and working (accepted the connection, holds the
+            # lock, will finish and persist).  Do NOT fall through to the direct-write
+            # path — that would hit the held lock and produce a false "Database is locked"
+            # error.  Exit 0 so the git hook stays non-fatal; the server will complete.
+            # (socket.timeout is an alias of TimeoutError, a subclass of OSError — this
+            # clause must be listed before the broad OSError clause below.)
+            import sys
+
+            print(
+                f"Server is still applying the reindex (timed out waiting after "
+                f"{_NOTIFY_SOCKET_TIMEOUT_S}s); the graph will update when it finishes "
+                f"— check 'sqlcg mcp status'.",
+                file=sys.stderr,
+            )
+            raise typer.Exit(0) from None
+        except (FileNotFoundError, ConnectionRefusedError, OSError):
+            # R3: no live server (stale socket, socket absent, fallback condition) —
+            # fall through to the existing direct-write path unchanged.
+            # NOTE: socket.timeout / TimeoutError is an OSError subclass, so the
+            # dedicated timeout clause above must be listed first (already is).
+            pass
+        except typer.Exit:
+            raise
+        except Exception as exc:
+            console.print(f"[red]--notify routing failed: {exc}[/red]")
+            raise typer.Exit(1) from exc
+
     # Resolve dialect
     if dialect == "auto":
         dialect = get_dialect(path)
 
+    if not quiet and not config_file_present(path):
+        console.print(
+            f"[yellow]No .sqlcg.toml found at {path}/.sqlcg.toml — "
+            "using defaults (snowflake dialect, no aliases/prefixes). "
+            "Create .sqlcg.toml in the index directory to customise.[/yellow]"
+        )
+
     db_path = get_db_path()
     db_path.parent.mkdir(parents=True, exist_ok=True)
 
@@ -88,15 +184,17 @@ def reindex_cmd(  # noqa: B008
 
         # ---- Determine mode -------------------------------------------------------
         if from_sha is not None:
-            # Explicit-SHA mode
-            effective_to = to_sha or _get_head(path)
+            # Explicit-SHA mode — resolve symbolic refs to concrete SHAs before storing
+            effective_from = _resolve_ref(path, from_sha)
+            effective_to = _resolve_ref(path, to_sha) if to_sha else _get_head(path)
             if not quiet:
                 console.print(
-                    f"Resyncing [cyan]{path}[/cyan] [dim]{from_sha[:8]}..{effective_to[:8]}[/dim]"
+                    f"Resyncing [cyan]{path}[/cyan] "
+                    f"[dim]{effective_from[:8]}..{effective_to[:8]}[/dim]"
                 )
             summary = indexer.resync_changed(
                 path,
-                from_sha,
+                effective_from,
                 effective_to,
                 backend,
                 dialect,
@@ -150,24 +248,36 @@ def reindex_cmd(  # noqa: B008
                 )
 
 
-def _get_head(root: Path) -> str:
-    """Return the current HEAD SHA for the git repo at root.
+def _resolve_ref(root: Path, ref: str) -> str:
+    """Resolve a git ref (HEAD, branch, tag, or concrete SHA) to a 40-char SHA.
 
-    Raises typer.Exit(1) if git is unavailable or root is not a git repo.
+    A concrete SHA resolves to itself (idempotent), so callers may pass either a
+    symbolic ref or a SHA without branching.
+
+    Raises typer.Exit(1) if git is unavailable or the ref cannot be resolved.
     """
     try:
         result = subprocess.run(
-            ["git", "rev-parse", "HEAD"],
+            ["git", "rev-parse", ref],
             cwd=str(root),
             capture_output=True,
             text=True,
         )
         if result.returncode != 0:
             console.print(
-                f"[red]Could not determine HEAD SHA in {root}: {result.stderr.strip()}[/red]"
+                f"[red]Could not resolve ref '{ref}' in {root}: {result.stderr.strip()}[/red]"
             )
             raise typer.Exit(1)
         return result.stdout.strip()
     except FileNotFoundError:
-        console.print("[red]git is not available — cannot determine HEAD SHA[/red]")
+        console.print("[red]git is not available — cannot resolve ref[/red]")
         raise typer.Exit(1) from None
+
+
+def _get_head(root: Path) -> str:
+    """Return the current HEAD SHA for the git repo at root.
+
+    Delegates to _resolve_ref so there is one git-rev-parse code path.
+    Raises typer.Exit(1) if git is unavailable or root is not a git repo.
+    """
+    return _resolve_ref(root, "HEAD")

sqlcg/core/config.py

@@ -71,6 +71,21 @@ def get_db_path() -> Path:
     return KuzuConfig.from_env().db_path
 
 
+def config_file_present(path: Path) -> bool:
+    """Return True when a .sqlcg.toml file exists at the given directory.
+
+    Single source of truth for the config filename so callers never hard-code
+    ".sqlcg.toml" independently.
+
+    Args:
+        path: Directory to check for .sqlcg.toml
+
+    Returns:
+        True if path/.sqlcg.toml exists, False otherwise.
+    """
+    return (Path(path) / ".sqlcg.toml").exists()
+
+
 def get_dialect(path: Path) -> str:
     """Get the SQL dialect from .sqlcg.toml or fall back to snowflake.
 
@@ -266,9 +281,90 @@ def get_presentation_prefixes(path: Path) -> list[str]:
     return []
 
 
-def get_backend() -> "GraphBackend":
+class ExternalConsumerSpec(BaseModel):
+    """Specification for a single external downstream consumer declared in .sqlcg.toml."""
+
+    name: str
+    consumer_type: str
+    consumes: list[str]
+
+
+def get_external_consumers(path: Path) -> list[ExternalConsumerSpec]:
+    """Get external downstream consumer declarations from .sqlcg.toml.
+
+    Reads [[sqlcg.external_consumers]] array-of-tables from .sqlcg.toml. Each
+    table must have ``name`` and ``consumes`` (non-empty list). Rows without a
+    ``name`` or with an empty ``consumes`` list are silently skipped. The
+    ``kind`` field is stored as ``consumer_type`` (lowercased). **Defaults to an
+    empty list** when the section is absent — when unset, the ingestion pass is a
+    no-op (correct generic behaviour for any user). No hardcoded fallback::
+
+        [[sqlcg.external_consumers]]
+        name = "Tableau: Sales Dashboard"
+        kind = "tableau"
+        consumes = ["ia_sales.fct_orders"]
+
+    Args:
+        path: Root directory to search for .sqlcg.toml
+
+    Returns:
+        List of ExternalConsumerSpec objects. Defaults to an empty list.
+    """
+    config_file = Path(path) / ".sqlcg.toml"
+    if config_file.exists():
+        try:
+            with open(config_file, "rb") as f:
+                config = tomllib.load(f)
+            raw = config.get("sqlcg", {}).get("external_consumers", [])
+            if not isinstance(raw, list):
+                return []
+            specs: list[ExternalConsumerSpec] = []
+            for entry in raw:
+                if not isinstance(entry, dict):
+                    continue
+                name = entry.get("name", "")
+                if not name or not isinstance(name, str):
+                    continue
+                consumes_raw = entry.get("consumes", [])
+                if not isinstance(consumes_raw, list) or not consumes_raw:
+                    continue
+                consumes = [c.lower() for c in consumes_raw if isinstance(c, str)]
+                if not consumes:
+                    continue
+                kind = entry.get("kind", "")
+                consumer_type = kind.lower() if isinstance(kind, str) else ""
+                specs.append(
+                    ExternalConsumerSpec(
+                        name=name,
+                        consumer_type=consumer_type,
+                        consumes=consumes,
+                    )
+                )
+            return specs
+        except Exception:
+            pass
+    return []
+
+
+def get_backend(read_only: bool = False) -> "GraphBackend":
     """Get a graph backend instance respecting the SQLCG_BACKEND env var.
 
+    Args:
+        read_only: Open in read-only mode.  When ``True``, the KùzuDB open
+            does not take an exclusive write lock, enabling *multiple concurrent
+            read-only opens* (reader/reader concurrency).  CLI read commands
+            pass ``True`` so they do not hold the exclusive write lock and
+            therefore do not block other concurrent readers or a pending reindex.
+            Note: this does NOT allow reads while a read-write writer already
+            holds the exclusive lock — KùzuDB's exclusive write lock is
+            process-level; a ``read_only=True`` open still fails with
+            "Database is locked" when a writer is active.  Reads during an
+            active writer remain a known limitation (future work: route reads
+            through the live MCP server).
+            Neo4j has no single-writer lock; this flag is a no-op there.
+            All writer call sites (index, reindex, db init/reset, server
+            init_backend) use the default ``False``.
+
     Returns:
         A GraphBackend instance (KuzuBackend by default, or Neo4jBackend)
 
@@ -281,14 +377,26 @@ def get_backend() -> "GraphBackend":
         from sqlcg.core.kuzu_backend import KuzuBackend
 
         kuzu_cfg = KuzuConfig.from_env()
-        return KuzuBackend(
-            str(kuzu_cfg.db_path),
-            buffer_pool_size_mb=kuzu_cfg.buffer_pool_size_mb,
-        )
+        try:
+            return KuzuBackend(
+                str(kuzu_cfg.db_path),
+                buffer_pool_size_mb=kuzu_cfg.buffer_pool_size_mb,
+                read_only=read_only,
+            )
+        except RuntimeError as exc:
+            if read_only and "READ ONLY" in str(exc):
+                # KùzuDB refuses to open a non-existent or empty DB in read-only
+                # mode ("Cannot create an empty database under READ ONLY mode").
+                # Surface the same empty-DB guidance the user sees from `db info`.
+                raise RuntimeError(
+                    "Database not initialised — run 'sqlcg db init' and 'sqlcg index <path>' first."
+                ) from exc
+            raise
     elif backend_type == "neo4j":
         from sqlcg.core.neo4j_backend import Neo4jBackend
 
         neo4j_cfg = Neo4jConfig.from_env()
+        # Neo4j has no single-writer lock; read_only is a no-op here.
         return Neo4jBackend(neo4j_cfg.uri, neo4j_cfg.user, neo4j_cfg.password)
     else:
         raise ValueError(f"Unknown backend type: {backend_type}")