DatabaseManager

This document provides instructions for using DatabaseManager, an asynchronous, singleton-based SQLite helper class designed for robust performance in Android applications. It prevents UI freezes by executing all database operations on a background thread and returns results to the main thread via callbacks.

---

1. Initial Setup

Adding the Component

To start using DatabaseManager, you must add its component to every Activity or Fragment where you need it. It is recommended to use the same component name every time it is created within the same application.

Getting the Instance

DatabaseManager uses a singleton pattern to ensure a single, consistent connection point for each database. You should always get the instance in the onCreate event of each activity. Select the component, enter the database name, and its version (default is 1).

---

2. Schema Management

Creating a Table

To create a new table, specify a table name and a definition for columns and their SQL data types. The operation uses CREATE TABLE IF NOT EXISTS to prevent errors on repeated calls.

You can also define foreign key constraints here, such as ON DELETE CASCADE.

---

3. CRUD Operations

Standard methods for data manipulation: Create, Read, Update, and Delete.

Inserting Data

To add a new row to a table, provide the table name and the column-value pairs to insert. The callback will return the auto-incremented ID of the new row in the get insert id number variable.

Reading Data (Multiple Records)

To retrieve multiple records, specify the table and optional selection criteria (WHERE clause). The result is returned as an ArrayList of HashMap objects (known as a ListMap in Sketchware). This list is ready to be used anywhere in your activity or fragment.

Reading a Single Record

For retrieving a single row, this method is optimized to return only the first matching record as a single HashMap (known as a Map variable in Sketchware).

Updating Data

To modify existing records, specify the table, the new data, and a WHERE clause. The callback returns the number of rows affected in the rowsAffected number variable.

Deleting Data

To remove records, provide the table name and a WHERE clause. The callback returns the number of rows deleted.

---

4. Utility Methods

Helper methods for common checks and queries.

Existence Checks

These methods are designed for quick checks to see if a table, column, or specific value exists. A boolean (true/false) is returned in the callback.

Get Row Count

This method efficiently retrieves the total number of rows in a specified table.

Execute Raw Query

For complex queries not covered by standard methods (e.g., JOIN), you can execute a raw SQL query. This method returns a ListMap, similar to readData. Blocks are available with and without arguments.

Insert or Update

This convenience method checks for a record's existence. If it exists, it's updated; otherwise, a new record is inserted. Useful for data synchronization.

---

5. Management Operations

Clear or Delete a Table

Delete Table completely removes the table from the database. Clear Table removes all records from the table, returning the number of affected rows in the rowsAffected variable.

Close the Database

This block closes the database connection globally. Only use it when you are certain no other part of your app will need database access. If your app frequently accesses the database, it's better to let the Android system manage the connection lifecycle.

Este documento proporciona instrucciones para el uso de DatabaseManager, una clase de ayuda para SQLite, asíncrona y basada en el patrón singleton, diseñada para un rendimiento robusto en aplicaciones Android. Evita el congelamiento de la UI (Interfaz de Usuario) al ejecutar todas las operaciones de la base de datos en un hilo secundario y devuelve los resultados al hilo principal mediante callbacks.

---

1. Configuración Inicial

Añadir el Componente

Para comenzar a usar DatabaseManager, debemos añadir su componente a cada Actividad o Fragmento donde lo necesitemos. Se recomienda usar el mismo nombre de componente cada vez que sea creado en una misma aplicación.

Obtener la Instancia

DatabaseManager utiliza un patrón singleton para asegurar un punto de conexión único y consistente para cada base de datos. Se debe obtener siempre la instancia en el evento onCreate de cada actividad. Seleccionamos el componente, escribimos el nombre de la base de datos y su versión (por defecto 1).

Ahora podemos comenzar a realizar operaciones.

---

2. Gestión del Esquema

Crear una Tabla

Para crear una tabla, especifique su nombre y defina las columnas con sus tipos de dato SQL. La operación usa CREATE TABLE IF NOT EXISTS para prevenir errores en llamadas repetidas.

Aquí puede definir restricciones de clave foránea (FOREIGN KEY), como por ejemplo ON DELETE CASCADE.

---

3. Operaciones CRUD

Métodos estándar para la manipulación de datos: Crear, Leer, Actualizar y Borrar.

Insertar Datos

Para añadir una nueva fila a una tabla, proporcione el nombre de la tabla y los pares columna-valor a insertar. El callback devolverá el ID autoincremental del registro en la variable numérica get insert id.

Leer Datos (Múltiples Registros)

Para recuperar múltiples registros, especifique la tabla y criterios de selección opcionales (cláusula WHERE). El resultado se devuelve como un ArrayList de objetos HashMap, conocido en Sketchware como ListMap. La lista obtenida estará lista para usar de forma normal en cualquier lugar.

Leer un Registro Único

Para recuperar una sola fila, este método está optimizado para devolver únicamente el primer registro coincidente como un único HashMap, conocido en Sketchware como variable Map.

Actualizar Datos

Para modificar registros existentes, especifique la tabla, los nuevos datos y una cláusula WHERE. El callback devuelve el número de filas afectadas en la variable numérica rowsAffected.

Borrar Datos

Para eliminar registros, proporcione el nombre de la tabla y una cláusula WHERE. El callback devuelve el número de filas eliminadas.

---

4. Métodos de Utilidad

Métodos de ayuda para consultas y comprobaciones comunes.

Comprobaciones de Existencia

Estos métodos están pensados para consultas rápidas y tienen 3 usos principales:

• Verificar si la tabla especificada existe.
• Verificar si la columna especificada existe.
• Verificar si un valor especificado en una columna existe.

Se devolverá true o false en el callback según el resultado.

Obtener Conteo de Filas

Este método recupera de forma eficiente el número total de filas en una tabla específica.

Ejecutar Consulta Directa (Raw Query)

Para consultas complejas no cubiertas por los métodos estándar (ej. JOIN), puede ejecutar una consulta SQL directa. Este método devuelve un ListMap. Incluye un bloque con argumentos y otro sin ellos.

Insertar o Actualizar

Este método comprueba la existencia de un registro. Si existe, se actualiza; de lo contrario, se inserta uno nuevo. Es útil para tareas de sincronización de datos.

---

5. Operaciones de Gestión

Limpiar, Borrar Tabla y Obtener Error

Delete table elimina la tabla de la base de datos. Clear table elimina todos los registros de la tabla y devuelve en la variable numérica rowsAffected la cantidad de registros afectados. El bloque get error message obtiene el mensaje de error del callback.

Cerrar la Base de Datos

Este bloque cierra la conexión a la base de datos de forma global. Solo se debe ejecutar cuando no se necesite acceder más a la base de datos desde ninguna parte de la aplicación. Si tu aplicación accede constantemente a la base de datos, es mejor dejar que el sistema Android gestione el cierre por sí mismo.