Database

Database - Guida Rapida

Come leggere, aggiornare e sincronizzare il database BlackTrails.

---

Comandi Cursor

Dico a Cursor	Cosa fa	Modifica DB?
“leggi database”	Report stato attuale	❌ No (read-only)
“aggiorna database”	Modifica schema	✅ Sì (con conferma)

Workflow Consigliato

1. Prima: "leggi database" → Vedi stato attuale
2. Poi: "aggiorna database" → Applica modifiche (se necessario)
3. Fine: Commit + push

---

Dove sono i file

BLACKTRAILS-PLATFORM

Repository con codice e runbook AI.

File	Cosa contiene
db/schema.sql	Struttura database (SQL)
docs/SCHEMA_REFERENCE.md	Tabelle in formato leggibile
docs/MIGRATION_LOG.md	Storia modifiche database
scripts/verify-db-schema.js	Script verifica live
AGENTS/cursor/LEGGI-DATABASE.md	Runbook lettura
AGENTS/cursor/AGGIORNA-DATABASE.md	Runbook modifica

BLACKTRAILS-DOCS

Repository con documentazione (questo sito).

File	Cosa contiene
private/architecture/truth/02-data-schema.md	Fonte di verità
private/area-x/infrastructure/database.md	Dettagli operativi
private/area-x/infrastructure/database-map.md	⚠️ Outdated (18 Dic)

---

Schema Attuale (25 Dic 2025)

blacktrails (Neon PostgreSQL)
├── auth          → Utenti, ruoli, magic links
├── in1           → Rhama (poesie AI)
├── elements      → Camere, prenotazioni
├── library       → Documenti, embeddings (RAG)
├── finance       → Transazioni (vuoto)
├── ai            → Chat AI (vuoto)
├── system        → Log sistema (vuoto)
└── organization  → Multi-tenant (vuoto)

Record Count

Schema	Tabelle	Record	Status
auth	3	~10	✅ Attivo
in1	1	~100	✅ Attivo
elements	2	~5	✅ Attivo
library	2	~10	✅ Attivo
finance	0	0	🚧 Vuoto
ai	0	0	🚧 Vuoto
system	0	0	🚧 Vuoto
organization	0	0	🚧 Vuoto

---

Flusso Aggiornamento

Quando modifichi il database:

graph TD
    A[Modifica DB
Neon Console] --> B[aggiorna database
Cursor]
    B --> C[Aggiorna PLATFORM
schema.sql + docs]
    C --> D[Aggiorna DOCS
02-data-schema.md]
    D --> E[Commit + Push
Deploy automatico]

Step by Step

1. Modifica Database (Neon Console)

   • Crea tabella, aggiungi colonna, etc.
   • Branch: main (production) o dev (testing)

2. Aggiorna PLATFORM (Cursor)

   Francesco: "aggiorna database"

   • Cursor legge runbook AGGIORNA-DATABASE.md
   • Esegue verify-db-schema.js
   • Aggiorna schema.sql, SCHEMA_REFERENCE.md, MIGRATION_LOG.md
   • Chiede conferma prima di modificare

3. Aggiorna DOCS (Manuale o Cursor)

   • Modifica 02-data-schema.md (Truth Zone)
   • Modifica database.md (Area-X)
   • Aggiorna sezione “Recent Updates”

4. Deploy

   git add .
   git commit -m "docs: update database schema"
   git push

   • PLATFORM: deploy Render automatico
   • DOCS: deploy Cloudflare Pages automatico

---

Troubleshooting

Errori Comuni

Problema	Causa	Soluzione
relation "users" does not exist	Nome tabella senza schema	Usa auth.users non users
schema.sql non allineato	File outdated	"aggiorna database"
Docs outdated	File non sincronizzati	Modifica 02-data-schema.md
Query fallisce dopo migration	Cache query vecchia	Restart app server

Comandi Utili

# Verifica stato database
cd E:\BLACKTRAILS-PLATFORM
node scripts/verify-db-schema.js

# Test connessione
psql $DATABASE_URL -c "SELECT NOW();"

# List schemas
psql $DATABASE_URL -c "\dn"

# List tables in schema
psql $DATABASE_URL -c "\dt auth.*"

---

Link Utili

• Neon Console: patient-queen-89181819
• PLATFORM Repo: E:\BLACKTRAILS-PLATFORM
• DOCS Repo: E:\BLACKTRAILS-DOCS
• Schema Reference: 02-data-schema.md
• Database Architecture: database.md

---

Prossimi Step

• Attivare RAG per library.embeddings (generare embeddings)
• Implementare finance schema (pagamenti Stripe)
• Creare system.audit_logs (log azioni utenti)
• Branch strategy: setup auto-sync dev → main

---

Ultimo aggiornamento: 2025-12-25
Maintainer: Francesco Pelosio
AI Agent: Cursor (con runbook LEGGI-DATABASE.md, AGGIORNA-DATABASE.md)