QueryCraft is a review-first, AI-assisted SQL workbench. It connects to an existing PostgreSQL, MySQL, or SQLite database, builds a versioned schema snapshot, turns natural-language questions into editable SQL through OpenRouter, and executes only after dialect-aware validation and explicit confirmation.
QueryCraft is maintained as a HubZero Build. Historical design context is preserved in the Project Knowledge Package; archived source repositories are not part of this production codebase.
- GitHub authentication and user-owned resources
- Encrypted PostgreSQL, MySQL, and SQLite connection configuration
- Schema introspection, versioned snapshots, and relevance-based AI context
- Streaming, structured SQL generation through OpenRouter
- Editable Monaco SQL artifacts with explanations, assumptions, warnings, and usage metadata
- AST-based, read-only validation with a separate confirmation boundary
- Time, row, and response-size constrained execution with cancellation
- Virtualized results, CSV/JSON export, conversations, history, and saved queries
- Persisted preferences, onboarding, audit records, health checks, and structured metrics
Generated SQL never executes automatically.
QueryCraft is a single full-stack Next.js application. Feature modules own their UI, validation, types, and server services; Route Handlers are thin authenticated transport boundaries.
Browser
| Auth.js session + typed Route Handlers
v
Next.js application
|-- Conversations -> schema context -> AIService -> OpenRouter
|-- Connections -> metadata providers -> customer databases
`-- Executions -> AST policy -> read-only providers -> bounded results
|
`-> Prisma -> MongoDB (metadata and audit records; no result rows)
Architecture decisions are recorded in docs/architecture. Operational documentation starts with docs/deployment.md, docs/security.md, and docs/operations.md.
Next.js 15 App Router, React 19, strict TypeScript, Tailwind CSS, shadcn/ui conventions, Prisma with MongoDB, Auth.js, OpenRouter, Zod, React Hook Form, TanStack Query, Monaco Editor, and native database drivers.
| Capability | Support |
|---|---|
| Databases | PostgreSQL, MySQL, SQLite |
| AI provider | OpenRouter only |
| Authentication | GitHub OAuth through Auth.js |
| Application store | MongoDB replica set or MongoDB Atlas |
Use a dedicated, database-native read-only account for PostgreSQL and MySQL. SQLite files must already exist on the application host and are opened read-only.
- Node.js 20.9 or newer
- npm 10 or newer
- MongoDB replica set or MongoDB Atlas
- GitHub OAuth application
- OpenRouter API key
MongoDB transactions are required by Prisma and Auth.js; a standalone MongoDB server is not sufficient.
git clone https://github.com/HubZeroHQ/querycraft.git
cd querycraft
npm ci
cp .env.example .env.local
npm run prisma:generate
npm run prisma:push
npm run devOpen http://localhost:3000.
| Variable | Required | Purpose |
|---|---|---|
DATABASE_URL |
Yes | MongoDB replica-set/Atlas connection string |
AUTH_SECRET |
Yes | Auth.js secret, at least 32 characters |
AUTH_GITHUB_ID |
Yes | GitHub OAuth client ID |
AUTH_GITHUB_SECRET |
Yes | GitHub OAuth client secret |
AUTH_TRUST_HOST |
Production | Trust the reverse-proxy host forwarded to Auth.js |
OPENROUTER_API_KEY |
Yes for generation | Server-only OpenRouter credential |
OPENROUTER_SITE_URL |
Yes | Public URL sent in OpenRouter attribution headers |
OPENROUTER_APP_NAME |
No | Attribution name; defaults to QueryCraft |
CONNECTION_ENCRYPTION_KEY |
Yes for connections | Base64 encoding of exactly 32 random bytes |
NEXT_PUBLIC_APP_URL |
Yes | Canonical public application URL |
Generate secrets with openssl rand -base64 32. Never commit .env files or rotate the connection key without re-encrypting saved credentials.
npm run checkThe aggregate check formats nothing and runs Prettier, ESLint, TypeScript, all tests, Prisma validation, and the production build. Individual commands remain available in package.json.
Tests do not call OpenRouter. The SQLite execution suite uses a temporary local database; persistence tests start an ephemeral MongoDB replica set.
Build with npm ci, npm run prisma:generate, and npm run build, then run npm start behind an HTTPS reverse proxy. Preserve streaming responses, forward request IDs, and allow the configured execution and AI timeouts. A single execution instance is the supported initial topology because cancellation and rate limiting are process-local.
See docs/deployment.md for the complete startup and network model.
Credentials are AES-256-GCM encrypted and decrypted only in server services. Every resource is scoped to the authenticated user. Mutations enforce same-origin checks and rate limits. SQL passes an AST policy and a database-native read-only boundary before execution. Result rows are returned to the current browser but are not stored in MongoDB.
Security assumptions and responsible disclosure guidance are documented in docs/security.md. Do not submit sensitive connection information in a public issue.
Before opening a pull request:
- Keep changes within the feature-based architecture.
- Add or update tests for changed behavior.
- Update current-state documentation and add an ADR for significant architectural decisions.
- Run
npm run check.
Use GitHub issues for reproducible bugs and focused proposals. See CONTRIBUTING.md for the full workflow.
No open-source license has been selected yet. Until a license file is added, copyright remains with HubZero and the source is not licensed for redistribution. Selecting and publishing the intended license is a release-blocking owner decision before tagging v1.0.0.