This is an automated email from the ASF dual-hosted git repository.
asf-gitbox-commits pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cayenne.git
The following commit(s) were added to refs/heads/master by this push:
new 56fe3bc4c CAY-2979 AI skill: "cayenne-full-db-sync"
56fe3bc4c is described below
commit 56fe3bc4c23f26fa1ffd8893a386cc7ab1f8a767
Author: Andrus Adamchik <[email protected]>
AuthorDate: Sat Jul 18 14:49:50 2026 -0400
CAY-2979 AI skill: "cayenne-full-db-sync"
---
RELEASE-NOTES.txt | 1 +
ai-plugin/README.md | 6 +-
ai-plugin/skills/cayenne-db-import/SKILL.md | 2 +-
ai-plugin/skills/cayenne-full-db-sync/SKILL.md | 135 +++++++++++++++++++++++++
4 files changed, 141 insertions(+), 3 deletions(-)
diff --git a/RELEASE-NOTES.txt b/RELEASE-NOTES.txt
index 72a68945d..1dcfd71c4 100644
--- a/RELEASE-NOTES.txt
+++ b/RELEASE-NOTES.txt
@@ -26,6 +26,7 @@ CAY-2972 Fewer parentheses in generated SQL
CAY-2974 CayenneSqlException with a reference to translated query
CAY-2975 Mnemonic table aliases in generated SQL
CAY-2978 AI skill: "cayenne-model-naming"
+CAY-2979 AI skill: "cayenne-full-db-sync"
Bug Fixes:
diff --git a/ai-plugin/README.md b/ai-plugin/README.md
index b257bddbc..abec76c73 100644
--- a/ai-plugin/README.md
+++ b/ai-plugin/README.md
@@ -26,13 +26,14 @@ This plugin teaches Claude how to:
- Reverse-engineer a database schema into a DataMap by driving CayenneModeler.
- Polish the reverse-engineered Object-layer names (entities, attributes,
relationships) into idiomatic Java, fixing the few cases the deterministic name
generator can't.
- Regenerate Java entity classes from a DataMap.
+- Run a full DB sync — import, name cleanup, and class regeneration — as a
single end-to-end workflow.
- Bootstrap `CayenneRuntime` in a Java application and write `ObjectSelect` /
`SQLSelect` queries.
The plugin assumes downstream **users of Cayenne** writing their own Java
apps. It does *not* cover contributor workflows for hacking on Cayenne itself.
## Install
-**Cayenne 5.0+ only.** The MCP server ships with Cayenne 5.0. Skills that
depend on it (`cayenne-cgen`, `cayenne-modeler`, `cayenne-db-import`) will not
work against earlier Cayenne versions. The XML-editing, runtime, and query
skills also target 5.0 idioms — for older Cayenne, this plugin is not the right
tool.
+**Cayenne 5.0+ only.** The MCP server ships with Cayenne 5.0. Skills that
depend on it (`cayenne-cgen`, `cayenne-modeler`, `cayenne-db-import`,
`cayenne-full-db-sync`) will not work against earlier Cayenne versions. The
XML-editing, runtime, and query skills also target 5.0 idioms — for older
Cayenne, this plugin is not the right tool.
The plugin is distributed from the Apache Cayenne GitHub repository:
**https://github.com/apache/cayenne**. Inside Claude Code:
@@ -59,9 +60,10 @@ ai-plugin/
├── README.md # this file
├── skills/ # auto-triggering workflows
│ ├── cayenne-modeling/ # edit *.map.xml and cayenne-*.xml
-│ ├── cayenne-db-import/ # import a DB schema (Modeler GUI)
+│ ├── cayenne-db-import/ # import a DB schema into the DataMap (model
only)
│ ├── cayenne-model-naming/ # polish Obj-layer names after import / on
request
│ ├── cayenne-cgen/ # regenerate Java classes via MCP
+│ ├── cayenne-full-db-sync/ # orchestrate import → name cleanup → cgen
│ ├── cayenne-modeler/ # open the GUI on a project
│ ├── cayenne-runtime/ # bootstrap CayenneRuntime in an app
│ └── cayenne-query/ # write ObjectSelect / SQLSelect queries
diff --git a/ai-plugin/skills/cayenne-db-import/SKILL.md
b/ai-plugin/skills/cayenne-db-import/SKILL.md
index 609c53be1..d5757a57c 100644
--- a/ai-plugin/skills/cayenne-db-import/SKILL.md
+++ b/ai-plugin/skills/cayenne-db-import/SKILL.md
@@ -1,6 +1,6 @@
---
name: cayenne-db-import
-description: "Use this skill whenever the user wants to import database schema
metadata into a Cayenne DataMap — full-schema sync from a live DB. Trigger on
phrases like 'reverse engineer the database', 'import the schema', 'generate a
DataMap from my DB', 'sync the model with the database', 'add the new tables
from the DB', 'import the customer table', 'pick up the latest schema changes',
'create entities from these tables', or any request that involves reading
database metadata to popu [...]
+description: "Use this skill when the user wants to import database schema
metadata into a Cayenne DataMap — the *model/mapping only*, not names or Java
classes. Trigger on phrases like 'reverse engineer the database', 'import the
schema', 'generate a DataMap from my DB', 'add the new tables from the DB into
the model', 'import the customer table', 'create entities from these tables',
or any request to read database metadata to populate or update a DataMap's XML.
This is for *full schema [...]
---
<!--
diff --git a/ai-plugin/skills/cayenne-full-db-sync/SKILL.md
b/ai-plugin/skills/cayenne-full-db-sync/SKILL.md
new file mode 100644
index 000000000..08ebf81ba
--- /dev/null
+++ b/ai-plugin/skills/cayenne-full-db-sync/SKILL.md
@@ -0,0 +1,135 @@
+---
+name: cayenne-full-db-sync
+description: "Use this skill when the user wants to bring their WHOLE Cayenne
project in line with the database in one shot — the mapping, the Object-layer
names, and the generated Java classes together. This is the end-to-end 'sync
with the DB' workflow, and it orchestrates three skills in order:
`cayenne-db-import` (import schema metadata into the DataMap) →
`cayenne-model-naming` (polish the just-imported names) → `cayenne-cgen`
(regenerate Java classes). Trigger on holistic phrases l [...]
+---
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ https://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+# cayenne-full-db-sync
+
+Bring an entire Cayenne project in line with the database in one pass. This
skill is a **thin
+orchestrator** — it runs three existing skills in sequence and does not
re-implement any of their
+logic:
+
+1. **`cayenne-db-import`** — import DB schema metadata into the DataMap (the
mapping XML).
+2. **`cayenne-model-naming`** — polish the Object-layer names of what the
import just added.
+3. **`cayenne-cgen`** — regenerate the Java entity classes so the code matches
the model.
+
+Each sub-skill still runs within its own scope and carries its own required
reading, MCP tool usage,
+failure handling, and anti-patterns. Your job here is to drive them in order,
pass the shared
+project/DataMap identity through, and short-circuit correctly when a stage has
nothing to do.
+
+## When to use this vs. a single skill
+
+- **Whole project should reflect the DB** (mapping + names + Java) → this
skill.
+- **Model/mapping only**, no name cleanup or class generation →
`cayenne-db-import`.
+- **Java classes only**, model already correct → `cayenne-cgen`.
+- **Names only**, no import or regeneration → `cayenne-model-naming`.
+
+If the request is ambiguous ("update from the DB"), default to this full sync
— it is the common
+intent — but say what you're about to do (import → clean names → regenerate)
before you start.
+
+## Required reading
+
+This skill delegates, so read each sub-skill and let it pull its own
references:
+
+- `${CLAUDE_PLUGIN_ROOT}/skills/cayenne-db-import/SKILL.md`
+- `${CLAUDE_PLUGIN_ROOT}/skills/cayenne-model-naming/SKILL.md`
+- `${CLAUDE_PLUGIN_ROOT}/skills/cayenne-cgen/SKILL.md`
+- `${CLAUDE_PLUGIN_ROOT}/references/project-layout.md` — to resolve the
project descriptor and DataMap once, up front.
+
+## Step 0 — Resolve the shared inputs once
+
+All three stages operate on the same project. Resolve these before starting so
you can pass them
+through:
+
+- **`projectPath`** — absolute path to the top-level project descriptor
(`cayenne-*.xml`), via
+ `project-layout.md`. Not a DataMap file.
+- **`dataMap`** — the DataMap name from `<map name="...">` in the descriptor.
If the project has
+ multiple DataMaps and the user wants "everything", run the whole pipeline
once per DataMap. If
+ ambiguous, ask which DataMap; cache the answer.
+
+Tell the user the plan in one line: "I'll import from the DB, clean up the new
names, then regenerate
+the classes."
+
+## Step 1 — Import (`cayenne-db-import`)
+
+Follow the `cayenne-db-import` skill to run `dbimport_run` for the resolved
project/DataMap. Because
+you are orchestrating, **you** drive the follow-up here — do not act on that
skill's own Step 5
+hand-off prompts (it would suggest naming/cgen again); this skill sequences
them instead.
+
+Branch on the result status:
+
+- **`imported` with a non-empty `summary`** (entities/relationships
added/modified) → the model
+ changed. Proceed to Step 2.
+- **`up_to_date`** (or `imported` with an all-zero summary) → the mapping
already matches the DB.
+ **Skip Step 2** (nothing new to name). Go straight to Step 3 to guarantee
the Java classes are in
+ sync — `cgen_run` is idempotent and simply reports everything skipped if the
code is already
+ current. Tell the user the model was already up to date.
+- **`validation_failed`** → follow `cayenne-db-import`'s remediation table for
the `error.code`. The
+ common first-run case is `dbconnector_not_configured`, which routes through
the Modeler GUI to save
+ the connection; once resolved, re-run the import and continue the pipeline.
If it can't be resolved,
+ stop and surface the problem — do **not** run naming or cgen on a failed
import.
+- **`error`** (partial/mid-run failure) → surface `error.message` and the
partial summary, then stop.
+ Don't proceed to naming or cgen.
+
+## Step 2 — Clean up names (`cayenne-model-naming`)
+
+Only when Step 1 imported real changes. Follow the `cayenne-model-naming`
skill in its **changed-only**
+mode — it scopes itself to the import's additions via `git diff`, so you don't
tell it which entities
+changed. Within this pipeline it runs **unattended**: apply the changed-scope
renames and **report**
+what changed; do not pause for per-rename confirmation. (Naming must run
*before* cgen so the classes
+are generated with the final names.)
+
+Two carry-overs from that skill still hold: it only touches what the
deterministic generator can't get
+right (run-together names, `team1`-style collisions, a table prefix leaking
into relationships), and
+every rename updates its cross-references per `model-naming-rename-safety.md`.
+
+## Step 3 — Regenerate classes (`cayenne-cgen`)
+
+Follow the `cayenne-cgen` skill to run `cgen_run` for the same
project/DataMap. This materializes the
+Java entity classes from the now-final model. Report the `summary` counts and
the destination as that
+skill describes.
+
+## Step 4 — Summarize the whole run
+
+Give the user a single consolidated report of the three stages:
+
+- **Import** — entities/relationships added/removed/modified (from the
`dbimport_run` summary).
+- **Names** — the renames applied (old → new), or "none needed".
+- **Classes** — files written / skipped, and the destination directory.
+
+Then the usual follow-ups: remind them not to edit the `_<Entity>.java`
superclasses (regenerated),
+and to save the project in the Modeler if it's open.
+
+## Anti-patterns
+
+- **Don't use this for a single stage.** Model-only import →
`cayenne-db-import`; classes-only →
+ `cayenne-cgen`; names-only → `cayenne-model-naming`. This skill is for the
whole pipeline.
+- **Don't re-implement the sub-steps.** Delegate to each skill so its MCP tool
usage, failure modes,
+ and anti-patterns all apply. This file only sequences and short-circuits.
+- **Don't run naming or cgen after a failed or empty import.** A
`validation_failed`/`error` stops the
+ pipeline; `up_to_date` skips naming (but cgen may still run as an idempotent
guarantee).
+- **Don't reorder the stages.** Names must be finalized before cgen, or
classes are generated with the
+ names you're about to change.
+- **Don't rewrite the whole model during a sync.** Naming stays in
changed-only scope (import
+ additions), never an entire-model pass, unless the user explicitly asks for
one.
+- **Don't suggest `mvn cayenne:cdbimport` / `cayenne:cgen` or the Gradle
tasks.** The sub-skills use
+ the MCP tools exclusively; if the server isn't connected, they point at
`cayenne-mcp-server/README.md`
+ and stop.
