mirror of https://github.com/vectorize-io/hindsight.git synced 2026-09-14 19:31:49 +08:00

Files

T

DK09876 f4106fff55 docs: add Oracle Database setup guide (#2612 )

* docs: add Oracle Database setup guide

Hindsight supports Oracle Database 23ai as a storage backend, but the docs
only mentioned it in passing — a one-paragraph note on the Storage page and a
couple of Configuration reference rows, with no `oracle+oracledb://` example
anywhere. This adds a dedicated Oracle Database page under Hosting.

The guide covers requirements (Oracle 23ai, the ASSM-tablespace requirement
for VECTOR columns, Oracle Text / CTXAPP), installing the python-oracledb
driver, a local quick start via scripts/dev/start-oracle.sh, production
provisioning SQL + connection URL + env vars + migrations, a config reference,
the differences from PostgreSQL, and troubleshooting. Content is grounded in
the CI Oracle job, the dev script, and the backend code.

Registered in the sidebar and cross-linked from Storage and Configuration.
Regenerated the docs agent-skill and mirrored the change into
versioned_docs/version-0.8 so it ships on the currently-served version.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PginSDrapXsoDd6gN5Pszo

* docs(oracle): correct managed-service note, add connection caveat

The connection layer builds the Oracle DSN from the URL as a plain
host:port/service_name descriptor — wallet-based mTLS, TLS/TCPS, and TNS
aliases / full connect descriptors are not wired up. The previous "Least
privilege" note implied Oracle Autonomous Database works via an
ADMIN-provisioned user, which is misleading since ADB defaults to wallet/mTLS.

- Reworded the managed-service note to drop the specific ADB claim while
  keeping the accurate requirement (ASSM tablespace + CTXAPP).
- Added an "Easy Connect only" warning documenting that wallet/mTLS/TLS and
  TNS descriptors are unsupported, and that transport encryption must be
  handled at the network layer.

Applied to the current and version-0.8 copies; regenerated the docs skill.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PginSDrapXsoDd6gN5Pszo

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-07-07 14:58:03 -07:00

3.3 KiB

Raw Permalink Blame History

Storage

Hindsight uses PostgreSQL as its primary storage backend, with Oracle AI Database available as an alternative for enterprise deployments.

Why PostgreSQL?

PostgreSQL provides all capabilities required for a semantic memory system in a single database:

Capability	Implementation
Vector search	pgvector extension with HNSW indexes
Full-text search	Built-in tsvector with GIN indexes
Relational data	Native PostgreSQL
JSON documents	JSONB with indexing
Graph queries	Recursive CTEs

Reduced System Dependencies

Building exclusively for PostgreSQL simplifies deployment and operations:

Single connection string to configure
Single backup and restore strategy
Single monitoring target
ACID transactions across all data types
Single upgrade path

No Storage Abstraction

Hindsight does not abstract storage behind a generic interface. This is a deliberate trade-off.

We believe PostgreSQL is becoming the standard database API. Its popularity, extension ecosystem, and modularity mean that PostgreSQL-compatible interfaces are appearing everywhere—from serverless offerings to distributed databases. Building for PostgreSQL today means compatibility with a growing ecosystem tomorrow.

Supporting multiple databases would increase flexibility but conflict with our core goals: Hindsight is fully open source and designed to be as simple as possible to run and use. Adding database abstractions introduces complexity in code, testing, documentation, and operations—complexity that we pass on to users.

By building on PostgreSQL, we keep the system simple:

One set of deployment instructions
One set of performance characteristics to understand
One codebase optimized for one backend
No configuration decisions about which database to use

Oracle AI Database Support

For enterprise deployments, Hindsight also supports Oracle AI Database with full feature parity. All memory operations—retain, recall, and reflect—work identically on Oracle, making it a drop-in option for organizations that standardize on Oracle infrastructure.

See the Oracle Database guide for setup: prerequisites, provisioning, connection URLs, migrations, and the differences from PostgreSQL.

Development with pg0

For local development, Hindsight uses pg0—an embedded PostgreSQL distribution.

What is pg0?

pg0 is a single binary containing:

PostgreSQL server
pgvector extension (pre-installed)
Automatic initialization

Behavior

When no HINDSIGHT_API_DATABASE_URL is configured, Hindsight:

Starts an embedded PostgreSQL instance on port 5555
Initializes the schema
Stores data in ~/.hindsight/pg0/

Environments

Environment	Database	Configuration
Development	pg0 (embedded)	Automatic
Production	PostgreSQL 15+	`HINDSIGHT_API_DATABASE_URL` environment variable

Requirements

PostgreSQL 15 or later
pgvector 0.5.0 or later

Any PostgreSQL instance that satisfies these requirements should work. If you encounter issues with a specific setup, open a GitHub issue.

Tested Managed Services

AWS RDS (PostgreSQL 15+)
Google Cloud SQL
Azure Database for PostgreSQL
Supabase
Neon

3.3 KiB Raw Permalink Blame History