SQL Editor & Autocomplete
Relevant source files
The following files were used as context for generating this wiki page:
The SQL Editor & Autocomplete system in KamehaDB provides a high-performance environment for writing and executing database queries. It leverages the Monaco Editor to provide features expected in professional IDEs, including syntax highlighting, complex autocomplete suggestions, and direct execution of SQL statements.
The system is designed to be "schema-aware," meaning it uses metadata from the connected database—such as table names, column structures, and foreign key relationships—to provide context-sensitive hints. It also integrates with the AI Chat Panel to allow users to run AI-generated queries directly within the editor environment.
Sources: PLAN.md:15-18, apps/desktop/src/components/sql-editor.tsx:142-160, README.md:14-16
Architecture and Components
The SQL Editor is a React-based component that interacts with several internal libraries and external sidecar APIs. It serves as the primary interface for the "Query" workspace tab.
Component Structure
The editor is built upon the @monaco-editor/react package. When initialized, it registers a custom completion provider that interfaces with the local autocomplete library.
The diagram above shows the relationship between the UI components and the logic used for both suggestion generation and query execution.
Sources: apps/desktop/src/components/sql-editor.tsx:135-155, PLAN.md:118-124
Data Flow for Query Execution
When a user triggers a query (via the UI button or Ctrl+Enter), the system flows through a mutation hook that communicates with the Node sidecar.
- Input: User types SQL in the Monaco instance.
- State Management: Local state updates and persists the SQL to the active tab store.
- Mutation: The
useRunQueryhook sends the SQL string to the sidecar. - Result Processing: The returned
QueryResultis rendered in aQueryResultTable.
Sources: apps/desktop/src/components/sql-editor.tsx:114-133, packages/shared/src/index.ts:55-61
Context-Aware Autocomplete
The autocomplete engine is a client-side library found in sql-autocomplete.ts. It provides specialized suggestions based on the cursor position and the SQL keywords preceding it.
Suggestion Logic
The engine categorizes suggestions into keywords, tables, columns, and special "FK conditions."
| Suggestion Type | Trigger Context | Description |
|---|---|---|
| Table | After FROM, JOIN, UPDATE, INTO | Lists schema-qualified tables (e.g., public.users). |
| Column | After SELECT, WHERE, ORDER BY, or table. | Lists columns belonging to identified tables in the query. |
| FK Condition | After ON in a JOIN clause | Suggests equality joins based on foreign key metadata. |
| Keyword | General typing | Standard SQL commands and operators. |
Sources: apps/desktop/src/lib/sql-autocomplete.ts, apps/desktop/src/lib/tests/sql-autocomplete.test.ts:50-100
Foreign Key Join Hints
A unique feature of the autocomplete system is the ability to suggest join conditions automatically by analyzing the foreign key relationships of the tables involved in the query.
This logic ensures that developers do not need to remember specific relationship mappings while writing complex joins.
Sources: apps/desktop/src/lib/tests/sql-autocomplete.test.ts:114-150, apps/desktop/src/lib/sql-autocomplete.ts
Results and Exporting
Executed queries return a QueryResult object, which is displayed in a dense, interactive table.
Query Result Table Features
The QueryResultTable component includes:
- Column Resizing: Implemented via the
useColumnResizehook. - Null Visualization: Explicitly renders
NULLvalues in italics to distinguish them from empty strings. - Metadata Display: Shows row counts and execution duration in milliseconds.
- Record Details: Clicking a row opens a
Sheetcontaining theRecordDetailTabsfor deep inspection of JSON or large fields.
Sources: apps/desktop/src/components/sql-editor.tsx:43-98, packages/shared/src/index.ts:55-61
Export Capabilities
KamehaDB supports exporting the visible result set into multiple formats. This is handled via the downloadResult utility called from a dropdown menu.
| Format | Description |
|---|---|
| CSV | Comma-separated values for spreadsheet compatibility. |
| JSON | Standard JSON array of objects. |
| SQL | Generated INSERT statements based on the result rows. |
Sources: apps/desktop/src/components/sql-editor.tsx:100-110, README.md:120-123
Safety and Read-Only Mode
To prevent accidental data loss, the editor respects a "Read-Only" configuration defined at the connection level.
SQL Safety Guard
The isQuerySafe utility in packages/shared performs a regex-based check on incoming SQL strings. It identifies destructive keywords and blocks them if the connection is in read-only mode.
- Blocked Keywords:
DROP,TRUNCATE,ALTER,CREATE,INSERT,UPDATE,DELETE,MERGE,GRANT,REVOKE. - Permitted Keywords:
SELECT,WITH,SHOW,DESCRIBE,EXPLAIN.
Sources: packages/shared/src/index.ts:474-510, PLAN.md:323-332
Integration with AI Chat
The AI Chat Panel integrates deeply with the SQL Editor. When the AI generates a code block tagged as sql, the UI provides two primary actions:
- Insert into editor: Opens a new query tab and populates it with the generated SQL.
- Run SQL: Opens a new query tab, populates the SQL, and immediately executes the query.
// Example of the Run SQL integration
onRun={
block.language === 'sql'
? () => {
if (!connectionId) return;
openQueryTabWithSql(connectionId, block.value, true);
}
: undefined
}
Sources: apps/desktop/src/components/ai-chat-panel.tsx:110-128, apps/desktop/src/components/ai-chat-panel.tsx:210-230
Conclusion
The SQL Editor & Autocomplete module provides a robust, schema-aware environment that minimizes manual typing through intelligent FK-based hints and AI integration. By combining the power of Monaco with a custom local autocomplete library and strict safety guards, it offers a secure and efficient workflow for managing various database engines within a single desktop application.