DataQuery Pro

AI-powered database visualization and query tool - ask questions about your data in plain English

DataQuery Pro lets you connect to PostgreSQL, MySQL, SQL Server, and SQLite databases, explore schemas with AI-generated descriptions, and query your data using natural language that automatically converts to SQL with dialect-specific syntax.

Features

• Multi-Database Support - Connect to PostgreSQL, MySQL, SQL Server, or SQLite databases
• Natural Language Queries - Convert plain English questions to SQL using OpenAI
• Query Enhancement - Let AI improve your vague queries with specific details from your schema
• Self-Correcting Queries - When queries fail, AI automatically revises them to fix errors
• Schema Introspection - Automatically discover database structure, tables, and relationships
• AI Descriptions - Generate business-focused descriptions for tables and columns
• Query Results Visualization - View data as tables or various chart types
• Smart Column Types - Auto-detects column types (text, number, currency, date, URL) with manual override
• Saved Reports - Save queries as parameterized reports for reuse
• AI Suggestions - Get smart metric and report recommendations based on your schema
• Follow-Up Questions - Ask follow-up questions about your query results to drill deeper
• Server Configuration - Deploy pre-configured connections via config/databases.json for teams
• Rate Limiting & BYOK - Optional rate limiting with bring-your-own-key bypass for demos
• Authentication - Optional Authentik SSO with per-user data isolation, sharing, and admin controls
• Eval Harness - Measure NL→SQL accuracy, latency, and cost across models with pnpm eval (evals/README.md)
• Dark/Light Mode - Full theme support for comfortable viewing

---

Screenshots

Dashboard

The dashboard provides an overview of your connected database, saved reports, and AI-generated suggestions for metrics you might find valuable.

Initial dashboard before connecting a database

Dashboard with active connection, reports, and AI suggestions

Light Mode

---

Database Connection

Add your database credentials to get started. DataQuery Pro supports PostgreSQL, MySQL, SQL Server, and SQLite. The connection card shows status, table count, and schema upload state.

Enter your database connection details

Connection established with schema uploaded indicator

---

Schema Explorer

Browse your database structure with AI-generated descriptions that explain each table's business purpose.

View all tables in your database

Expand tables to see columns, types, and constraints

Light Mode

---

AI-Generated Descriptions

Click "Generate AI Descriptions" to automatically create business-focused descriptions for every table and column in your schema. These descriptions help the AI understand your data better, resulting in more accurate query generation.

Tables with AI-generated descriptions explaining their business purpose

Expanded table showing column-level AI descriptions with data types and constraints

---

Natural Language Queries

Ask questions about your data in plain English. DataQuery Pro converts your question to SQL, shows the confidence level, and provides an explanation.

The query interface

Enter your question in natural language

AI generates SQL with confidence score and explanation

---

Enhance Query with AI

Not sure how to phrase your question? Type a simple query and click "Enhance Query with AI" to let the AI expand it with specific tables, columns, and business logic from your schema.

A simple "show revenue by month" query enhanced with detailed instructions about which tables, columns, and aggregations to use

---

Self-Correcting Queries

When a query fails due to errors (like referencing a non-existent table), click "Revise Query" to let the AI automatically fix the problem. The AI analyzes the error, searches your schema for alternatives, and generates a corrected query.

Query failed with table not found error - click "Revise Query" to fix

AI automatically corrected the query, using the correct table from the schema

---

Query Results

View your results as a sortable, searchable table or visualize them as charts. Each column is automatically typed (text, number, currency, date, URL) based on its name and values, with smart formatting applied:

• Currency columns - Detected by column name (e.g., revenue, price, total) and formatted as $1,234.56
• URL columns - Rendered as clickable links with an external link icon
• Date columns - Formatted for readability
• Number columns - Formatted with locale-appropriate separators

Click the type badge on any column header to manually override the detected type.

Table view with search and export options

Automatic chart generation from your data

Light Mode

---

Follow-Up Questions

After viewing results, ask follow-up questions to drill deeper into your data. The AI generates new queries based on your original results and question.

Ask a follow-up question about your results

AI generates a new query based on your follow-up question, shown in a separate tab

---

Saved Reports

Save frequently used queries as reports for quick access. Reports can include parameters for flexible reuse.

Save queries as named reports with descriptions

Manage and run your saved reports

---

Quick Start

Option 1: Docker (Recommended)

# Clone the repository
git clone <repository-url>
cd dashboard

# Create environment file
cp .env.example .env.local
# Add your OpenAI API key to .env.local
# Optionally configure Authentik auth vars (see "Authentication with Authentik" below)

# Start with Docker Compose (includes PostgreSQL for app data)
docker-compose up

Docker Compose includes a PostgreSQL database for app data. When auth env vars are not set, the app uses localStorage as before.

Option 2: Local Development

# Install dependencies (pnpm required)
pnpm install

# Create environment file
cp .env.example .env.local

# Add your OpenAI API key to .env.local
# OPENAI_API_KEY=sk-...

# Start development server
pnpm dev

Open http://localhost:3000 in your browser.

Option 3: Local Development with Authentication (Authentik)

To test the full multi-user experience with OIDC authentication locally, use the included docker-compose.auth-test.yml which starts Authentik, an app database, and a demo database:

# 1. Start all containers (Authentik + app DB + demo DB)
docker compose -f docker-compose.auth-test.yml up -d
#   OR with Podman: podman-compose -f docker-compose.auth-test.yml up -d

# 2. Wait ~60 seconds for Authentik to initialize, then run setup
bash scripts/setup-authentik.sh

# 3. Copy the output env vars into .env.local (also add OPENAI_API_KEY)

# 4. Install and start
pnpm install
pnpm dev

Open http://localhost:3000 — you'll see a "Sign in with Authentik" login page.

Test accounts:

Username	Password	Role
testadmin	testadmin123	Admin (manage server connections at /admin)
testuser	testuser123	Regular user

Services started by docker-compose.auth-test.yml:

Service	Port	Purpose
authentik-server	localhost:9000	Authentik identity provider
app-db	localhost:5432	DataQuery Pro app database
demo-db	localhost:5433	Demo data (CloudMetrics) for testing queries

Authentik admin UI: http://localhost:9000/if/admin/ (login: akadmin / admin)

The demo database can be added as a server connection from the Admin page:

• Host: localhost, Port: 5433, Database: cloudmetrics, User: demo, Password: demo

See docs/guides/authentication-testing.md for detailed troubleshooting and testing scenarios.

---

Setup Flow

1. Create Connection - Add your database credentials on the Database page (PostgreSQL, MySQL, SQL Server, or SQLite)
2. Introspect Schema - Click "Introspect" to discover tables and columns
3. Generate Descriptions - Let AI describe your data for better query understanding (optional but recommended)
4. Upload Schema - Click "Upload Schema File" to enable natural language queries
5. Start Querying - Go to the Query page and ask questions in plain English

Server Configuration (Optional)

For team deployments, you can provide pre-configured database connections via a server-side config file:

1. Copy config/databases.json.example to config/databases.json
2. Update with your shared database credentials
3. Deploy the config file with your application
4. All users will automatically see these connections marked as "Server Config"
5. Server connections cannot be edited/deleted through the UI

See config/README.md for detailed setup instructions.

---

Demo Database

To try DataQuery Pro with sample data, demo database scripts are provided for all supported database types in the scripts/ folder:

PostgreSQL

# Start PostgreSQL container
docker run -d \
  --name cloudmetrics-db \
  -e POSTGRES_USER=demo \
  -e POSTGRES_PASSWORD=demo \
  -e POSTGRES_DB=cloudmetrics \
  -p 5433:5432 \
  postgres:15

# Load demo data
docker exec -i cloudmetrics-db psql -U demo -d cloudmetrics < scripts/demo-database.sql

# Connection: localhost:5433, database: cloudmetrics, user: demo, password: demo

Note: If using docker-compose.auth-test.yml (see Option 3 above), the demo database is already included and pre-loaded — no need to start it separately.

MySQL

# Start MySQL container
docker run -d \
  --name dataquery-mysql \
  -e MYSQL_ROOT_PASSWORD=rootpass \
  -e MYSQL_DATABASE=demo \
  -e MYSQL_USER=demo \
  -e MYSQL_PASSWORD=password \
  -p 3306:3306 \
  mysql:8

# Load demo data
docker exec -i dataquery-mysql mysql -udemo -ppassword demo < scripts/demo-database-mysql.sql

# Connection: localhost:3306, database: demo, user: demo, password: password

SQL Server

# Start SQL Server container
docker run -d \
  --name dataquery-sqlserver \
  -e ACCEPT_EULA=Y \
  -e SA_PASSWORD=Strong@Password1 \
  -p 1433:1433 \
  mcr.microsoft.com/mssql/server:2022-latest

# Create database and load demo data
docker exec -i dataquery-sqlserver /opt/mssql-tools18/bin/sqlcmd \
  -S localhost -U sa -P 'Strong@Password1' -C \
  -Q "CREATE DATABASE demo"
docker exec -i dataquery-sqlserver /opt/mssql-tools18/bin/sqlcmd \
  -S localhost -U sa -P 'Strong@Password1' -d demo -C \
  -i /dev/stdin < scripts/demo-database-sqlserver.sql

# Connection: localhost:1433, database: demo, user: sa, password: Strong@Password1

SQLite

# Create SQLite database (no container needed)
mkdir -p data
sqlite3 data/demo.db < scripts/demo-database-sqlite.sql

# Connection: filepath = ./data/demo.db

The demo database includes tables for organizations, subscriptions, products, invoices, usage events, support tickets, and more - perfect for exploring business analytics queries.

---

Landing Page

A product landing page is available at /landing showcasing features, screenshots, and installation instructions. See app/landing/README.md for customization details.

---

Documentation

Comprehensive developer documentation is available in the docs folder:

Topic	Link
Documentation Index	docs/README.md
File Map (where things live)	docs/reference/file-map.md
Architecture Overview	docs/architecture/overview.md
State Management	docs/architecture/state-management.md
Auth & Data Layer	docs/architecture/auth-and-data-layer.md
API Reference	docs/api/overview.md
Component Guide	docs/components/overview.md
Data Models	docs/models/overview.md
Getting Started Guide	docs/guides/getting-started.md
Authentication Testing	docs/guides/authentication-testing.md
OpenAI Integration	docs/guides/openai-integration.md
Testing Plan	docs/testing/README.md
NL→SQL Eval Harness	evals/README.md

---

Tech Stack

Layer	Technology
Framework	Next.js 15 (App Router)
UI	React 19, shadcn/ui, Tailwind CSS
State	React Context + localStorage / PostgreSQL
Auth	Auth.js v5 (next-auth) with Authentik OIDC
Databases	PostgreSQL, MySQL, SQL Server, SQLite
AI	OpenAI API (Responses API)
Charts	Recharts

---

Commands

pnpm dev              # Start development server
pnpm build            # Build for production
pnpm start            # Start production server
pnpm lint             # Run linter
docker-compose up     # Start with Docker (includes build)
docker-compose up -d  # Start in detached mode

---

Environment Variables

Create a .env.local file with:

OPENAI_API_KEY=sk-...    # Required for AI features
OPENAI_MODEL=gpt-5.6-sol # Required by query generation (no fallback); other AI endpoints default per-route
OPENAI_REASONING_EFFORT= # Optional: none|minimal|low|medium|high|xhigh|max for query generation (gpt-5/o-series only; empty = provider default)
EVAL_ALLOW_MODEL_OVERRIDE= # Optional (default off): set to "true" to let the eval harness override model/effort per request
DEMO_RATE_LIMIT=         # Optional: limit API requests per IP per 24h (empty = unlimited)
TRUSTED_PROXIES=         # Optional: comma-separated trusted proxy IPs for rate limiting

Rate Limiting & Bring Your Own Key (BYOK)

For demo deployments, you can limit OpenAI API usage per IP address:

• DEMO_RATE_LIMIT: Set to a number (e.g., 10) to limit requests per 24-hour window per IP
• User API Keys: Users can bypass rate limits by providing their own OpenAI API key via the settings dialog
• Leave DEMO_RATE_LIMIT empty or unset to disable rate limiting

Authentication with Authentik (Optional)

DataQuery Pro supports optional multi-user authentication via Authentik using OpenID Connect. When enabled, all user data (connections, schemas, reports) is stored in a PostgreSQL application database instead of localStorage, with per-user isolation and sharing capabilities.

When authentication is not configured, the app works exactly as before using localStorage.

Prerequisites

• An Authentik instance (self-hosted or cloud)
• A PostgreSQL database for the application (separate from any databases you query)

1. Create an Authentik Application

1. In Authentik, go to Applications > Providers and create a new OAuth2/OpenID Provider
2. Set the Redirect URI to http://localhost:3000/api/auth/callback/authentik (adjust host/port for production)
3. Under Advanced Protocol Settings, add groups to the Scopes (the app requests openid email profile groups)
4. Go to Applications and create a new application linked to the provider
5. Note the Client ID, Client Secret, and Issuer URL (e.g., https://auth.example.com/application/o/dataquery-pro/)

2. Create an Admin Group (Optional)

1. In Authentik, go to Directory > Groups and create a group (e.g., dataquery-admins)
2. Add users who should have admin access to this group
3. Admins can manage server connection assignments in the app's admin panel at /admin

3. Configure Environment Variables

Add these to your .env.local:

# Authentication (all 3 required to enable auth mode)
AUTH_OIDC_ISSUER=https://auth.example.com/application/o/dataquery-pro/
AUTH_OIDC_CLIENT_ID=your-client-id
AUTH_OIDC_CLIENT_SECRET=your-client-secret
AUTH_SECRET=your-random-secret          # Generate with: openssl rand -hex 32

# Admin group name (must match the Authentik group name)
AUTH_ADMIN_GROUP=dataquery-admins

# App database for storing user data (required when auth is enabled)
APP_DATABASE_URL=postgres://user:pass@localhost:5432/dataquery_app

# Encryption key for database connection passwords (required when auth is enabled)
APP_ENCRYPTION_KEY=your-64-char-hex     # Generate with: openssl rand -hex 32

4. Create the App Database

# Create the PostgreSQL database
createdb dataquery_app

# Or with Docker
docker exec -i your-postgres-container psql -U postgres -c "CREATE DATABASE dataquery_app"

The app automatically runs migrations on startup to create the required tables.

How It Works

Feature	Without Auth (Default)	With Auth
Data storage	localStorage	PostgreSQL (encrypted)
User isolation	Single user	Per-user with sharing
Connection passwords	Plain text in browser	AES-256-GCM encrypted in database
Login	None	SSO via Authentik
Admin panel	N/A	/admin for server connection management

• Data migration: On first login, if you have existing data in localStorage, a migration dialog will offer to import it into your account
• Sharing: Connections and reports can be shared with other users with configurable permissions (view/edit/admin)
• Server connections: Admins can assign server-configured connections (config/databases.json) to specific users or Authentik groups via the admin panel
• Session strategy: Uses JWT tokens (no server-side session storage required)

---

Roadmap

• Support additional database types (MySQL, SQLite, MSSQL) - Completed!
• Enhanced chart creation and customization
• Team collaboration features - Completed! (Authentik SSO, per-user data, sharing, admin panel)
• Query history and favorites - Completed! (report favorites + device-local query history at /history)

---

License

MIT