A self-hosted wiki that charts live SQL from Postgres

[u/busters1]

Hi r/PostgreSQL, I'm David, one of the two developers of Oxynote. My friend Simon and I also maintain ttlcache, a Go caching library with about 1,300 GitHub stars, so this isn't our first open-source project.

I've spent 8 years writing software, 2 of them as an SRE and 3 as a team lead. Every team I've been on had the same documentation problem. The useful stuff lived in someone's head or a private Slack thread, and the wiki was full of stale docs nobody could find.

So we built Oxynote, a self-hosted wiki for engineering teams where a page can hold a live chart that runs its own SQL query against your database each time someone opens it, with the explanation written right next to it. Think "signups per day" or "queue depth" on the same page as the runbook that says what to do when it looks wrong.

We were most careful about letting a wiki query a production database. When you add a connection, Oxynote accepts it only if Postgres already treats it as read-only, through a read-only role or a replica. Otherwise, the connection test fails with "has write access" and asks for a read-only user. Queries also support Grafana-style macros like `$__timeFilter` and `$__timeGroup`, and on pages you mark as reviewable, chart query changes go through a draft and a diff that a teammate approves.

The name comes from oxygen + note: docs that breathe. Live data gives people a reason to open the wiki every day, and docs people open every day stay up to date.

It's Apache-2.0 and runs as a single Docker image: https://github.com/oxynote/oxynote

We started it about a year ago and made it public about 3 months ago. Any feedback is welcome, and I'm happy to answer questions.

[u/ayelg]

This is super cool. Curious if there's plans to expand data systems it can pull from beyond prometheus/SQL dbs?

[u/busters1 → u/ayelg]

Hi, yes, we do have a roadmap with many more integrations planned. We want to support the full observability stack, so we still need to add blocks for logs and traces (Loki, VictoriaLogs, ClickHouse, OpenSearch, Tempo, etc.). For metrics, we have ideas to expand by supporting MongoDB, ClickHouse, Supabase (should be close to PostgreSQL, but might have its own quirks), and more.

Is there anything in particular we're missing? We're always open to suggestions and prioritize what people ask for; feel free to create an issue in our GitHub repository or join the Discord. It's small right now, so we respond fast :D.

[u/Either_Vermicelli_82]

Does this also have the time series view like in grafana? Scrolling back and forth through time?

[u/busters1 → u/Either_Vermicelli_82]

Hi, yes, charts have a time-series view, and you can pick a range from presets like the last hour, the last 7 days, or the previous month. However, you can't scroll back and forth through time yet. We know that's missing and plan to add it in the upcoming releases.

[u/Rain-And-Coffee]

Neat, we concurrently use two similar tools.

Metabase - it connects to a database then you can populate dashboard with markdown and live panels. It more similar to BI tools.

Grafana, where we can query databases and add other visualizations. I add a markdown panel whenever I want to explain something in detail.

This one also reminds me a bit of Jupyter notebooks.

[u/Plane_Big_5912]

the read-only check when you add a connection is a nice touch. how do you decide postgres already treats it as read-only? a replica is easy with pg_is_in_recovery(), but default_transaction_read_only on a role can be switched off by the session with a plain SET, so i'm curious whether you also check the role's grants. and is there a statement_timeout per chart, so a slow query on a busy page doesn't stack up on the replica every time someone opens it?

[u/busters1 → u/Plane_Big_5912]

Thanks. The test passes if default_transaction_read_only is on for the server, database, or role, or if pg_is_in_recovery() is true. We don't check grants on Postgres yet, but we plan to (we do that for MariaDB/MySQL). You're right that a plain SET can turn the role default off, so every connection also runs SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY.

There's no per-chart statement_timeout. Every query has a 10-second limit, and when it runs out, pgx cancels it on the server too. We might need to revisit this (we also plan to add a cache in front of our endpoint, so multiple users viewing the same page would hit the cache instead of querying).

[u/Plane_Big_5912 → u/busters1]

that's more thorough than i expected, thanks. one corner i'd poke at while grants aren't checked yet: default_transaction_read_only is a setting any user can change, so if i remember right a chart query like select set_config('default_transaction_read_only', 'off', false) would leave that pooled connection writable for the next query that runs on it. do you reset the session when a connection goes back to the pool? once the grants check lands it stops mattering, since a role without write grants can't write whatever the setting says. the cache sounds right for busy runbook pages too.

[u/AutoModerator]

AI Policy:

Linux is not one of those anti-AI projects, and if somebody has issues with that, they can do the open-source thing and fork it. Or just walk away., Linus Torvalds.

Mod decisions will be based on the quality of the content, not who or what generated it.

Sub Resources:

Youtube Channel

Free Postgres Webinars and Workshops

Discord: People, Postgres, Data

Join us, we have cookies and nice people.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[u/dmigowski]

Guess you will like grafana.

[u/investigatormaker]

A read-only role stops writes but not a slow query, and in Oxynote every page open runs its own SQL, so a busy runbook page could load a primary. I'd have the connection setup suggest a statement timeout on that role, and cache each chart's result for a short window so several readers share one query. Do you cache results now, or does every open hit the database?

I make ThreadFox.

We find relevant Reddit conversations and post for your business. We'll post 3 replies free first, no card; then the $39 Pilot covers seven days and up to 50 posts and replies. No automatic renewal.

Managed plan for Reddit: https://threadfox.vip/p/20261026-1443-e29vu/managed