Victor M. Herrera Silva - 2012-07-05
<title>README</title> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <style type="text/css"> .credits{ font-size:14px; color:#2BB53D; display:inline-block; } .mainTitle{ font-size:25px; font-weight:bold; color:#5E615E; display:inline-block; } .title{ font-size:17px; font-weight:bold; color:#A2A5A3; } .subtitle{ font-size:15px; font-weight:bold; color:#172C77; } .parrafo{ font-size:14px; } .leyenda{ font-size:13px; font-style:italic; padding-left:20px; } </style>
DBSubervsion
by Victor M. Herrera Silva

Descripción

Esta herramienta permite manejar los scripts de base de datos asignando una clave que llamaremos como "versionId". Con esta clave, la herramienta podrá identificar los scripts que han sido ejecutados en la base de datos configurada e identificar aquellos que están pendientes por ejecutar. Consiste en generar archivos .sql con el formato necesario para que la herramienta pueda ejecutar los scripts de manera secuencial asi como dar la opcion de generar documentación sobre los cambios realizados. Esta herramienta puede utilizarse con otras herramientas colaborativas como el svn, ya que cada desarrollador puede subir sus scripts y al actualizar verá aquellos que ya fueron ejecutados por la herramienta y cuales quedan pendientes por ejecutar, esto permitir´ que siempre se esté manejando los scripts más recientes.


Índice

Características
  • Permite generar documentación sobre el contenido de cada uno de los scripts
  • El template de la generación del documento puede ser modificado.
  • Rápida ejecución de scripts sin preocuparse por la secuencia ya que esta es de acuerdo al orden en es generado cada script.
  • Permite ejecutar el rollback de cada script o archivo .sql
  • Permite regresar o actualizar la base de datos ejecutando los scripts de una versión de origen a una de destino

Requerimientos

1.- Tener instalado el Java Development Kit(JDK) version 1.6 o la más reciente.Descargar
2.- Configurar la variable de entorno de java.Configurar variable
3.- Tener habilitada la conexión a la base de datos a conectarse
4.- Modificar el archivo de Migrate.properties con los datos correctos para la conexión


Configurar variable de entorno
  • 1.- Instalar JDK 1.6 o más reciente
  • 2.- Ir a la carpeta de instalación de Java, y entrar a la carpeta bin para copiar la ruta o directorio ${JavaPath}/bin
  • 3.- Ir a las variables de entorno del sistema operativo correspondiente, en este caso, Mi PC >Propiedades >Configuracion Avanzada >Variables de Entorno
  • 4.- Buscar la variable de entorno llamada "path" dentro de las variables del sistema y modificar su valor para agregar ";"+el path que copiamos en el paso anterior.
  • 5.- Una vez que modificamos el path, guardamos los cambios y cerramos la ventana
  • 6.- Ir a línea de comandos y ejecutar el comando de "java"
  • 7.- Si todo salió bien, debe de aparecer las opciones de java, de lo contrario marcar´ comando inv´lido y deber´ de repetir los 7 pasos de nuevo.

Modo de Uso

1.- Modificar el archivo de Migrate.properties con los datos correctos para la conexión. Note que se muestran las siguientes propiedades:

db.driverClassName: Indica la clase que contiene el driver de jdbc para conexión a base datos de Java, puede remover los "##" de cada driver dependiendo del DBMS que esté implementando.
db.url: Representa la liga para establecer la conexión de base de datos y depende de cada proveedor del driver.Descomente aquellos que sean necesarios para su conexion, simplemente cambie el nombre de la db y puertos necesarios.
db.user: Usuario quien se conectará a la base de datos. Este usuario una vez que se haya instalado la aplicación si tiene asignado un esquema por default, será este esquema que contenga la tabla de instalación de la herramienta.
db.password: Password requerido para conectarse con el usuario indicado en el atributo anterior según la url proporcionada.
db.database: Base de datos a la cual se está conectando el usuario.Este dato es de carácter informativo.
db.port: Puerto utilizado para conectarse a la base de datos.
db.dialect: Indica el dialecto a utilizar para los scripts de SQL, ya que en oracle se requiere una secuencia a diferencia de otros DBMS.Puede ser [oracle|mysql|otro]

2.- Entrar a línea de comandos y posicionarse en la misma ruta donde se encuentra el archivo dbSubversion.jar
3.- Ejecutar en línea de comandos el comando para mostrar la ayuda de la herramienta

java -jar dbSubversion.jar help

4.- Si es la primera vez que se utiliza la herramienta, ejecutaremos el comando de install, de lo contrario omitimos este paso.

java -jar dbSubversion.jar install

Nota:Es importante especificar que si el usuario que se logea a la base de datos tiene un esquema default con cual se logea, la tabla "changelog" será creada en este esquema default,por lo tanto si se cambia de usuario que se conecta a la base de datos y NO tiene el MISMO esquema default, la herramienta detectará como si no estuviera instalada y el versionamiento de los scripts no se recuperarán, para ello se tendrá que asignar el mismo esquema default o conectarse con el usuario que instaló por primera vez la herramienta.

5.- Una vez instalada la herramienta, podremos ejecutar el siguiente comando para identificar si existen scripts pendientes por ejecutar o si ya fueron ejecutados.

java -jar dbSubversion.jar status

A continuación nos mostrará un listado con la siguiente información:

Version: Indica la clave o identificador de cada script que se utilizará para la mayoría de comandos de la herramienta.(propiedad "versionId")
Script: Nombre del script
Fecha de Registro: Fecha en la cual fue ejecutado el script en la base de datos e insertado en la tabla de changelog

6.- Una vez instalado usted puede hacer uso de los comandos:[help|install|status|up|down|version|getDoc|getScript|pending|pendingByVersion]

Comandos

help

Muestra los comandos disponibles de la herramienta con una breve descripción de cada comando.
Parámetros:
Ninguno
Ejemplo:

java -jar dbSubversion.jar help

install

Crea una tabla "changelog" en el esquema default en el que se logea el usuario en la cual se estarán registrando los scripts que se ejecutan por medio de la herramienta DBSubversion.
Parámetros:
Ninguno
Ejemplo:

java -jar dbSubversion.jar install

status

Muestra la lista de los scripts que fueron ejecutados y que se encuentran registrados en la tabla de changelog, aquellos que no esten en la tabla y que estén en la carpeta de "scripts" son marcados como pendientes o "pending..."
Parámetros:
Ninguno
Ejemplo:

java -jar dbSubversion.jar status

up

Ejecuta 1 o más scripts pendientes de ejecutar DESDE el último script ejecutado, es decir, el último script que tiene fecha de registro(de arriba hacia abajo), TODOS los scripts marcados como "pending..." que se ubican por debajo de este último script serán ejecutados a menos que se le envíe el parámetro indicando la cantidad de scripts a ejecutar.
Parámetros:
número de scripts a ejecutar
Ejemplo: Ejecuta todos los scripts pendientes del último ejecutado.

java -jar dbSubversion.jar up

Ejemplo: Ejecuta los primeros 3 scripts pendientes del último ejecutado.

java -jar dbSubversion.jar up 3

down

Ejecuta 1 o más ROLLBACK's de scripts ejecutados DESDE el último script ejecutado hacía atrás a menos que se le envíe el parámetro indicando la cantidad de scripts a ejecutar su ROLLBACK.
Parámetros:
número de scripts a ejecutar
Ejemplo: Ejecuta el ROLLBACK del último script ejecutado.

java -jar dbSubversion.jar down

Ejemplo: Ejecuta los primeros 3 ROLLBACK's de los scripts a partir último ejecutado(incluyéndolo) hacia atrás.

java -jar dbSubversion.jar down 3

version

Ejecuta 1 o más scripts de una version de origen a una de destino, si la version de origen es menor a la de destino, se ejecutarán los @TODO de cada script, de lo contrario se ejecutarán los @UNDO o ROLLBACK's de los scripts hasta llegar al script de destino
Parámetros:
versionId de origen
versionId de destino
Ejemplo: Ejecuta los scripts de la version 20120115182108 a 20120228152105

java -jar dbSubversion.jar version 20120115182108 20120228152105

Ejemplo: Ejecuta los ROLLBACK's de la version 20120228152105 hasta la version 20120115182108

java -jar dbSubversion.jar version 20120228152105 20120115182108

getDoc

Genera documentación de 1 o más scripts de una version de origen a una de destino, si la version de origen es menor a la de destino, se ejecutarán los @TODO de cada script, de lo contrario se documentarán los @UNDO o ROLLBACK's de los scripts hasta llegar al script de destino. La documentación se genera en la carpeta de dbSubversion/templates/docs y son archivos .pdf
Parámetros:
versionId de origen
versionId de destino
Ejemplo: Se genera documentación de los scripts de la version 20120115182108 a 20120228152105

java -jar dbSubversion.jar getDoc 20120115182108 20120228152105

Ejemplo: Genera la documentación de los ROLLBACK's de la version 20120228152105 hasta la version 20120115182108

java -jar dbSubversion.jar getDoc 20120228152105 20120115182108

getScript

Genera un script maestro que contiene todos los scripts de una version de origen a una de destino, si la version de origen es menor a la de destino, se ejecutarán los @TODO de cada script, de lo contrario se crea el script maestro con todos los @UNDO o ROLLBACK's de los scripts hasta llegar al script de destino. El archivo o script maestro con extensión .sql se genera en la carpeta de dbSubversion/templates/docs.
Parámetros:
versionId de origen
versionId de destino
incluirScriptsCreacionChangelog sirve para indicar si en el script maestro debe de tener los inserts del changelog. Valores [0|1], donde 1 es para incluir los scripts.
Ejemplo: Se crea el script maestro de todos los scripts de la version 20120115182108 a 20120228152105

java -jar dbSubversion.jar getScript 20120115182108 20120228152105

Ejemplo: Se crea el script maestro de todos los ROLLBACK's de la version 20120228152105 hasta la version 20120115182108

java -jar dbSubversion.jar getScript 20120228152105 20120115182108

pending

Ejecuta todos los scripts marcados como pendientes sin importar si están intercalados o no.
Parámetros:
Ninguno
Ejemplo:

java -jar dbSubversion.jar pending


pendingByVersion

Ejecuta un script marcado como pendiente indicando la version del script que se quiere ejecutar.
Parámetros:
versionId de script pendiente a ejecutar
Ejemplo:

java -jar dbSubversion.jar pendingByVersion 20120228152105


Warnings

1.- No eliminar o limpiar la tabla de changelog.
2.- Si se cambia de usuario al conectarse la base de datos, revisar primero si tiene el mismo esquema default de lo contrario o se homologa el esquema, o se vuelve a conectar con un usuario que si tenga el mismo esquema default y que pueda ver la tabla changelog.
3.- No renombrar ninguna carpeta o archivo dentro de dbSubversion a excepción de los scripts creados por la herramienta, es decir, no renombrar "scripts", "templates","docs", ni mucho menos los archivos de Migrate.properties, changelogConfig.properties
4.- Si se va a renombrar un script asegúrese de que primero no esté ejecutado o con fecha de registro, si ya está ejecutado se debe de hacer un delete from changelog where name like 'nombre del script';