You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This page lists the configuration locations, skills, and database skills that Storm installs for each AI coding tool. For the main guide, see [AI-Assisted Development](ai.md).
4
+
5
+
---
6
+
7
+
## Tool Configuration Locations
8
+
9
+
Each AI tool stores its configuration in a different location, but the content is the same: Storm's conventions, entity rules, query patterns, and verification guidelines.
10
+
11
+
| Tool | Rules | Skills | MCP |
12
+
|------|-------|--------|-----|
13
+
| Claude Code | CLAUDE.md | .claude/skills/ | .mcp.json |
Skills are per-topic guides that the AI loads on demand when working on a specific task. Each skill contains focused instructions, code examples, and common pitfalls for one area of Storm. Skills are fetched from orm.st during setup and can be updated automatically on each run without requiring a CLI update.
24
+
25
+
| Skill | Purpose |
26
+
|-------|---------|
27
+
| storm-setup | Configure dependencies (detects Spring Boot, Ktor, or standalone) |
Copy file name to clipboardExpand all lines: docs/ai.md
+17-46Lines changed: 17 additions & 46 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,12 +5,8 @@ import TabItem from '@theme/TabItem';
5
5
6
6
Storm is an AI-first ORM. Entities are plain Kotlin data classes or Java records. Queries are explicit SQL. Built-in verification lets AI validate its own work before anything touches production.
7
7
8
-
:::caution Storm is not for vibe coding
9
-
Database code affects data integrity, performance, and security. Generating it without understanding or verifying the result is not something Storm encourages.
10
-
8
+
:::info AI-first, not AI-only
11
9
Storm keeps you in control. `ORMTemplate.validateSchema()` validates that entities match the database. `SqlCapture` validates that queries match the intent. `@StormTest` runs both checks in an isolated in-memory database before anything reaches production. The AI generates code, then Storm verifies it. That is what AI-first means here.
12
-
13
-
Automated verification catches mistakes, but it does not replace understanding. Your data layer is not the place to let the codebase drift away from you.
14
10
:::
15
11
16
12
---
@@ -34,57 +30,31 @@ The interactive setup walks you through three steps:
34
30
35
31
### 1. Select AI tools
36
32
37
-
Choose which AI coding tools you use. Storm configures each one with rules, skills, and (optionally) a database-aware MCP server. You can select multiple tools if your team uses different editors.
38
-
39
-
| Tool | Rules | Skills | MCP |
40
-
|------|-------|--------|-----|
41
-
| Claude Code | CLAUDE.md | .claude/skills/ | .mcp.json |
Each tool stores its configuration in a different location, but the content is the same: Storm's conventions, entity rules, query patterns, and verification guidelines.
33
+
Choose which AI coding tools you use. Storm configures each one with rules, skills, and (optionally) a database-aware MCP server. You can select multiple tools if your team uses different editors. Storm currently supports Claude Code, Cursor, GitHub Copilot, Windsurf, and Codex. Each tool stores its configuration in a different location, but the content is the same: Storm's conventions, entity rules, query patterns, and verification guidelines. See [AI Tools Reference](ai-reference.md) for the full list of configuration locations.
48
34
49
35
### 2. Rules and skills
50
36
51
37
For each selected tool, Storm installs two types of AI context:
52
38
53
39
**Rules** are a project-level configuration file that is always loaded by the AI tool. They contain Storm's key patterns, naming conventions, and critical constraints (immutable QueryBuilder, no collection fields on entities, `Ref<T>` for circular references, etc.). The rules ensure the AI follows Storm's conventions in every interaction, without you having to repeat them.
54
40
55
-
**Skills** are per-topic guides that the AI loads on demand when working on a specific task. Each skill contains focused instructions, code examples, and common pitfalls for one area of Storm. Skills are fetched from orm.st during setup and can be updated automatically on each run without requiring a CLI update.
56
-
57
-
| Skill | Purpose |
58
-
|-------|---------|
59
-
| storm-setup | Configure dependencies (detects Spring Boot, Ktor, or standalone) |
**Skills** are per-topic guides that the AI loads on demand when working on a specific task. Each skill contains focused instructions, code examples, and common pitfalls for one area of Storm (entities, queries, repositories, migrations, JSON, serialization, and more). Skills are fetched from orm.st during setup and can be updated automatically on each run without requiring a CLI update. See [AI Tools Reference](ai-reference.md#skills) for the full list.
72
42
73
43
### 3. Database connection (optional)
74
44
75
45
If you have a local development database running, Storm can set up a schema-aware MCP server. This gives your AI tool access to your actual database structure (table definitions, column types, foreign keys) without exposing credentials or data.
76
46
77
-
The MCP server runs locally on your machine, exposes only schema metadata, and stores credentials in `~/.storm/` (outside your project, outside the LLM's reach). It supports PostgreSQL, MySQL, MariaDB, Oracle, SQL Server, SQLite, and H2.
47
+
The MCP server runs locally on your machine, exposes only schema metadata by default, and stores credentials in `~/.storm/` (outside your project, outside the LLM's reach). It supports PostgreSQL, MySQL, MariaDB, Oracle, SQL Server, SQLite, and H2. You can connect multiple databases to a single project, even across different database types.
48
+
49
+
Optionally, you can enable read-only data access per connection. This lets the AI query individual records to inform type decisions — for example, recognizing that a `VARCHAR` column contains enum-like values, or that a `TEXT` column stores JSON. Data access is disabled by default because it means actual data from your database flows through the AI's context. When enabled, the database connection is read-only (enforced at both the application and database driver level), and the AI cannot write, modify, or delete data. See [Database Connections & MCP — Security](database-and-mcp.md#security) for the full details.
78
50
79
-
With the database connected, three additional skills become available:
51
+
With the database connected, three additional skills become available for schema inspection, entity validation against the live schema, and entity generation from database tables. See [AI Tools Reference](ai-reference.md#database-skills) for details.
80
52
81
-
| Skill | Purpose |
82
-
|-------|---------|
83
-
| storm-schema | Inspect your live database schema |
84
-
| storm-validate | Compare entities against the live schema |
85
-
| storm-entity-from-schema | Generate, update, or refactor entities from database tables |
53
+
To manage database connections later, use `storm db` for the global connection library and `storm mcp` for project-level configuration. See [Database Connections & MCP](database-and-mcp.md) for the full guide.
86
54
87
-
To reconfigure the database connection later, run `storm mcp`.
55
+
:::tip Looking for a database MCP server for Python, Go, Ruby, or any other language?
56
+
The Storm MCP server works standalone — no Storm ORM required. Run `npx @storm-orm/cli mcp init` to set up schema access and optional read-only data queries without installing Storm rules or skills. See [Using Without Storm ORM](database-and-mcp.md#using-without-storm-orm).
57
+
:::
88
58
89
59
---
90
60
@@ -140,12 +110,12 @@ The design choices that matter most:
140
110
-**No persistence context.** No session scope, flush ordering, or detachment rules that require deep framework knowledge.
141
111
-**Convention over configuration.** Fewer annotations and config files for the AI to keep consistent.
142
112
-**Compile-time metamodel.** Type errors caught at build time, not at runtime. The AI gets immediate feedback.
143
-
-**Secure schema access.** The MCP server gives AI tools structural database knowledge without exposing credentials or data.
113
+
-**Secure schema access.** The MCP server gives AI tools structural database knowledge without exposing credentials. Data access is opt-in, read-only by construction, and enforced at the database driver level.
144
114
145
115
Beyond the data model, Storm provides dedicated tooling for AI-assisted workflows:
146
116
147
117
-**Skills** guide AI tools through specific tasks (entity creation, queries, repositories, migrations) with framework-aware conventions and rules.
148
-
-**A locally running MCP server** gives AI tools access to your live database schema: table definitions, column types, constraints, and foreign keys. The AI can inspect your actual database structure to generate entities that match, or validate entities it just created.
118
+
-**A locally running MCP server** gives AI tools access to your live database schema: table definitions, column types, constraints, and foreign keys. Optionally, the AI can also query individual records (read-only) when sample data would improve type decisions. The AI can inspect your actual database structure to generate entities that match, or validate entities it just created.
149
119
-**Built-in verification** through `ORMTemplate.validateSchema()` and `SqlCapture` lets the AI validate its own work. After generating entities, the AI can validate them against the database. After writing queries, it can capture and inspect the actual SQL. Both checks run in an isolated in-memory database through `@StormTest`, so verification happens before anything touches production. For dialect-specific code, `@StormTest` supports a static `dataSource()` factory method on the test class, allowing integration with Testcontainers to test against the actual target database.
150
120
151
121
---
@@ -180,13 +150,14 @@ The AI generates and updates code (entities, migrations, queries). Storm validat
180
150
181
151
In a schema-first workflow, the database is the source of truth. The schema already exists (or is managed by a DBA), and entities need to match it.
182
152
183
-
When the MCP server is configured, the AI has access to the live database through `list_tables` and `describe_table`. This gives it full visibility into table definitions, column types, constraints, and foreign key relationships.
153
+
When the MCP server is configured, the AI has access to the live database through `list_tables` and `describe_table`. This gives it full visibility into table definitions, column types, constraints, and foreign key relationships. When data access is enabled, the AI can also use `select_data` to sample individual records — useful when the schema alone is ambiguous about intent (e.g., a `VARCHAR` that holds enum values, or a `TEXT` column that stores JSON).
184
154
185
155
The AI workflow:
186
156
187
157
1.**Inspect the schema.** The AI calls `list_tables` to discover tables, then `describe_table` for each relevant table.
188
-
2.**Generate entities.** Based on the schema metadata and Storm's entity conventions (naming, `@PK`, `@FK`, `@UK`, nullability, `Ref<T>` for circular or self-references), the AI generates Kotlin data classes or Java records.
189
-
3.**Validate.** The AI writes a temporary test that validates the generated entities against the database using `ORMTemplate.validateSchema()`.
158
+
2.**Sample data (if available).** When `select_data` is enabled and the schema leaves a type decision ambiguous, the AI queries a few rows to inform the choice.
159
+
3.**Generate entities.** Based on the schema metadata (and optional sample data) and Storm's entity conventions (naming, `@PK`, `@FK`, `@UK`, nullability, `Ref<T>` for circular or self-references), the AI generates Kotlin data classes or Java records.
160
+
4.**Validate.** The AI writes a temporary test that validates the generated entities against the database using `ORMTemplate.validateSchema()`.
190
161
191
162
When the database schema evolves, the same flow applies: the AI inspects the changed tables, updates the affected entities, and re-validates.
0 commit comments