@kitdbase/mysql-orm
Índice
Introducción
@kitdbase/mysql-orm
es una biblioteca de Node.js diseñada para simplificar las interacciones con bases de datos MySQL utilizando un enfoque orientado a objetos. Esta biblioteca te permite realizar operaciones CRUD (Crear, Leer, Actualizar, Eliminar) fácilmente, así como gestionar la estructura de tus tablas.
Características
- Conexión a MySQL: Gestión de conexiones a la base de datos utilizando el patrón Singleton.
- Operaciones CRUD: Realizar operaciones de inserción, selección, actualización y eliminación.
- Consultas avanzadas: Soporte para consultas con
JOIN
, WHERE
, ORDER BY
, GROUP BY
, LIMIT
, OFFSET
, etc.
- Gestión de tablas: Crear, eliminar y modificar tablas y columnas.
- Validación de datos: Validación automática de tipos de datos y valores antes de ejecutar consultas.
- Manejo de errores: Gestión y reporte eficiente de errores.
Instalación
Para instalar la biblioteca, ejecuta el siguiente comando:
npm install @kitdbase/mysql-orm
Configuración
Antes de usar la biblioteca, asegúrate de configurar las variables de entorno necesarias en un archivo .env:
MYSQL_HOST=localhost
MYSQL_USER=root
MYSQL_PASSWORD=password
MYSQL_DATABASE=mydatabase
MYSQL_PORT=3306
Uso básico
Conexión a la base de datos
La conexión se establece automáticamente al crear una instancia de MySQL. No necesitas conectarte manualmente.
import db from "@kitdbase/mysql-orm";
Operaciones de tabla
Crear una tabla
Puedes crear una tabla utilizando el método create
. Define las columnas y sus propiedades.
const usersTable = db.table("users");
await usersTable.create([
{ name: "id", type: "INT", options: ["primary", "autoincrement"] },
{ name: "name", type: "VARCHAR", length: 255 },
{ name: "email", type: "VARCHAR", length: 255 },
{ name: "age", type: "INT", defaultValue: 18 },
]);
Eliminar una tabla
Puedes eliminar una tabla utilizando el método drop
.
await usersTable.drop();
Operaciones CRUD
Insertar datos
Utiliza el método insert
para añadir nuevos registros a una tabla.
const newUsers = await usersTable.insert([
{ name: "Alice", email: "alice@example.com", age: 28 },
{ name: "Bob", email: "bob@example.com", age: 32 },
]);
console.log(newUsers);
Seleccionar datos
Utiliza el método select
para recuperar datos de una tabla.
const users = await usersTable.select(["id", "name", "email"]).get();
console.log(users);
Actualizar datos
Utiliza el método update
para modificar registros existentes.
await usersTable.where("id", "=", 1).update({ age: 29 });
Eliminar datos
Utiliza el método delete
para eliminar registros de una tabla.
await usersTable.where("id", "=", 2).delete();
Consultas avanzadas
Consulta con WHERE
Filtra registros utilizando el método where
.
const adultUsers = await usersTable.where("age", ">", 18).get();
console.log(adultUsers);
Consulta con OR WHERE
Utiliza orWhere
para añadir condiciones OR a tu consulta.
const users = await usersTable
.where("age", ">", 25)
.orWhere("name", "=", "Alice")
.get();
console.log(users);
Consulta con grupos de condiciones WHERE
Agrupa condiciones utilizando whereGroup
.
const users = await usersTable
.whereGroup((query) => {
query.where("age", ">", 25).orWhere("name", "=", "Jane");
})
.get();
console.log(users);
Consulta con BETWEEN
Busca valores entre un rango utilizando whereBetween
.
const users = await usersTable.whereBetween("age", [25, 35]).get();
console.log(users);
Consulta con IN
Busca valores que coincidan con un conjunto de valores utilizando whereIn
.
const users = await usersTable.whereIn("id", [1, 3, 5]).get();
console.log(users);
Consulta con IS NULL / IS NOT NULL
Busca valores nulos o no nulos utilizando whereNull
y whereNotNull
.
const usersWithoutEmail = await usersTable.whereNull("email").get();
const usersWithEmail = await usersTable.whereNotNull("email").get();
Consulta con JOIN
Une tablas utilizando el método join
.
const usersWithOrders = await usersTable
.join("orders", "users.id", "=", "orders.user_id")
.select(["users.name", "orders.order_id"])
.get();
console.log(usersWithOrders);
Consulta con LEFT JOIN
Realiza un left join utilizando el método leftJoin
.
const usersWithOrders = await usersTable
.leftJoin("orders", "users.id", "=", "orders.user_id")
.select(["users.name", "orders.order_id"])
.get();
console.log(usersWithOrders);
Consulta con RIGHT JOIN
Realiza un right join utilizando el método rightJoin
.
const ordersWithUsers = await usersTable
.rightJoin("orders", "users.id", "=", "orders.user_id")
.select(["users.name", "orders.order_id"])
.get();
console.log(ordersWithUsers);
Consulta con ORDER BY
Ordena resultados utilizando el método orderBy
.
const sortedUsers = await usersTable.orderBy("name", "ASC").get();
console.log(sortedUsers);
Consulta con LIMIT y OFFSET (paginación)
Limita el número de resultados y pagina utilizando limit
y page
.
const firstTwoUsers = await usersTable.limit(2).page(1).get();
const nextTwoUsers = await usersTable.limit(2).page(2).get();
console.log(firstTwoUsers);
console.log(nextTwoUsers);
Consulta con GROUP BY
Agrupa resultados utilizando el método groupBy
.
const usersByAge = await usersTable.groupBy("age").get();
console.log(usersByAge);
Consulta con DISTINCT
Recupera registros únicos utilizando el método distinct
.
const uniqueNames = await usersTable.distinct().select(["name"]).get();
console.log(uniqueNames);
Funciones de agregación
count
Cuenta el número de registros.
const userCount = await usersTable.count().first();
console.log(userCount);
sum
Calcula la suma de una columna.
const totalAge = await usersTable.sum("age").first();
console.log(totalAge);
avg
Calcula el promedio de una columna.
const averageAge = await usersTable.avg("age").first();
console.log(averageAge);
max
Encuentra el valor máximo en una columna.
const maxAge = await usersTable.max("age").first();
console.log(maxAge);
min
Encuentra el valor mínimo en una columna.
const minAge = await usersTable.min("age").first();
console.log(minAge);
Buscar registros
find
Encuentra un registro por un valor específico de columna.
const user = await usersTable.find(1, "id");
console.log(user);
first
Obtiene solo el primer registro que cumple con las condiciones.
const firstUser = await usersTable.where("age", ">", 25).first();
console.log(firstUser);
Gestión de columnas
Añadir columnas
Añade nuevas columnas a una tabla utilizando el método add
de columns()
.
await usersTable
.columns()
.add([{ name: "phone", type: "VARCHAR", length: 15 }]);
Editar columnas
Modifica columnas existentes utilizando el método edit
de columns()
.
await usersTable.columns().edit([
{
name: "email",
type: "VARCHAR",
length: 255,
defaultValue: "new@example.com",
},
]);
Eliminar columnas
Elimina columnas de una tabla utilizando el método delete
de columns()
.
await usersTable.columns().delete(["phone"]);
Ejecutar consultas SQL crudas
Si necesitas ejecutar una consulta SQL cruda, puedes utilizar el método query
.
const result = await db.query("SELECT * FROM users WHERE age > 25;");
console.log(result);
Manejo de errores
La biblioteca captura errores comunes, como errores de sintaxis SQL o problemas de conexión, y los devuelve en formato JSON.
try {
const result = await db.query("INVALID SQL QUERY;");
} catch (error) {
console.error(error);
}
API completa
Clase MySQL
table(tableName: string): TableQuery
Crea y devuelve una nueva instancia de TableQuery
para la tabla especificada.
const usersTable = db.table("users");
query(sqlQuery: string): Promise<{ status: string, message: string, data: any | null }>
Ejecuta una consulta SQL directa en la base de datos.
const result = await db.query("SELECT * FROM users;");
Clase TableQuery
create(fields: Field[]): Promise<boolean>
Crea una nueva tabla con los campos especificados.
await usersTable.create([
{ name: "id", type: "INT", options: ["primary", "autoincrement"] },
{ name: "name", type: "VARCHAR", length: 255 },
]);
drop(): Promise<boolean>
Elimina la tabla.
await usersTable.drop();
select(fields: string[] = []): TableQuery
Especifica las columnas a seleccionar en una consulta SELECT.
usersTable.select(["id", "name", "email"]);
where(column: string, operator: string | undefined, value: any): TableQuery
Añade una condición WHERE a la consulta.
usersTable.where("age", ">", 25);
orWhere(column: string, operator: string | undefined, value: any): TableQuery
Añade una condición OR WHERE a la consulta.
usersTable.orWhere("name", "=", "Jane");
whereGroup(callback: any): TableQuery
Añade un grupo de condiciones WHERE a la consulta.
usersTable.whereGroup((query) => {
query.where("age", ">", 25).orWhere("name", "=", "Jane");
});
whereBetween(column: string, [value1, value2]: any): TableQuery
Añade una condición WHERE BETWEEN a la consulta.
usersTable.whereBetween("age", [25, 35]);
whereIn(column: string, values: any): TableQuery
Añade una condición WHERE IN a la consulta.
usersTable.whereIn("id", [1, 3, 5]);
whereNull(column: string): TableQuery
Añade una condición WHERE IS NULL a la consulta.
usersTable.whereNull("email");
whereNotNull(column: string): TableQuery
Añade una condición WHERE IS NOT NULL a la consulta.
usersTable.whereNotNull("email");
join(table: string, column1: string, operator: string, column2: string): TableQuery
Añade una cláusula JOIN a la consulta.
usersTable.join("orders", "users.id", "=", "orders.user_id");
leftJoin(table: string, column1: string, operator: string, column2: string): TableQuery
Añade una cláusula LEFT JOIN a la consulta.
usersTable.leftJoin("orders", "users.id", "=", "orders.user_id");
rightJoin(table: string, column1: string, operator: string, column2: string): TableQuery
Añade una cláusula RIGHT JOIN a la consulta.
usersTable.rightJoin("orders", "users.id", "=", "orders.user_id");
orderBy(column: string, direction: string = 'ASC'): TableQuery
Añade una cláusula ORDER BY a la consulta.
usersTable.orderBy("name", "ASC");
groupBy(column: string): TableQuery
Añade una cláusula GROUP BY a la consulta.
usersTable.groupBy("age");
distinct(): TableQuery
Añade una cláusula DISTINCT a la consulta.
usersTable.distinct();
count(column = '*'): TableQuery
Añade una cláusula COUNT a la consulta.
usersTable.count();
sum(column: string): TableQuery
Añade una cláusula SUM a la consulta.
usersTable.sum("age");
avg(column: string): TableQuery
Añade una cláusula AVG a la consulta.
usersTable.avg("age");
max(column: string): TableQuery
Añade una cláusula MAX a la consulta.
usersTable.max("age");
min(column: string): TableQuery
Añade una cláusula MIN a la consulta.
usersTable.min("age");
limit(number: number): TableQuery
Añade una cláusula LIMIT a la consulta.
usersTable.limit(10);
page(number: number): TableQuery
Añade paginación a la consulta utilizando LIMIT y OFFSET.
usersTable.limit(10).page(2);
get(): Promise<any[]>
Ejecuta la consulta y devuelve todas las filas coincidentes.
const users = await usersTable.get();
first(): Promise<any | null>
Ejecuta la consulta y devuelve la primera fila coincidente.
const user = await usersTable.first();
insert(data: Record<string, any>[]): Promise<Record<string, any>[]>
Inserta nuevos registros en la tabla.
const newUsers = await usersTable.insert([
{ name: "Alice", email: "alice@example.com" },
]);
update(data: Record<string, any>): Promise<boolean>
Actualiza registros en la tabla según las condiciones WHERE.
await usersTable.where("id", "=", 1).update({ name: "Alice Smith" });
delete(): Promise<boolean>
Elimina registros de la tabla según las condiciones WHERE.
await usersTable.where("id", "=", 1).delete();
find(value: any, column: string = 'id'): Promise<any | null>
Encuentra un registro por su valor de columna.
const user = await usersTable.find(1);
columns(): Columns
Devuelve una instancia de la clase Columns para gestionar columnas de la tabla.
const columns = usersTable.columns();
Clase Columns
add(columns: Field[]): Promise<boolean>
Añade nuevas columnas a la tabla.
await usersTable
.columns()
.add([{ name: "phone", type: "VARCHAR", length: 15 }]);
edit(columns: Field[]): Promise<boolean>
Modifica columnas existentes en la tabla.
await usersTable.columns().edit([
{
name: "email",
type: "VARCHAR",
length: 255,
defaultValue: "example@mail.com",
},
]);
delete(columns: string[]): Promise<boolean>
Elimina columnas de la tabla.
await usersTable.columns().delete(["phone"]);
Licencia
Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.