${run.doctype} DBMT

DBMT - Manual de usuario.

Inicio -- english version of this manual

1.- Configurando el fichero XML.

Una migración se describe en un fichero XML que contiene todos los pasos a seguir. Aunque este fichero es bastante sencillo, puede ser molesto de escribir, especialmente si la migración tiene muchos pasos, así que ponte en contacto con nosotros si quieres escribir una aplicación con interfaz gráfica para realizar esta tarea :-).
En todo caso, un fichero XML tiene que ser algo parecido a esto:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE migration SYSTEM "http://dbmt.sourceforge.net/dtds/migration_1_0.dtd">
<migration>

  <databank>
    <source
      url="jdbc:mysql://127.0.0.1/DATABASE_SRC?user=USERNAME&password=PASSWORD"
      driver="org.gjt.mm.mysql.Driver"
    />
    <target
      url="jdbc:postgresql://destiny/DATABASE_TGT?user=USERNAME&password=PASSWORD"
      driver="org.postgresql.Driver"
    />
  </databank>

  <functions>
      <function name="countrows"
                sql="select count(*) from source_table where id > 0" />
      <function name="count_greater_rows"
                sql="select count(*) from source_table where id > ${current.id}" />
  </functions>

  <steps>
    <step name="test_migration"
          source_table="source_table"
          target_table="target_table"
          clear_target="true"
          output="file"
          sliced="true"
          slice_size="1"
          slice_key="Id"           
     >
      <field from="id" to="item" type="int" value=""/>
      <field from="datum" to="post-date" type="date" value=""/>
      <field from="now" to="then" type="timestamp" value=""/>
      <field from="somethingbig" to="athing" type="blob" value=""/>
      <field from="text" to="description" type="string" value=""/>
      <field from="" to="user" type="new-string" value="anonymous"/>
      <field from="" to="today" type="new-date" value="2002-11-25"/>
      <field from="" to="intvalue" type="new-int" value="0"/>
      <field from="" to="count" type="new-int" value="${countrows}"/>
    </step>
  </steps>

</migration>

Puedes descargar una versión documetnada de este ejemplo desde aquí

1.1.- La etiqueta `databank` .

En este etiqueta definiremos las bases de datos usadas como fuenta y destino para esta migración, indicando la UURL de conexión y el nombre del driver JDBC a utilizar. Ten en cuenta que los drivers JDBC no estan incluidos en la distribución de DBMT, de modo que tendrás que añadirlos al classpath tu mismo.
Por supuesto este tag es obligatorio.

  <databank>
    <source
      url="jdbc:mysql://127.0.0.1/DATABASE_SRC?user=USERNAME&password=PASSWORD"
      driver="org.gjt.mm.mysql.Driver"
    />
    <target
      url="jdbc:postgresql://destiny/DATABASE_TGT?user=USERNAME&password=PASSWORD"
      driver="org.postgresql.Driver"
    />
  </databank>

Como veremos, DBMT puede escribir todas las snetencias de inserción en un fichero de texto en lugar de ejecutarlas directamente en la base de datos de destino, lo cual es muy útil si las dos máquinas no estan accesibles en el mismo momento o lugar. También en este caso tendremos que indicar a DBMT una conexión fuenta y otra destino, aunque ya que no se ejecutarán sentencias SQL de inserción, simplemente puedes repetir la información de la base de datos origen.

1.2.- La etiqueta `functions`.

La siguiente parte de una migración son las funciones. Una función es una sentencia SQL cuyo resultado puede ser usado para calcular nuevos valores en la tabla destino.
Este tag es opcional, ya que muchas de las veces no se necesitan funciones.

  <functions>
      <function name="countrows"
                sql="select count(*) from source_table where id > 0" />
  </functions>

En ocasiones necesitaremos ejecutar estas funciones en base a los valores del registro actual en la migración. Esto se puede hacer usando ${current.NOMBRE_DEL_CAMPO} en lugar de indicar solo el nombre de un campo.

      <function name="count_greater_rows"
                sql="select count(*) from source_table where id > ${current.id}" />

En este ejemplo, la clausula de selección variara para cada registro migrado, tomando el valor del campo id fpara cada fila.

1.3.- La etiqueta `steps`.

Los steps o pasos son la parte más importante de una migración, ya que en cada paso se define como han de cmabiar los campos de la tabla para ajustarse al nuevo esquema.
podemos escribir tantas etiquetas step como tablas queramos migrar.

  <steps>
    <step name="test_migration"
          source_table="source_table"
          target_table="target_table"
          clear_target="true"
          output="file"
          sliced="true"
          slice_size="1"
          slice_key="Id"                     
     >
       FIELDS
    </step>
  </steps>

Primero indicamos alguna información de configuración: name (nombre), source_table (tabla origen), target_table (tabla destino), clear_target (limpiar destino) y output (salida). Los tres priemros estan claros, el cuarto indica si se debe eliminar la información existente en la tabla destino al comenzar la migración, y el quinto indica que tipo de salida producir. Este atributo output puede tomar tres valores:

db file both

Con db los datos se insertarán directamente en la base de datos destino. Con file se creará una fichero de texto con el nombre NOMBRE_DEL_PASO.sql conteniendo todas las sentencias de inserción usando el nuevo esquema. Obviamente both (ambos) producirá mabas salidas, a fichero y a la base de datos destino.

Si nuestra tabla es lo suficientemente grande para querer envitar una select completa de los datos y si nuestro driver soporta JDBC 2.0, podemos dividir los datos de la tabla en porciones para realizar la migración en porciones más pequeñas ajustando el valor del atributo sliced a true. entonces podremos usar slice_size y slice_id para configurar estas partes.

Después tendremos que escribir como se procesarán los campos. Podemos pasar un campo de un determinado tipo del viejo esquema al nuevo, dejando el atributo value (valor) vacio e introduciendo el tipo adecuado en el atributo type. Hasta ahora solo se soportan string, date, int, timestamp and blob, principalmente porque hasta ahora no hemos necesitado más, pero sdebería ser muy sencillo añadir más.

      <field from="id" to="item" type="int" value=""/>
      <field from="datum" to="post-date" type="date" value=""/>
      <field from="text" to="description" type="string" value=""/>
      <field from="now" to="then" type="timestamp" value=""/>
      <field from="somethingbig" to="athing" type="blob" value=""/>

Si el nuevo esquema tiene algunos campos nuevos podemos asignarles un valor fijo dejando el atributo from (de) vacio y añadiendo el texto new- (nuevo-) al comienzo del tipo, indicando el valor en el atributo value (valor).

      <field from="" to="user" type="new-string" value="anonymous"/>
      <field from="" to="today" type="new-date" value="2002-11-25"/>
      <field from="" to="intvalue" type="new-int" value="0"/>
      <field from="" to="then" type="new-timestamp" value=""/>

Para nuevos valores también podems usar las funciones ya definidas, indicando el nombre de la función en el atributo value como sigue::

      <field from="" to="count" type="new-int" value="${NOMBRE_FUNCION}"/>

2.- Ejecución.

Sencillom ejecuta la clase org.javahispano.dbmt.MigrationRunner indicando tu fichero XML como parámtro.
Como con todo programa escrito en java, necesitarás añadir al classpath todas las clases necesarias, por ejemplo el driver JDBC de tu SGBD y las del parser XML (crimson y JAXP estan incluidos en el directorio "lib").

        *nix:
          java -cp dbmt.jar:MORE_JARS org.javahispano.dbmt.MigrationRunner migration.xml
        Windows:
          java -cp dbmt.jar;MORE_JARS org.javahispano.dbmt.MigrationRunner migration.xml

3.- Licencia.

DBMT se distribuye bajo la Licencia Pública GNU (GPL)