[deepamehta-devel] some newbie dev migrations questions

[Jörg Richter]

On Feb 11, 2014, at 0:36, carolina wrote:

>> The general migration concept is: A migration represents a certain 
>> version of your data model that is compatible with a certain
>> version of your plugin logic. Currently your plugin contains no
>> logic (but just a data model), so this might be why you are
>> confused. For differentiating declarative and imperative migrations
>> see also the note below.
>> 
>> Read about DM migrations also here: 
>> https://trac.deepamehta.de/wiki/PluginDevelopmentGuide#Migrations 
>> Don't hesitate to tell me where this explanation could be
>> improved.
> 
> I think that my confusion comes from using the terminology "migration"
> for declarative migrations when you can just do one operation once,
> somehow I guess I would see declarative migrations as db schemas that
> are loaded once, sorry I'm doing the equivalences with RoR, which has
> those 2 concepts (though in RoR db-schema gets generated/updated while
> doing migrations but then you can load it on its own without running
> the migrations)

Sorry, here you lost me.

In general the migration story is about the challenge of keeping your DB model (= schema) in-sync with your application logic. In particular when the user upgrades your application.

A DM migration (regardless of declarative or imperative) migrates your DB from one model version to the next. That is quite analogue to a RoR migration. You can see a DM type definition as part of the DB schema. Roughly 1 Parent Type = 1 table, 1 Child Type = 1 table column.

When a DM migration is run it actually CREATES resp. MODIFIES the DB schema, namely by creating types and/or associating child types. Each particular DM migration runs exactly once (per DM instance) as the schema manipulations must be performed only once. You want not create a particular table twice (it would fail).

About wording: I would not say schemas or migrations are "loaded". Schemas persist in the DB. And when a migration is "run" it manipulates the schema.

In DM migrations are not run manually by the developer/administrator. Instead your application (= DM plugin) knows on which DB schema it relies (as reflected by the "requiredPluginMigrationNr" plugin property) and then the DM platform takes care of running the required migrations. (That happens each time the platform is launched or when your plugin is installed).

(Think of "requiredPluginMigrationNr" as "schemaVersion/modelVersion/requiredModel" or the like. Probably we should rename this plugin property.)

>> This would be the most flexible solution as you could run both DM 
>> instances at the same time.
> 
> I've decided for this option, so now I have 2 DM running :D

IMPORTANT TOO: in your production instance you must not only install stable versions of your plugin (as told before) but you must also install only *stable* DM versions. While for particular DM releases installing SNAPSHOTS might be OK (e.g. upgrading from 4.2-SNAPSHOT to 4.2 is not a problem), in general there is no guarantee for that to work. What on the other hand IS guaranteed to work: upgrading from stable DM to stable DM. Furthermore you're free to skip releases (e.g. you can upgrade from 4.1 to 4.1.3 in one step).

> Which of the plugins would be a good start to read code?

All of them :-)
Indeed it might be insightful to skim the source code of several plugins and recognize the common patterns. Also be aware every plugin might have a server-side Java portion (look in /src/main/java) and/or a client-side JavaScript portion (/src/main/resources/web/script). Good starting points are the respective plugin "main" files:
	/src/main/java/.../<plugin>/...Plugin.java     (always extends PluginActivator)
	/src/main/resources/web/script/plugin.js
Also be aware that some plugins have no Java/JavaScript parts at all, e.g. dm4-notes and dm4-contacts. These define just a data model (= DB schema) and provide web resources (like images).

Unfortunately the Plugin Development Guide is still quite incomplete. The server-side parts are covering just the basics, and the client-side parts are not yet existing at all. However, you'll already find useful information in it:
https://trac.deepamehta.de/wiki/PluginDevelopmentGuide
See also the architecture overview:
https://trac.deepamehta.de/wiki/ArchitectureOverview

I'm eager to answer all your questions :-)
(you might consider starting separate threads)

Cheers,
Jörg