refactor(env)!: rename database configuration environment variables

BREAKING CHANGE: Migrate from legacy `HTM_DB*` format to new `HTM_DATABASE__*` namespaced variables for improved clarity and consistency

Author: MadBomber

.architecture/decisions/adrs/001-use-postgresql-timescaledb-storage.md

@@ -115,7 +115,7 @@ We will use **PostgreSQL with TimescaleDB** as the primary storage backend for H
 ### Connection Configuration
 ```ruby
 # Via environment variable (preferred)
-ENV['HTM_DBURL'] = "postgresql://user:pass@host:port/dbname?sslmode=require"
+ENV['HTM_DATABASE__URL'] = "postgresql://user:pass@host:port/dbname?sslmode=require"
 
 # Parsed into connection hash
 {

.architecture/decisions/adrs/011-database-side-embedding-generation-with-pgai.md

@@ -284,7 +284,7 @@ LIMIT $3;
 ruby enable_extensions.rb
 
 # 2. Run database schema with triggers
-psql $HTM_DBURL < sql/schema.sql
+psql $HTM_DATABASE__URL < sql/schema.sql
 
 # 3. Use HTM normally - embeddings automatic!
 ruby -r ./lib/htm -e "HTM.new(robot_name: 'Bot').add_node('test', 'value')"
@@ -294,16 +294,16 @@ ruby -r ./lib/htm -e "HTM.new(robot_name: 'Bot').add_node('test', 'value')"
 
 ```bash
 # 1. Backup database
-pg_dump $HTM_DBURL > htm_backup.sql
+pg_dump $HTM_DATABASE__URL > htm_backup.sql
 
 # 2. Enable pgai extension
 ruby enable_extensions.rb
 
 # 3. Apply new schema (adds triggers)
-psql $HTM_DBURL < sql/schema.sql
+psql $HTM_DATABASE__URL < sql/schema.sql
 
 # 4. (Optional) Regenerate embeddings with new model
-psql $HTM_DBURL -c "UPDATE nodes SET value = value;"
+psql $HTM_DATABASE__URL -c "UPDATE nodes SET value = value;"
 # This triggers embedding regeneration for all nodes
 ```
 

.architecture/decisions/adrs/012-llm-driven-ontology-topic-extraction.md

@@ -333,7 +333,7 @@ htm.add_node('memory_001', 'PostgreSQL with TimescaleDB handles time-series data
 HTM::Database.migrate
 
 # 2. (Optional) Re-extract topics for existing nodes
-psql $HTM_DBURL -c "UPDATE nodes SET value = value;"
+psql $HTM_DATABASE__URL -c "UPDATE nodes SET value = value;"
 # Triggers topic extraction for all existing nodes
 ```
 

.envrc

@@ -2,35 +2,22 @@
 
 export RR=`pwd`
 
-export RAILS_ENV=development
+export HTM_ENV=development
 export HTM_EXTRACT_PROPOSITIONS=true
 
 # Database connection - Localhost PostgreSQL
-export HTM_DBHOST=localhost
-export HTM_DBPORT=5432
-export HTM_DBNAME=htm_development
-export HTM_DBUSER=${USER}
-export HTM_DBPASS=
-export HTM_DBURL="postgresql://${HTM_DBUSER}@${HTM_DBHOST}:${HTM_DBPORT}/${HTM_DBNAME}?sslmode=disable"
-# export HTM_DBURL="postgresql://dewayne@localhost:5432/htm_development"
-
-# Uncomment if using TimescaleDB Cloud instead:
-# export HTM_SERVICE_NAME=$TIGER_SERVICE_NAME
-# export HTM_DBURL=$TIGER_DBURL
-# export HTM_DBNAME=$TIGER_DBNAME
-# export HTM_DBUSER=$TIGER_DBUSER
-# export HTM_DBPASS=$TIGER_DBPASS
-# export HTM_DBHOST=$TIGER_DBHOST
-# export HTM_DBPORT=$TIGER_DBPORT
+export HTM_DATABASE__HOST=localhost
+export HTM_DATABASE__PORT=5432
+export HTM_DATABASE__NAME=htm_development
+export HTM_DATABASE__USER=${USER}
+export HTM_DATABASE__PASSWORD=
+export HTM_DATABASE__URL="postgresql://${HTM_DATABASE__USER}@${HTM_DATABASE__HOST}:${HTM_DATABASE__PORT}/${HTM_DATABASE__NAME}?sslmode=disable"
 
 # Client-side embedding generation
-# HTM generates embeddings before inserting into database
-export HTM_EMBEDDINGS_PROVIDER=ollama
-export HTM_EMBEDDINGS_MODEL=embeddinggemma
-export HTM_EMBEDDINGS_BASE_URL=http://localhost:11434
-export HTM_EMBEDDINGS_DIMENSION=768
+export HTM_EMBEDDING__PROVIDER=ollama
+export HTM_EMBEDDING__MODEL=embeddinggemma
+export HTM_EMBEDDING__DIMENSIONS=768
 
 # Topic extraction (client-side)
-export HTM_TOPIC_PROVIDER=ollama
-export HTM_TOPIC_MODEL=phi4
-export HTM_TOPIC_BASE_URL=http://localhost:11434
+export HTM_TAG__PROVIDER=ollama
+export HTM_TAG__MODEL=phi4

.irbrc

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # HTM Interactive Development Console
-# Usage: HTM_DBURL="postgresql://user@localhost:5432/htm_development" irb
+# Usage: HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_development" irb
 
 require_relative 'lib/htm'
 require 'debug_me'

.tbls.yml

@@ -1,9 +1,9 @@
 # tbls configuration for HTM database documentation
 # https://github.com/k1LoW/tbls
 
-# Database connection - uses HTM_DBURL environment variable
+# Database connection - uses HTM_DATABASE__URL environment variable
 # tbls expands environment variables with $VAR or ${VAR} syntax
-dsn: $HTM_DBURL
+dsn: $HTM_DATABASE__URL
 
 # Output documentation to docs/database directory
 docPath: docs/database

README.md

@@ -39,7 +39,7 @@ HTM includes a Model Context Protocol server with 23 tools for memory management
   "mcpServers": {
     "htm": {
       "command": "htm_mcp",
-      "env": { "HTM_DBURL": "postgresql://localhost/htm" }
+      "env": { "HTM_DATABASE__URL": "postgresql://localhost/htm" }
     }
   }
 }

Rakefile

@@ -10,16 +10,21 @@ Rake::TestTask.new(:test) do |t|
   t.verbose = true
 end
 
-# Ensure test task runs with RAILS_ENV=test
+# Ensure test task runs with HTM_ENV=test (takes priority over RAILS_ENV/RACK_ENV)
 task :test do
-  ENV['RAILS_ENV'] = 'test'
+  ENV['HTM_ENV'] = 'test'
 end
 
 # Prepend environment setup before test runs
 Rake::Task[:test].enhance [:set_test_env]
 
 task :set_test_env do
-  ENV['RAILS_ENV'] = 'test'
+  ENV['HTM_ENV'] = 'test'
+  # Set database URL if not already configured
+  # Uses current system user for local PostgreSQL connection
+  unless ENV['HTM_DATABASE__URL']
+    ENV['HTM_DATABASE__URL'] = "postgresql://#{ENV['USER']}@localhost:5432/htm_test"
+  end
 end
 
 task default: :test

config/database.yml

@@ -23,8 +23,8 @@ The seeding process uses environment variables for configuration. All settings h
 
 ### Database Settings
 
-- `HTM_DBURL` - Full PostgreSQL connection URL (required)
-- Or individual settings: `HTM_DBHOST`, `HTM_DBPORT`, `HTM_DBNAME`, `HTM_DBUSER`, `HTM_DBPASS`
+- `HTM_DATABASE__URL` - Full PostgreSQL connection URL (required)
+- Or individual settings: `HTM_DATABASE__HOST`, `HTM_DATABASE__PORT`, `HTM_DATABASE__NAME`, `HTM_DATABASE__USER`, `HTM_DATABASE__PASSWORD`
 
 ### Other Settings