APEX 03 - 08 - Historial de cambios y control de código fuente para Oracle APEX (Primera Parte)

En esta octava entrega de la SAGA Ciclo de Desarrollo para aplicaciones APEX veremos la primera parte de cómo administrar el historial de cambios en nuestras aplicaciones Oracle APEX mediante el control del código fuente. 

Administra el historial de cambios en tus aplicaciones mediante el control de código fuente

👀 A nadie le gusta perder trabajo, por ello, creamos copias de seguridad periódicas de nuestro trabajo en curso, de hecho, Oracle APEX también realiza copias de seguridad sistemáticas de sus aplicaciones también. Sin embargo, el seguimiento del historial de cambios en los artefactos de la aplicación a lo largo del tiempo en un repositorio ofrece muchas ventajas adicionales. 

Como veremos en esta entrega, es fácil hacer esto combinando un sistema de gestión de control de fuente (SCM) como Git con una herramienta de Oracle como SQLcl.

Ventajas de utilizar un repositorio de código fuente

Un repositorio de código fuente es como una máquina del tiempo para nuestros proyectos. Un sistema SCM mantiene automáticamente información adicional "contable" sobre los archivos del proyecto, de modo que, en cualquier momento, para cualquier cambio, en cualquier archivo de aplicación, a lo largo de la vida de nuestros proyectos, podremos responder preguntas como: ¿Quién realizó el cambio? ¿Qué se agregó o modifico? ¿Cuándo se hizo? Y quizás lo más importante: ¿Por qué se hizo? 

La aplicación del repositorio de control del código fuente de nuestras aplicaciones proporcionan el contexto histórico sobre quién en el equipo solucionó qué error o implementó qué nueva característica, y conoce los artefactos de la aplicación que se agregaron o cambiaron en el proceso. 

El repositorio se convierte en la "fuente de verdad" para nuestros proyectos, permitiéndonos etiquetar un conjunto particular de artefactos que fueron entregados a los usuarios finales con un nombre significativo como "Versión 1.0.4" cada vez que el equipo alcanza un hito importante.  

En cualquier momento posterior, podemos utilizar el nombre de una etiqueta de lanzamiento para retroceder en el tiempo y recuperar exactamente el conjunto correcto de archivos de versiones de artefactos de las aplicaciones, para aplicar, con confianza, por ejemplo, una corrección de errores incremental a una versión anterior de la aplicación. 

El visualizar el historial de cambios agrupado por característica lógica o solución, también simplifica la determinación de qué cambios son necesarios para revertir una característica específica o introducir esa característica en una versión anterior de nuestras aplicaciones.

Utiliza Git para gestionar los cambios de tus aplicaciones

Git es un sistema de gestión de control de código fuente gratuito que es el estándar de facto para los equipos que realizan desarrollo en todo el mundo. Su naturaleza de código abierto y su popularidad entre otros proyectos de desarrollo de código abierto le han dado una confianza bien ganada desde su debut en el año 2005. 

📕 La copia permanente del repositorio del equipo reside en un servidor. Este servidor puede ser “clonado” en otra máquina para usarlo como área de trabajo local y alli agregar, cambiar o eliminar artefactos del proyecto sin afectar inmediatamente al repositorio permanente del equipo. 

Cuando los cambios locales pendientes en los artefactos del proyecto en el área de trabajo están listos para hacerse permanentes, de forma similar a una transacción de base de datos, pueden ser "confirmados" junto con un mensaje de registro que explica la corrección del error o la funcionalidad que ha sido implementada.  Como paso final, los cambios confirmados son “empujados” al servidor permanente del equipo. 

La copia de trabajo local se puede eliminar en este momento o se puede conservar y ser actualizada para incluir cualquier cambio posterior realizado en el repositorio permanente del equipo "extrayendo" esos cambios a demanda.

Comienza por confirmar periódicamente la exportación de una aplicación

👉El equipo de APEX, alla por 2022 realizó una encuesta a desarrolladores de APEX, dicha encuestra reveló que dos tercios están utilizando algún tipo de sistema de gestión para el control de código fuente. Sin embargo, esto significa que a un tercio de las aplicaciones APEX les falta un seguimiento detallado en el historial de cambios. 

Eres de esos desarrolladores de APEX que actualmente no usan Git, pues aqui te muestro cómo comenzar para que periódicamente confirmes la exportación de una aplicación a un repositorio hosteado.

Elije un repositorio Git alojado

Si bien es posible instalar el software del servidor Git on-premise (localmente), una forma aún más sencilla de comenzar es crear un repositorio de equipo privado en uno de los servicios de alojamiento Git disponibles. 

Tanto GitHub como GitLab son populares servicios de alojamiento Git cuyas ofertas de nivel gratuito atraen a equipos pequeños. Los equipos más grandes pueden actualizar a opciones pagas.

Los proyectos de APEX que utilizan Oracle Cloud pueden evaluar otras opciones nativas para un repositorio Git alojado: Oracle VB Studio y OCI Devops de un único proveedor de servicios de ciclo de vida de desarrollo de aplicaciones alojadas puede satisfacer mejor ese tipo de necesidades y ambas opciones basadas en OCI son gratuitas para los clientes de OCI, solo se paga por el almacenamiento y el procesamiento para los trabajos de desarrollo (no tengo experiencia con este servicio por lo que no lo trataré en este post, lo menciono porque se de su existencia y su conveniencia de uso).

Ahora, ya con un repositorio Git creado, el trabajo está a medio hacer. 

Cada vez que el equipo alcanza un hito significativo, simplemente debemos elegir a un miembro del equipo para que sea el responsable de exportar la definición de la aplicación desde el espacio de trabajo de desarrollo de APEX, tambien que exporte las definiciones de objetos de la base de datos desde la base de datos de desarrollo, luego, copie estos archivos de aplicación exportados a un área de trabajo local de Git y confirme los cambios en el repositorio permanente del equipo en Git. 

Los comandos para estos pasos se describen más adelante y funcionan de la misma manera sin importar dónde se encuentre albergado el repositorio permanente del equipo.

Instala la última versión de la línea de comandos SQL (SQLcl)

Con la utilidad de línea de comandos SQL de Oracle (SQLcl), podemos exportar nuestra aplicación APEX, así como los cambios en los objetos de nuestro esquema de base de datos a archivos de texto en un sistema de archivos. Estos archivos se copian a un área de trabajo de Git para luego confirmar los cambios en el repositorio de equipo. En todas las plataformas, la forma más sencilla de instalar SQLcl es:

• Asegúrate de que Java 11 esté instalado primero y luego
• Descargar y descomprime la última versión de SQLcl desde: https://download.oracle.com/otn_software/java/sqldeveloper/sqlcl-latest.zip

La utilidad SQLcl es el programa sql en el subdirectorio ./sqlcl/bin, el cual puedes agregar a la ruta del sistema operativo para invocar sql desde cualquier lugar. De forma alternativa, en Mac, si utilizas el administrador de paquetes Brew, puedes ejecutar brew install sqlcl, o en Oracle Linux usar yum sqlcl (OL7) o dnf sqlcl (OL8). Los ejemplos en este artículo han sido validados usando SQLcl versión 22.3.1 y APEX 22.1, estoy trabajando para validar esto mismo con SQLcl 24.1.0 y APEX 24.1, en cuanto lo tenga listo agrego aquí un enlace al post actualizado.

Exporta una aplicación APEX usando SQLcl

Después de ejecutar SQLcl con las credenciales de conexión del esquema de base de datos relacionado con nuestra aplicación APEX, usaremos el comando apex export para exportar una aplicación al directorio actual. Para ello, proporcionaremos la identificación de la aplicación (por ejemplo, 12345) usando la opción -applicationid como se muestra a continuación:

$ sql username/password@host:puerto/servicio

SQL> apex export -applicationid 12345

De forma predeterminada, se exporta la aplicación 12345 como un único archivo f12345.sql. Sin embargo, para fines de control de fuente, es una mejor práctica usar la opción -split para dividir la exportación en un archivo por cada componente.

SQL> apex export -applicationid 12345 -split

Esto creará un subdirectorio f12345, en el directorio actual estará el archivo install.sql y un directorio de la aplicación (y posiblemente también un directorio del espacio de trabajo). Estos directorios contendrán un archivo por componente muy bien organizado en más subdirectorios según el tipo de componente. Estas otras opciones de exportación evitan diferencias innecesarias en tus archivos:

• -skipExportDate: evita incluir la fecha de exportación en cada archivo

• -expOriginalIds: mantiene la coherencia del componente de la aplicación en todos los entornos.

• -expSupportingObjects: incluye scripts de objetos de soporte que haya definido

• -expType: especifica uno o más formatos de exportación

El formato de exportación predeterminado es la fuente de la aplicación, por lo que no mencionar un tipo de exportación equivale a usar la opción -expType APPLICATION_SOURCE. Otros valores de tipo de exportación admitidos incluyen:

• READABLE_YAML: para comprender más fácilmente qué ha cambiado, o

• EMBEDDED_CODE: para simplificar el análisis externo del código SQL y JavaScript incorporado.

La opción -expType acepta un valor separado por comas para que una operación de exportación pueda producir múltiples formatos.

Una mejor práctica para exportar la aplicación APEX 123456 desde la línea de comandos SQLcl es dividirla en archivos de componentes que incluyan tanto el código fuente de la aplicación como los formatos YAML legibles, esto se hace como se muestra en el siguiente ejemplo:

$ sql username/password@host:puerto/servicio

SQL> apex export -applicationid 12345 -split -skipExportDate -expOriginalIds -expSupportingObjects Y -expTipo APPLICATION_SOURCE,READABLE_YAML

Bueno, hasta aqui hemos visto la importancia de contar con un historial de cambios y llevar el control del código fuente de nuestra aplicación, además hemos visto como podemos exportar nuestra aplicación utilizando SQLcl.. y se preguntarán, porqué muestro una herramienta de linea de comandos para realizar la exportación de aplicaciones cuando desde la interfaz de APEX puedo tranquilamente realizar lo mismo.. pues la respuesta es sencilla, porque la idea es AUTOMATIZAR este proceso, y para ello necesitamos herramientas de linea de comandos.

En la proxima entrega hablaremos de cómo exportar los objetos de esquema de base de datos, crear una utilidad que combine la exportación de nuestra aplicación APEX, la exportación de los objetos de esquema y la incorporación de estos archivos de exportación a un repositorio Git y por último, cómo ver el historial de cambiso de nuestras aplicaciones.

No te pierdas la proxima entrega de: Historial de cambios y control de código fuente para Oracle APEX (Segunda Parte)

Juntos, creamos las aplicaciones del futuro!

Mi nombre es José Preda.

* José es Analista de Sistemas e Ingeniero de Software con especializaciones en tecnologías de Oracle, Microsoft, redes, infraestructura tecnológica y gestión de recursos humanos. Posee más de 30 años de experiencia en el área de tecnología, es de Paraguay, vive y trabaja en San Luis, Argentina. Fue consultor, capacitador y soporte técnico para Base de Datos y herramientas de Oracle, desde el año 2013 es miembro activo del Grupo de Usuarios Oracle de Argentina del cual es miembro del directorio desde el año 2023. Es CEO de su propia Consultora: Soft San Luis, una startup especializada en brindar formación profesional, consultoría, mentoría y soluciones con tecnología Oracle y Oracle APEX a empresas, equipos de desarrollo de consultoras y a particulares. En 2024 ha sido reconocido como  Oracle ACE Associate por la Corporación Oracle por sus contribuciones a la Comunidad de Usuarios de Tecnologías de Oracle