tabularis-hackernews-plugin

A Hacker News plugin for Tabularis, the lightweight database management tool.

This plugin turns the HN public API into a queryable SQL database. Stories, comments, users and polls become real tables. Full SQL support via an in-memory DuckDB engine — JOIN across tables, GROUP BY, window functions, CTEs.

No authentication required — uses the public Firebase API. No runtime dependencies: ships as a single compiled binary.

Discord - Join our discord server and chat with the maintainers.

Table of Contents

• Features
• Installation
  • Automatic (via Tabularis)
  • Manual Installation
• How It Works
• Settings
• Example Queries
• Supported Operations
• Development
• Changelog
• License

Features

• Zero auth — reads the public HN Firebase API, no API key needed.
• Real SQL — DuckDB handles all query execution: JOIN, GROUP BY, subqueries, CTEs, window functions.
• Auto-refresh — configurable TTL to reload data periodically without restarting the connection.
• 6 feed types — top, new, best, ask, show, jobs.
• 4 tables — stories, comments (nested BFS fetch), users (author profiles), poll_options.
• Schema Inspection — browse tables and columns in the sidebar explorer.
• ER Diagram — visualize relationships between tables.
• Cross-platform — works on Linux, macOS, and Windows. No runtime dependencies.

Installation

Automatic (via Tabularis)

Open Settings → Available Plugins in Tabularis and install Hacker News from the plugin registry.

Manual Installation

1. Download the latest release archive for your platform from the Releases page.
2. Extract the archive.
3. Copy tabularis-hackernews-plugin (or tabularis-hackernews-plugin.exe on Windows) and manifest.json into the Tabularis plugins directory:

OS	Plugins Directory
Linux	~/.local/share/tabularis/plugins/hackernews/
macOS	~/Library/Application Support/com.debba.tabularis/plugins/hackernews/
Windows	%APPDATA%\com.debba.tabularis\plugins\hackernews\

4. Make the binary executable (Linux/macOS):

chmod +x ~/.local/share/tabularis/plugins/hackernews/tabularis-hackernews-plugin

5. Restart Tabularis.

How It Works

The plugin is a compiled Rust binary that communicates with Tabularis through JSON-RPC 2.0 over stdio:

1. Tabularis spawns tabularis-hackernews-plugin as a child process.
2. Requests are sent as newline-delimited JSON-RPC messages to the plugin's stdin.
3. Responses are written to stdout in the same format.

On the first execute_query, the plugin fetches story IDs from the selected feed, loads each item from the HN API concurrently into an in-memory DuckDB database, and keeps it alive for the session. DuckDB handles all query execution.

If cache_ttl_minutes is set, the snapshot is automatically rebuilt after that interval — no need to restart the connection.

All debug output is written to stderr and appears in Tabularis's log viewer — stdout is reserved exclusively for JSON-RPC responses.

Settings

Configure via Settings → gear icon next to the Hacker News driver.

Key	Label	Type	Default	Description
story_type	Feed	select	top	Which HN feed: top, new, best, ask, show, jobs
max_items	Max Stories	number	30	How many stories to fetch (max 500)
include_comments	Include Comments	boolean	false	Load comments, enables the comments table
comment_depth	Comment Depth	number	1	Nesting levels to fetch (1–3). Higher values make many more requests
max_comments	Max Comments	number	500	Global cap on total comments fetched (max 5000)
include_users	Include Users	boolean	false	Fetch author profiles for story/comment authors, enables the users table
include_polls	Include Poll Options	boolean	false	Fetch voting options for poll stories, enables the poll_options table
timeout	Timeout (s)	number	10	HTTP timeout in seconds for HN API requests
cache_ttl_minutes	Cache TTL (min)	number	0	Auto-refresh data after N minutes. 0 = disabled

Example Queries

-- Top 10 stories by score
SELECT title, score, by, url
FROM stories
ORDER BY score DESC
LIMIT 10;

-- Who posts the most? And how well do they do?
SELECT by,
       COUNT(*)   AS posts,
       AVG(score) AS avg_score,
       MAX(score) AS best_score
FROM stories
GROUP BY by
ORDER BY posts DESC
LIMIT 10;

-- Stories linking to GitHub
SELECT title, url, score
FROM stories
WHERE url LIKE '%github.com%'
ORDER BY score DESC;

-- Comment activity per story (requires Include Comments = true)
SELECT s.title,
       s.score,
       COUNT(c.id)    AS loaded_comments,
       s.descendants  AS total_comments
FROM stories s
LEFT JOIN comments c ON c.story_id = s.id
GROUP BY s.id, s.title, s.score, s.descendants
ORDER BY loaded_comments DESC;

-- Rank stories by score within each type using a window function
SELECT title, type, score,
       RANK() OVER (PARTITION BY type ORDER BY score DESC) AS rank_in_type
FROM stories
ORDER BY type, rank_in_type;

-- Stories from the last 24 hours with at least 10 points
SELECT title, score, by,
       epoch_ms(time * 1000)::TIMESTAMP AS posted_at
FROM stories
WHERE time > epoch(now()) - 86400
  AND score >= 10
ORDER BY score DESC;

-- Top authors by karma (requires Include Users = true)
SELECT id, karma, submitted_count
FROM users
ORDER BY karma DESC
LIMIT 10;

Supported Operations

Method	Description
test_connection	Verify the HN API is reachable
get_databases	Returns ["hackernews"]
get_tables	Lists active tables based on current settings
get_columns	Get column schema for a table
execute_query	Execute SQL with pagination support
get_schema_snapshot	Full schema dump in one call (used for ER diagrams)
get_all_columns_batch	All columns for all tables in one call
get_all_foreign_keys_batch	Returns empty (no enforced FK constraints)
insert_record / update_record / delete_record	Returns error — read-only source

Development

Building

cargo build --release

Testing the Plugin

Test the plugin directly from your shell without opening Tabularis:

# initialize
echo '{"jsonrpc":"2.0","method":"initialize","params":{"settings":{"story_type":"top","max_items":5,"include_comments":false,"timeout":10,"cache_ttl_minutes":0}},"id":1}' \
  | ./target/release/tabularis-hackernews-plugin

# execute a query (fetches live data)
echo '{"jsonrpc":"2.0","method":"execute_query","params":{"params":{"driver":"hackernews","database":"hackernews"},"query":"SELECT title, score FROM stories ORDER BY score DESC LIMIT 3","page":1,"page_size":100},"id":2}' \
  | ./target/release/tabularis-hackernews-plugin

Install Locally

A convenience script builds the project and copies the binary and manifest directly into your Tabularis plugins folder:

./sync.sh

Tech Stack

• Language: Rust
• Query engine: DuckDB (in-memory)
• HTTP client: reqwest (async, rustls-tls)
• Async runtime: Tokio
• Data source: HN Firebase API
• Protocol: JSON-RPC 2.0 over stdio

Changelog

License

Apache License 2.0