Configure SQL Server, SemDB, entities, and sessions
Configure storage for Buffaly sessions, semantic lookup, ontology/entity discovery, and SQL-backed operational data without guessing which layer owns which data.
Who this is for
Use this guide when you need to configure SQL Server connection strings, choose file/SQL/hybrid session storage, understand how SemDB supports semantic lookup, or troubleshoot missing sessions, missing artifacts, failed semantic search, and database connectivity errors.
Keep secrets out of prompts, wiki pages, task artifacts, and commits. Report only status, logical connection-string names, or safe database names.
Storage roles
| Layer | Documented role | Evidence to verify |
|---|---|---|
| SQL Server / Sessions DB | Stores sessions, messages, artifacts, subscriptions, features, processes, and runtime/admin records. | buffaly_sessions.readwrite, Sessions.Web rows, SQL session-store behavior. |
| SemDB / SemanticDB | Stores semantic fragments and lookup data used for action/entity discovery and semantic retrieval. | buffaly_semanticdb.readwrite, SemanticDB initialization, semantic candidate search results. |
| File session store | Stores session snapshots and artifacts under the runtime sessions root. | Runtime Feature.SessionsRootPath, session.json, Plan.md, Scratch.md, artifacts. |
| Session store mode | Chooses whether runtime session state is file, SQL, or hybrid. | Infrastructure Feature.SessionStoreMode and active store behavior. |
| Ontology/project files | Define prototypes, annotations, action roots, prompt actions, and semantic names. | Active project path, project .pts files, candidate action/entity search. |
Do not collapse these into one database setting. Buffaly can use SQL Server for sessions while still using project files for ontology definitions and SemDB for semantic lookup.
Quick answer
The checked-in web host initializes two important SQL connection strings during startup:
buffaly_sessions.readwriteUsed by Buffaly sessions data access and Sessions DB data access.buffaly_semanticdb.readwriteUsed by SemanticDB data access.Runtime session storage is selected separately by Infrastructure Feature.SessionStoreMode. Source-defined canonical values are file, hybrid, database-source, and hybrid-database. Use exact tokens; wrong-cased or alias values can fail validation.
SQL Server backend
SQL Server backs Sessions.Web and database-backed runtime records. Verify sessions/messages, artifacts, subscriptions, feature JSON settings, semantic reindex processes, checkpoints, fragments, and vectors there.
SemDB
SemDB is Buffaly’s semantic database layer. It supports candidate action/entity retrieval with runtime ontology fallback when needed.
Entities and ontology storage
.pts project files define ontology and extension surfaces. SemDB indexes semantic names and fragments for retrieval. Secrets and connection strings do not belong in ordinary ontology memory.
Session storage
The active session store can be file, SQL, or hybrid. File mode is easiest to inspect on disk; SQL/database modes support central admin/search/history surfaces; hybrid modes bridge behavior.
Before you start
- Identify the active repository or install root and running web host.
- Confirm the current
buffaly_sessions.readwriteandbuffaly_semanticdb.readwritelogical targets without printing secret values. - Record
Runtime Feature.SessionsRootPathandInfrastructure Feature.SessionStoreMode. - Check whether Sessions.Web can open Dashboard, Sessions, Messages, Session Artifacts, Features, and Processes.
- Check whether semantic action/entity search and session semantic search currently work.
How to configure storage
1. Configure SQL connection strings
Verify named connection strings in the running installation configuration, not only in source. Ask Buffaly to report presence, safe logical target, and consuming implementation code without printing secrets.
2. Configure session store mode
Use settings or Features admin for Infrastructure Feature. After changing mode, verify with a new test session rather than assuming existing sessions moved stores automatically.
3. Configure Runtime Feature paths
Verify SessionsRootPath exists and the web/worker identity can read/write it. File-backed sessions should contain session.json, Plan, Scratch, artifacts, or compaction files.
4. Configure SemDB
Provision and point SemDB before relying on semantic discovery. Verify connection status, SemanticDB data access initialization, and candidate action/entity search results.
5. Configure session semantic search storage
Session semantic search uses Sessions DB rows, fragments, embeddings, and vectors. Verify the Sessions DB connection, semantic reindex process, fragments/vectors for target sessions, and embedding provider when vector search is expected.
How to verify it works
- SQL Server / Sessions DB: Dashboard, sessions, messages, Features admin, and a new test session appear in the expected store.
- Runtime session store: file, SQL, or hybrid evidence matches the configured mode.
- SemDB action/entity search: candidate search returns likely prototypes and reports whether semanticdb or fallback was used.
- Session semantic search: semantic results match exact session history or committed-file evidence, and reindex status is current enough.
Common failures and troubleshooting
Connection string missing or wrong. Verify both named connection strings; sessions and SemDB serve different layers. Do not print secret values.
Wrong session-store mode token. Use file, hybrid, database-source, or hybrid-database exactly.
Sessions visible in files but not Sessions.Web. Check store mode, sessions root, and Sessions.Web database connectivity.
Sessions visible in SQL but not on disk. This can be expected in database-source mode; verify mode before treating it as data loss.
SemDB search is stale or noisy. Verify active project and source annotations before rebuilding or reindexing semantic data.
Exact search works but semantic search does not. Verify embedding provider, vectors, and semantic reindex status.
Permissions or SQL authentication failures. Start with read-only verification of process identity, SQL login, firewall, database name, and permissions before broadening access.
How to ask Buffaly to help
Audit configuration: Inspect source first, then check buffaly_sessions.readwrite, buffaly_semanticdb.readwrite, session store mode, sessions root, Sessions.Web health, and semantic candidate search. Do not reveal secrets.
Diagnose Sessions.Web gaps: Verify active store mode, Sessions DB connection, recent session rows, and whether the session was file-backed or SQL-backed.
Verify SemDB: Search candidate actions and entities, report whether semanticdb or fallback was used, and identify stale prototype rows without changing data.
Configure SQL-backed sessions: Show supported store modes from source, propose the smallest settings change, validate with a test session, and document rollback.