[deepamehta-devel] some newbie dev migrations questions

[Jörg Richter]

On Feb 9, 2014, at 0:59, carolina wrote:

> a month ago or so, I started the first try to do a DM plugin, a calendar
> plugin. Now I want to continue with it, but of course I get stuck at
> what probably are silly things, so I proceed to ask till I get a bit
> familiar with DM.

No problem!
You're welcome :-)

> The question is related to migrations, since I'm not sure I understand
> how migrations work, is where I think I have the problem.
> 
> I had a first declarative migration, migration1.json, where I defined an
> event with a start_date and end_date.
> 
> Today I edited that migration1.json and added a title and text to the
> event, saved the file and run

You can't add new child types to an existing type with a declarative migration (JSON). You would need an imperative migration for that (Java, DM Core API). But see note below.

> mvn clean package
> 
> it said build success but showed a failed in the server terminal, so
> after re-reading the documentation, I read that a migration
> 
> "is executed exactly once in the lifetime of a particular DeepaMehta
> installation"
> 
> so I guess the migration1.json should have been renamed into
> migration2.json and then the plugin.properties file changed so that
> it looked like
> 
> requiredPluginMigrationNr=2
> importModels=de.deepamehta.webclient
> 
> 
> So I've tried to "cheat", I've left migration1.json as it originally was
> (or I think so), then I've created a migration2.json with the new
> changes ,  but no luck, I get an error that I attach as a a file since
> its too long to paste.
> 
> At some point says
> 
> Caused by: java.lang.RuntimeException: Running migration 2 of plugin
> "CGC Calendar" failed

Always when you see an exception read on in the log and follow the chain of underlying exceptions ("Caused by: ... Caused by: ... Caused by: ..."). The last exception reveals the original problem cause. In your case:

	Caused by: java.lang.RuntimeException: Running migration 2 of plugin "CGC Calendar" failed
	...
	Caused by: java.lang.RuntimeException: Reading migration file "/migrations/migration2.json" failed
	...
	Caused by: java.lang.RuntimeException: Creating topic type "cgc.calendar.event" failed
	...
	Caused by: java.lang.RuntimeException: URI "cgc.calendar.event" is not unique

So, the last exception is telling: it means you tried to create a type with an URI already in use. Actually you tried to create the Event type when it already exists in the DB.

> which makes me think that has to do with this migration, maybe the error
> is not in the naming but somewhere else, has to do with syntax or that
> I've missed sth,
> 
> Here is the repo where I've got the code of the migration after adding
> the title and text to the original one and before renaming the migration
> to migration2.json I've not pushed the changes since i'm not sure it has
> to do with it
> 
> https://github.com/carolinagc/dm-cgc-calendar/commit/8cb4d62ae4ea2499336b4570c7363d10437e3cb7
> 
> 
> even if the problem is somewhere else I have not clear how migrations
> versions work (I guess I've got bad RoR migrations habits)

The DM runtime takes care of running migrations in the proper order (1, 2, 3, ...) and that each migration is run exactly once. This is because a migration expects a well-defined DB state and leaves a well-defined DB state. If a migration which e.g. creates a type would run twice the 2nd run would fail as the type already exists. Declarative DM migrations (JSON) are not idempotent. 

> btw is there a way to create again the database from scratch so to be
> able to run the first migration?

Indeed, resetting your DB is the most easy solution in your case:
	1) Stop DM
	2) Delete the deepamehta-db folder (in the DM home directory)
	3) Start DM
This starts DM from scratch and runs your migrations starting from no. 1

Note: resetting the DB is a pragmatic way while development.
In a production environment this is not an option of course. To add new child types to an existing type in a production environment you MUST use an imperative migration (Java code, not JSON).

If you need more help, don't hesitate :-)

Cheers,
Jörg