QueryDB Documentation

QueryDB is a web application that lets you ask plain-English questions about your PostgreSQL database. You connect your database, choose which tables the AI can see, supply an LLM API key from a provider you already use, and start a conversation. The AI generates a safe, read-only SQL query, runs it, and returns the answer in plain English alongside the generated SQL so you can verify it.

There is no QueryDB-managed compute for your queries — your database connection string is stored server-side and queries are executed directly against your database. The LLM API key is yours; you pay your provider for tokens.

QueryDB uses email/password authentication with JWT tokens stored as httpOnly cookies. Sessions are managed server-side; there is no localStorage-based token.

Create an account with your email address and a password. After registering you will receive a verification email. You must verify your email before you can log in.

Log in with your email and password. The server returns a JWT access token which is set as an httpOnly cookie. A CSRF token cookie is also set and must be included in the X-CSRF-Token header for all subsequent requests.

Use the Forgot Password link on the login page. A reset link is emailed to you and expires after a short window. The endpoint is rate-limited to 3 requests per 15 minutes per IP.

Authenticated users can change their password from Settings by providing the current password. The new password must be different from the current one. This endpoint is rate-limited to 5 requests per 15 minutes.

A Connection is a saved link to one PostgreSQL database. You can have multiple connections in your personal workspace or in a team workspace.

Go to Connections → Add Connection. Provide a display name and a connection string:

The backend validates the connection is reachable before saving it. Duplicate active connections to the same URL are blocked. The connection is then created with schema_build_status: "created".

Deleting a connection performs a soft delete. The connection is hidden from the UI and API but retained in the database for auditing. All conversation history associated with that connection is also soft-deleted.

Before the AI can query your database you must tell it which tables and columns it is allowed to see. Open a connection from the Connections page to reach the schema configuration view.

The left panel lists every table in your database. Toggle a table to include it. When you toggle a table, all of its columns are also toggled automatically. Deselected tables are completely invisible to the AI.

Within each table you can deselect individual columns. Use this to hide sensitive columns (PII, internal flags, hashed passwords) from the AI without removing the whole table.

For each table you can add a plain-English description (e.g. "Customer purchase history"). For each column you can add a comment (e.g. "FK to users.id", "Stored in cents, not dollars"). These hints are injected into the AI prompt alongside the schema and meaningfully improve query accuracy.

If you add or rename tables in your database, click Sync Schema on the connection detail page to refresh the table list from the live database. This triggers a fresh schema discovery without losing your existing selections.

QueryDB does not include any LLM credits. You bring your own API key from one of the supported providers. Keys are encrypted server-side and the full key is never returned to the browser — only a masked version (e.g. sk-o...abcd) is displayed.

Go to API Keys → Add Key. Enter the provider name exactly as shown above, the model name exactly as the provider names it, and your API key. Each (provider, model_name) pair is stored independently so you can have multiple models active simultaneously.

Keys can be deleted from the API Keys page. Deleting a key does not affect existing conversation history, but future queries using that provider + model will fail until a new key is added.

A conversation is a persistent chat thread linked to a single database connection. Every query you run and every response the AI returns is stored in the conversation's history.

From the Query page click the New Chat button. Select the database connection to use. Optionally give it a title (1–100 characters). If you leave the title blank it defaults toNew Chat and is renamed automatically to the first 50 characters of your first query.

Right-click or use the three-dot menu on any conversation to rename or delete it. Deletion is a soft delete — the conversation and its messages are hidden from the API but retained in the database.

Conversations are listed in the sidebar grouped by time: Today, Yesterday, This Week, Last Week, This Month, Older. The list is paginated and sorted by most recent activity.

Select a conversation and type your question in the input box. Press Enter or click Send. The response includes a plain-English answer and the generated SQL query.

Each query must be sent with a provider and model name that matches a key you have previously saved. The model selector in the chat interface shows all your available keys. The backend resolves the API key using the exact (user_id, provider, model_name) triple.

Every query and response is stored and accessible from History. History is paginated and can be filtered by conversation. Each history item includes the original question, the generated SQL, the response, token counts, API call count, and duration in milliseconds.

Individual history items can be soft-deleted from the History page. Soft-deleted items are excluded from all lists and detail views but are retained in the database.

QueryDB supports multiple workspaces. By default every user has a Personal Workspace. You can additionally create Team Workspaces to share database connections with colleagues.

The workspace selector at the top of the sidebar shows your current workspace. Click it to switch between Personal Workspace and any teams you belong to. Switching workspaces clears the active conversation to prevent cross-workspace data leaks.

Click Create New Team in the workspace selector dropdown. Enter a team name. You are automatically set as the team owner.

Team owners can invite colleagues by email from the team settings. Two flows exist:

• Registered user: Added to the team immediately as a member.
• Unregistered email: An invitation email with a secure token is sent. The invitee registers and is auto-joined to the team on signup.

Invitations expire after 7 days and can be cancelled by the owner before they are accepted.