What Database Does Open Code Review Use? Understanding the JSONL Log Architecture

Open Code Review does not use a traditional relational or NoSQL database; instead, it stores all review data in append-only JSONL log files on the local filesystem.

The alibaba/open-code-review project eliminates database dependencies entirely. According to the repository's architecture documentation, the tool persists review sessions as plain-text logs rather than using PostgreSQL, MySQL, or any external data store. This design choice simplifies deployment and ensures review histories remain portable and human-readable.

Why Open Code Review Uses JSONL Files Instead of a Database

The project explicitly avoids database engines. As stated in pages/src/content/docs/en/architecture.md (lines 13-16), the architecture relies on append-only logs with the clarification that "there's no database, just append-only logs".

Each review session generates a separate JSONL (JSON Lines) file containing a line-by-line transcript of interactions. These files capture prompts, LLM responses, tool calls, and metadata in a sequential format. The storage path follows this structure:

~/.opencodereview/sessions/<encoded-repo-path>/<session-id>.jsonl

How Session Data is Written (internal/session/persist.go)

The Session struct in internal/session/persist.go handles persistence through simple file appends. The AppendEvent method marshals events to JSON and writes them with a newline delimiter:

// internal/session/persist.go – Session JSONL writer
func (s *Session) AppendEvent(ev interface{}) error {
    line, err := json.Marshal(ev)
    if err != nil {
        return err
    }
    _, err = s.file.Write(append(line, '\n'))
    return err
}

This approach ensures durability without transaction overhead. Each event becomes an immutable record in the session log, making the history append-only and corruption-resistant.

Reading Logs and the Web Viewer (internal/viewer/server.go)

The Web UI reads these files directly without intermediate database queries. The internal/viewer/server.go implementation parses JSONL files to render historical review sessions.

To read a session file programmatically:

package main

import (
	"bufio"
	"encoding/json"
	"fmt"
	"os"
)

type Event struct {
	Type string `json:"type"`
	Data json.RawMessage `json:"data"`
}

func main() {
	path := os.ExpandEnv("$HOME/.opencodereview/sessions/example-repo/12345.jsonl")
	f, err := os.Open(path)
	if err != nil {
		panic(err)
	}
	defer f.Close()

	scanner := bufio.NewScanner(f)
	for scanner.Scan() {
		var ev Event
		if err := json.Unmarshal(scanner.Bytes(), &ev); err != nil {
			fmt.Println("skip malformed line:", err)
			continue
		}
		fmt.Printf("Event: %s\n", ev.Type)
	}
	if err := scanner.Err(); err != nil {
		panic(err)
	}
}

To launch the built-in viewer:

# Open the web viewer (runs a local server)

opencodereview view

# Then open the URL shown, e.g. http://localhost:8080/viewer/

CLI Entry Point and Session Creation (cmd/opencodereview/main.go)

The cmd/opencodereview/main.go file serves as the entry point that initializes these sessions. When users start a review, the CLI creates the encoded repository path directory and begins writing to the JSONL file immediately.

Summary

• Open Code Review uses append-only JSONL files rather than SQL or NoSQL databases.
• Session data resides in ~/.opencodereview/sessions/<encoded-repo-path>/<session-id>.jsonl.
• The AppendEvent method in internal/session/persist.go handles persistence by marshaling JSON and appending newlines.
• The Web UI in internal/viewer/server.go reads these files directly, confirming the architecture's database-free design.
• This filesystem-based approach eliminates setup complexity and ensures review histories remain portable plain text.

Frequently Asked Questions

Does Open Code Review use PostgreSQL or MySQL?

No. Open Code Review does not use PostgreSQL, MySQL, or any relational database. According to the architecture documentation in pages/src/content/docs/en/architecture.md, the system explicitly avoids databases in favor of append-only JSONL log files stored on the local filesystem.

Where are review sessions stored locally?

Review sessions are stored in the ~/.opencodereview/sessions/ directory. Each repository gets an encoded subdirectory path, with individual session files named <session-id>.jsonl. These files contain line-by-line JSON records of the entire review transcript.

How does the Web UI access historical reviews without a database?

The Web UI implemented in internal/viewer/server.go reads the JSONL session files directly from the filesystem. When you run opencodereview view, the server parses these append-only logs to display historical prompts, LLM responses, and tool calls without requiring database queries or connection pools.

Is the JSONL storage format scalable for large codebases?

The JSONL format scales linearly with session length since events are appended sequentially. While this eliminates database maintenance overhead, extremely long review sessions will result in larger single files. The AppendEvent method in internal/session/persist.go uses simple file writes, making it suitable for local CLI usage but potentially requiring rotation strategies for archival purposes in high-volume scenarios.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}