[jbpm-commits] JBoss JBPM SVN: r5773 - jbpm4/trunk/modules/userguide/src/main/docbook/en/modules.
do-not-reply at jboss.org
do-not-reply at jboss.org
Fri Oct 23 04:24:09 EDT 2009
Author: alex.guizar at jboss.com
Date: 2009-10-23 04:24:09 -0400 (Fri, 23 Oct 2009)
New Revision: 5773
Modified:
jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch02-Installation.xml
Log:
[JBPM-2509] insert upgrade database section into user guide
Modified: jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch02-Installation.xml
===================================================================
--- jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch02-Installation.xml 2009-10-23 01:59:01 UTC (rev 5772)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch02-Installation.xml 2009-10-23 08:24:09 UTC (rev 5773)
@@ -127,7 +127,7 @@
<para>To customize the values for these properties, just use <literal>-D</literal> like this
</para>
<programlisting>ant -Ddatabase=postgresql demo.setup.jboss</programlisting>
- <para>Alternativelym you can specify the customized values in
+ <para>Alternatively you can specify the customized values in
<literal>${user.home}/.jbpm4/build.properties</literal>
</para>
</section>
@@ -189,53 +189,59 @@
<section id="database">
<title>Database</title>
- <para>The install script also contains scripts for
- DB operations like creating and dropping the schema.
+ <para>The install script is also capable of performing database operations
+ such as creating the schema, if you are installing jBPM for the first time,
+ or upgrading the database used with a previous version to the current schema.
+ Dropping the schema is an option as well.
</para>
- <para>To create the schema in your database:</para>
- <itemizedlist>
- <listitem>First, update the properties file of your database in <literal>${jbpm.home}/install/jdbc</literal></listitem>
- <listitem>Then run target <literal>ant create.jbpm.schema</literal> in the <literal>${jbpm.home}/install</literal> directory</listitem>
- </itemizedlist>
- </section>
+ <para>The prerrequisite for any database operation is to specify your
+ database connection parameters in <literal>${jbpm.home}/install/jdbc</literal>.
+ </para>
- <!--
- <section id="databasemigration">
- <title>Database migration</title>
-
- <para>jBPM is able to generate SQL DDL scripts to upgrade the database schema from any past version
- starting from 4.0. To enact this capability, first check out the project from our SVN repository as
- described in the Wiki page <ulink url="http://www.jboss.org/community/wiki/jbpm4buildingfromsource">
- Building from Source</ulink>. Make sure you specify the appropriate database properties for your
- target database.</para>
- <para>Afterwards, change to the <literal>modules/db</literal> directory and run:</para>
- <synopsis>mvn -Djbpm.previous.version=<version.number>
- -Ddatabase={hsqldb|mysql|postgresql|oracle} package</synopsis>
- <para>The valid previous versions are those available from the JBoss <ulink
- url="http://repository.jboss.org/maven2/org/jbpm/jbpm4/jbpm-db/">Maven repo</ulink> starting
- from 4.0.</para>
- <para>Let us walk over an example. Assume you want to generate an update script from version 4.0
- for PostgreSQL. You have checked out <ulink url="http://anonsvn.jboss.org/repos/jbpm/jbpm4/trunk/">trunk</ulink>.
- You have a local PostgreSQL server listening on port 5432 (default). You have created a database and login
- both called <literal>jbpm4</literal>. File <literal><user.home>/.jbpm4/jdbc/postgresql.properties</literal>
- contains your JDBC connection properties.</para>
- <programlisting>hibernate.connection.driver_class=org.postgresql.Driver
-hibernate.connection.url=jdbc:postgresql://localhost:5432/jbpm4
-hibernate.connection.username=jbpm4
-hibernate.connection.password=</programlisting>
- <para>Given the environment described above, you change to the <literal>modules/db</literal> directory
- and run maven there.</para>
- <synopsis>mvn -Djbpm.previous.version=4.0 -Ddatabase=postgresql package</synopsis>
- <para>This command creates directory <literal>target/4.0</literal> and writes the following artifacts
- there:</para>
- <itemizedlist>
- <listitem>Scripts to create and drop the jBPM 4.0 database schema, retrieved from the Maven repo.</listitem>
- <listitem>PostgreSQL script to upgrade from the jBPM 4.0 schema to the version in your working copy.</listitem>
- <listitem>Diff file between the previous and the current schema creation scripts. Only appears if your OS
- belongs to the Unix family (including Linux and Mac OS X) and provides the diff command.</listitem>
- </itemizedlist>
+ <section id="createdropdb">
+ <title>Creating or dropping the database schema</title>
+ <para>To create the schema, run target <literal>create.jbpm.schema</literal>
+ in the <literal>${jbpm.home}/install</literal> directory. Apart from
+ creating tables and constraints, the mentioned target will initialize
+ table <literal>JBPM4_PROPERTY</literal> with the current engine version
+ (key <literal>db.version</literal>) and the ID generator base value
+ (key <literal>next.dbid</literal>.</para>
+ <para>To drop the schema, simply run target <literal>drop.jbpm.schema</literal>.
+ Be aware that this operation will destroy any data present in the jBPM
+ tables.</para>
+ </section>
+
+ <section id="upgradedb">
+ <title>Upgrading an existing database</title>
+ <para>To upgrade, run target <literal>upgrade.jbpm.schema</literal>
+ in the <literal>${jbpm.home}/install</literal> directory.</para>
+ <para>Upgrading is a two-fold operation. The foremost step is to add
+ any extra tables, columns or constraints that were introduced in newer
+ versions. Afterwards, seed data is inserted.</para>
+ <para>Between 4.0 and 4.1, table <literal>JBPM4_VARIABLE</literal> got
+ a new column <literal>CLASSNAME_</literal> used to support setting
+ process variables to values of custom types mapped with Hibernate.
+ This column is nullable and left uninitialized since the feature was
+ not operational in 4.0.</para>
+ <para>From 4.1 to 4.2 the upgrade procedure got more interesting.</para>
+ <itemizedlist>
+ <listitem>A new table <literal>JBPM4_PROPERTY</literal>
+ was introduced for storing engine-wide values.</listitem>
+ <listitem>The jBPM version is saved in table <literal>JBPM4_PROPERTY</literal>
+ under key <literal>db.version</literal> to allow for precise
+ identification in future releases.</listitem>
+ <listitem>The ID generation strategy is consistent across databases.
+ The next available ID is calculated by querying all tables having
+ an identifier column, and stored under key <literal>next.dbid</literal>
+ in the <literal>JBPM4_PROPERTY</literal> table.</listitem>
+ <listitem>The process language is set to <literal>jpdl-4.0</literal>
+ for all existing process definitions under key <literal>langid</literal>
+ in table <literal>JBPM4_DEPLOYPROP</literal>. The jPDL parser employs the
+ <literal>langid</literal> property to read process documents in a
+ backwards-compatible manner.</listitem>
+ </itemizedlist>
+ </section>
</section>
- -->
<section id="graphicalprocessdesigner">
<title>Graphical Process Designer (GPD)</title>
More information about the jbpm-commits
mailing list