D.S.T. - Databases Searching Tool

1. Overview

D.S.T. is designed for a common operational problem: the value is known, but the database table is not. A support operator, developer, administrator, reviewer, or local AI agent may need to find where an email address, phone number, reference number, customer code, ticket number, event key, or other value appears across approved SQL Server scopes.

What D.S.T. is

• A local Windows-oriented SQL Server lookup utility.
• A controlled read-only search workflow for approved databases, tables, and columns.
• A profile-backed search layer for repeatable support, review, audit, and reconciliation work.
• A Search Memory system that records human, agent, and scheduler runs.
• An optional Agent API gateway that exposes structured search, history, and scheduled run access without handing out SQL credentials.
• A desktop runtime that can run minimized in the Windows tray, start with Windows, and shut down on schedule.

What D.S.T. is not

• It is not a SQL Server permission system. SQL Server accounts must still be restricted at the database layer.
• It is not a general SQL execution API. Agent API and scheduled search endpoints reject raw SQL.
• It is not a BI platform, data catalog, or full database administration suite.
• It is not intended for direct public internet exposure.
• Cancellation is cooperative; immediate SQL query interruption depends on the ODBC driver and SQL Server behavior.

2. Quick Start

1. Extract Databases Searching Tool.zip.
2. Run Databases Searching Tool.exe.
3. Open http://127.0.0.1:8765 if the browser does not open automatically.
4. Open Search Profiles and create or review a read-only profile.
5. Set the SQL server, SQL user, credential source, allowed databases, allowed tables, allowed columns, limits, and history settings.
6. Use Check readiness, then Test connection.
7. Open Search, choose Connection mode: Search Profile, select the profile and workspace.
8. Enter the value to find, choose a match mode, optionally narrow databases/tables/columns, and run Preflight.
9. If the scope is reasonable, run Search.
10. Review results in the UI and later in Search Memory.

3. Installation and Startup

Release files

Databases Searching Tool/
  Databases Searching Tool.exe
  _internal/
DST_FINAL_DOCUMENTATION.html
Databases Searching Tool.zip

Default local URL

http://127.0.0.1:8765

CLI flags

Startup examples

# Standard local startup
& ".\Databases Searching Tool.exe" --default

# Background tray runtime
& ".\Databases Searching Tool.exe" --default --tray --minimized --no-open-browser

# Alternate local port
& ".\Databases Searching Tool.exe" --default --port 8790

4. UI Map and Screenshots

The UI is a local browser application. Closing the browser tab does not necessarily stop the D.S.T. process, especially when tray mode is enabled.

5. Search Profiles

A Search Profile is the main control boundary. It stores the approved search policy and a reference to the credential source. Scheduled searches and Agent API searches must use profiles.

Example profile

{
  "profile_id": "main_lookup_readonly",
  "name": "Main Lookup - Read Only",
  "server": "sql-host.internal,1433",
  "user": "readonly_user",
  "auth_mode": "password_env",
  "password_env": "DST_SQL_LOOKUP_PASSWORD",
  "allowed_databases": ["PrimaryDB", "ArchiveDB"],
  "allowed_tables": ["dbo.Contacts", "dbo.Orders"],
  "allowed_columns": ["Email", "Phone", "ReferenceNo"],
  "searchable_types": ["char", "varchar", "nchar", "nvarchar", "text", "int"],
  "default_match_mode": "contains",
  "max_preview_rows": 500,
  "max_export_rows": 50000,
  "default_page_size": 50,
  "max_page_size": 200,
  "max_databases_per_search": 20,
  "max_tables_per_search": 100,
  "max_columns_per_search": 500,
  "max_concurrent_searches": 2,
  "agent_enabled": true,
  "history_enabled": true,
  "history_detail_mode": "summary_only",
  "history_retention_days": 30,
  "allow_agent_export": false,
  "masking_mode": "preview",
  "audit_query_mode": "hash",
  "timeout_seconds": 60,
  "connection_timeout_seconds": 10,
  "read_only": true
}

Credential modes

$env:DST_SQL_LOOKUP_PASSWORD = "..."

cmdkey /generic:DST/SQL/main_lookup /user:readonly_user /pass:...

POST /settings/credentials/vault

Readiness and connection checks

• Check readiness verifies missing config, credential readiness, allowlist counts, and limits.
• Test connection resolves the credential server-side and runs a lightweight connection test such as SELECT 1.
• Readiness and test responses must not expose passwords, token hashes, or connection strings.

6. Searching

Match modes

Recommended search flow

1. Select Connection mode: Search Profile.
2. Select the profile and workspace.
3. Enter the query value and match mode.
4. Optionally narrow databases, tables, and columns. Blank scope means the profile allowlist, not the entire SQL Server.
5. Run Preflight to estimate databases/tables/columns to scan.
6. Run Search.
7. Cancel if the scope was wrong or the run is no longer needed.
8. Export page, stored results, or full profile-backed results when appropriate.

Export scopes

7. Search Memory

Search Memory stores search metadata, summaries, workspaces, saved searches, search plans, scheduled searches, and scheduled runs.

runtime/memory/dst.memory.sqlite3

History detail modes

Saved searches and rerun

• Save stores an approved search configuration without credentials.
• Rerun executes through the current Search Profile rules and limits.
• Refine can change query text, match mode, or narrow scope.
• Agent access to history depends on both token permissions and profile history settings.

8. Scheduled Searches

Scheduled searches run in the background through approved Search Profiles. They never accept direct SQL credentials. Results are written into Search Memory as actor_type=scheduler.

Requirements

• The profile must exist.
• The profile must have history_enabled=true.
• The profile credential source must be ready.
• The scheduled scope may only narrow profile allowlists.
• The request must not contain server, user, password, connection_string, or sql.

Recurrence types

Example scheduled search

POST /scheduled-searches
X-CSRF-Token: <csrf>
Content-Type: application/json

{
  "name": "Monitor reference REF-2026-001",
  "profile_id": "main_lookup_readonly",
  "workspace_id": "wks_...",
  "query": "REF-2026-001",
  "match_mode": "exact",
  "scope": {
    "databases": ["PrimaryDB"],
    "tables": ["dbo.Orders"],
    "columns": ["ReferenceNo"]
  },
  "page_size": 50,
  "recurrence": { "type": "interval", "every": 15, "unit": "minutes" },
  "overlap_policy": "skip",
  "enabled": true
}

Concurrency

• Global scheduler worker limit: defaults.max_scheduler_workers, default 2.
• Per-profile limit: profile.max_concurrent_searches.
• skipped_concurrency means a run did not start because an overlap or worker limit was reached.

9. Tray, Startup, Shutdown

Runtime status

GET /runtime/status

The response includes server status, tray status, host, port, URL, shutdown flags, and scheduler status.

Windows tray

& ".\Databases Searching Tool.exe" --default --tray --minimized --no-open-browser

The final packaged EXE uses the Windows GUI subsystem, so it does not open a console window. Tray mode lets the application remain available in the background.

Start with Windows

HKCU\Software\Microsoft\Windows\CurrentVersion\Run
Value: Viken Data Studio D.S.T.

The startup command points at the packaged EXE and includes:

--default --tray --minimized --no-open-browser

Scheduled shutdown modes

10. Agent API

Agent API is a controlled search gateway. It is not a SQL execution API. Agents never receive SQL credentials, connection strings, or raw SQL access.

Token permissions

Forbidden request fields

server
user
password
connection_string
sql

Example agent search

POST /api/v1/agent/search
Authorization: Bearer <token>
Content-Type: application/json

{
  "profile_id": "main_lookup_readonly",
  "query": "abc@example.com",
  "match_mode": "contains",
  "scope": {
    "databases": ["PrimaryDB"],
    "tables": ["dbo.Contacts"],
    "columns": ["Email"]
  },
  "page_size": 100,
  "async": true
}

Example search plan

POST /api/v1/agent/search-plan
Authorization: Bearer <token>
Content-Type: application/json

{
  "profile_id": "main_lookup_readonly",
  "workspace_id": "wks_...",
  "user_goal": "Find customer by email abc@example.com",
  "max_searches": 3
}

The planner accepts a user goal, not SQL. SQL-like goals are rejected with raw_sql_not_allowed.

11. Files and Runtime Data

12. Security Model

• Use SQL Server permissions first. D.S.T. does not replace database-layer access control.
• Use read-only SQL accounts wherever possible.
• Bind to 127.0.0.1 unless a deliberate network access model exists.
• Keep Agent API disabled until needed.
• Use short, scoped agent tokens and revoke them when no longer needed.
• Prefer metadata_only or summary_only history for sensitive profiles.
• Review exports before sharing them.
• Audit and diagnostics should not expose passwords, raw tokens, token hashes, or connection strings.

13. Operations

Health checks

GET /health
GET /ready
GET /diagnostics
GET /runtime/status

Backup before upgrades

config/
runtime/memory/
runtime/audit/
runtime/vault/    # if local vault is used

Upgrade checklist

1. Back up config/ and the required runtime/ directories.
2. Stop the running D.S.T. process from the tray menu or by closing the runtime explicitly.
3. Replace the application folder with the contents of the new release ZIP.
4. Start Databases Searching Tool.exe and verify /health, /ready, Search Profiles, Search Memory, Scheduler, and Agent Access.
5. Confirm startup and shutdown schedules still match the intended local Windows user account.

14. Troubleshooting

15. Endpoint Reference

Runtime and human endpoints

Agent endpoints

16. Release Verification

• OK Python compile check.
• OK Full automated test suite: 106 tests passing.
• OK Packaged EXE uses the Windows GUI subsystem and does not open a console window.
• OK EXE health/runtime smoke.
• OK Tray smoke: tray_status=running.
• OK Start with Windows create/read/delete smoke; final state disabled.
• OK Release ZIP contains the application folder and this offline documentation file.
• OK This documentation is self-contained: CSS and screenshots are embedded in the HTML.

Release artifacts

dist/Databases Searching Tool/Databases Searching Tool.exe
dist/Databases Searching Tool.zip
dist/DST_FINAL_DOCUMENTATION.html