Executive Overview & Architectural Significance
The release of Oxynote introduces a paradigm shift in how engineering teams manage internal documentation by bridging the historical gap between static knowledge bases and dynamic telemetry. Traditionally, internal wikis and runbooks suffer from acute architectural decay; they are written during high-stress incidents and neglected until the next failure. Oxynote solves this fundamental observability anti-pattern by embedding live, executable queries directly into documentation pages alongside prose and architectural diagrams. By fusing documentation with live data sources—such as Prometheus, PostgreSQL, MySQL, and MariaDB—Oxynote incentivizes daily usage, transforming stale wikis into active operational surfaces.
From a systems architecture perspective, Oxynote leverages PostgreSQL not merely as an external persistent datastore, but as a central nervous system for both metadata storage and runtime telemetry resolution. The all-in-one Docker deployment natively embeds PostgreSQL 18, utilizing advanced relational capabilities to power its internal state engine, pull-request-style draft workflows, and diff-based review pipelines for documentation updates. This design ensures that institutional knowledge undergoes the same rigorous version-control discipline as production source code, maintaining complete auditability and safety before changes are merged into core operational guides.
Core Enhancements & Developer Ergonomics
The integration mechanics between Oxynote and PostgreSQL are engineered specifically to lower cognitive overhead for database administrators and site reliability engineers. Through the Live Metrics block architecture, developers can write raw SQL queries targeting their primary or replica PostgreSQL instances, rendering the output instantaneously as time-series charts, bar graphs, or gauges. This capabilities-first approach eliminates the friction of context-switching between monitoring dashboards and documentation platforms, placing telemetry precisely where engineers need it during incident response and system maintenance.
To ensure seamless adoption across existing monitoring stacks, Oxynote implements native support for Grafana-style query macros, including $__timeFilter, $__timeGroup, and $__timeFrom. This compatibility layer allows engineering teams to port pre-existing dashboard queries directly into their runbooks without rewriting SQL logic. Furthermore, security and isolation are treated as first-class citizens: Oxynote strictly enforces read-only access models. It mandates a dedicated database role or instance with default_transaction_read_only enabled, routes through physical or logical standbys where appropriate, and hardcodes every session into read-only execution modes at the driver level to prevent accidental mutation or performance degradation.
Architectural Comparison Matrix
| Metric / Dimension | Baseline Internal Wikis | Oxynote (PostgreSQL Integrated) |
|---|---|---|
| Query Latency | Static text (N/A) | Sub-second direct read-only SQL execution against PostgreSQL standbys |
| Memory Footprint | Low (Stateless document rendering) | Optimized via embedded PostgreSQL 18 engine and connection pooling |
| API / Interface | Custom REST endpoints / Webhooks | Native Grafana macro parsing with Prometheus & SQL multi-source orchestration |
| Data Consistency | Manual updates (High drift risk) | Living data pipelines tied directly to live database state |
Breaking Changes & Migration Caveats
As an initial architectural release under the Apache-2.0 license, this iteration of Oxynote establishes baseline contracts for state management and query execution. It is fully self-contained within its Docker distribution and does not introduce breaking changes to external legacy PostgreSQL deployments. However, administrators must ensure that upstream database credentials supplied to Oxynote strictly adhere to the read-only constraint model. Granting write-privileged roles will trigger runtime configuration warnings and violate the security isolation boundaries designed into the Live Metrics subsystem.
Step-by-Step Upgrade Guide
Deploying or upgrading to the latest Oxynote release requires provisioning the unified container image and configuring the target PostgreSQL data source with strict read-only permissions. Follow these steps to establish a secure, live-query-enabled documentation pipeline:
Provision Read-Only Database Role: Execute the following SQL commands on your target PostgreSQL database to establish a secure, isolated read-only user:
CREATE ROLE oxynote_reader WITH LOGIN PASSWORD 'secure_password'; ALTER ROLE oxynote_reader SET default_transaction_read_only = 'on'; GRANT CONNECT ON DATABASE production_db TO oxynote_reader; GRANT USAGE ON SCHEMA public TO oxynote_reader; GRANT SELECT ON ALL TABLES IN SCHEMA public TO oxynote_reader;Deploy via Docker Compose: Spin up the all-in-one container incorporating PostgreSQL 18 for internal state management:
version: '3.8' services: oxynote: image: ghcr.io/oxynote/oxynote:latest ports: - "8080:8080" environment: - OXYNOTE_DB_URL=postgresql://postgres:password@localhost:5432/oxynote - OXYNOTE_DEFAULT_DS_HOST=db.internal.net - OXYNOTE_DEFAULT_DS_USER=oxynote_readerValidate Grafana Macro Integration: Create a new wiki page, insert a Live Metrics block, and verify query resolution using standard time filters:
SELECT $__timeGroup(created_at, '5m') AS time, count(*) FROM transactions WHERE $__timeFilter(created_at) GROUP BY 1 ORDER BY 1;
