@teamnet/ic-orm/readme.md

Database Management System for Total.js v4 and standalone

## This ORM Works only for iCOne Systems. PLease, use Total.js Version for free.

# Node Database Management System (ORM)

- [__Documentation__](https://docs.totaljs.com/dbms/)
- [Website](https://www.totaljs.com/)
- [__Documentation__](https://docs.totaljs.com/total4/)
- [Chat support](https://platform.totaljs.com/?open=messenger)
- [Join __Total.js Telegram__](https://t.me/totalplatform)
- [Support](https://www.totaljs.com/support/)
- supports `PostgreSQL`, `MySQL`, Total.js `TextDB` and `MongoDB` (with connection pooling)

---

## 📚 Documentación Completa

Esta librería incluye documentación completa y detallada para desarrolladores:

### 🍃 [MongoDB - Documentación Completa](./docs/mongodb/)
Guías completas para trabajar con MongoDB:
- **59 tests certificados** ✅
- [Guía de Inicio Rápido](./docs/mongodb/mongodb-quickstart.md)
- [Connection Pooling y ReplicaSets](./docs/mongodb/mongodb-connection.md)
- [Operaciones CRUD](./docs/mongodb/mongodb-crud.md)
- [Query Builder Avanzado](./docs/mongodb/mongodb-query-builder.md)
- [Operadores Matemáticos](./docs/mongodb/mongodb-operators.md)
- [Operaciones Avanzadas (Scalar, GridFS, Aggregation)](./docs/mongodb/mongodb-advanced.md)
- [Ejemplos Prácticos](./docs/mongodb/mongodb-examples.md)

### 🐘 [PostgreSQL - Documentación Completa](./docs/postgresql/)
Guías completas para trabajar con PostgreSQL:
- **108 tests certificados** ✅
- [Guía de Inicio Rápido](./docs/postgresql/postgresql-quickstart.md)
- [Connection Pooling v16 Optimizado](./docs/postgresql/postgresql-connection.md)
- [Operaciones CRUD](./docs/postgresql/postgresql-crud.md)
- [Query Builder Avanzado](./docs/postgresql/postgresql-query-builder.md)
- [Operadores (GREATEST, LEAST, NOT)](./docs/postgresql/postgresql-operators.md)
- [Operaciones Avanzadas (Transacciones ACID, JSONB)](./docs/postgresql/postgresql-advanced.md)
- [Ejemplos Prácticos](./docs/postgresql/postgresql-examples.md)

**Total: 8,735+ líneas de documentación profesional | 167 tests certificados**

---

## Initialization

- installation `$ npm i @teamnet/ic-orm`
   - install MySQL: `$ npm install mysql2`
   - install PostgreSQL: `$ npm install pg`
   - install MongoDB: `$ npm install mongodb`

```js {"id":"01J5MZWYZG4RMQZZ3JTJEYW4GG"}
const dbms = require('@teamnet/ic-orm');

dbms.init([alias], connection_string);
// @alias {String} Optional, alias for connection string (default: 'default')
// @connection_string {String} A connection string to DB

// PostgreSQL
dbms.init('postgresql://user:pass@localhost:5432/dbname');
dbms.init('mypg', 'postgresql://user:pass@localhost:5432/dbname?max=10'); // with a name and connection pool

// MySQL & Maria DB
dbms.init('mysql://user:pass@localhost:3306/dbname');
dbms.init('mysql', 'mysql://user:pass@localhost:3306/dbname?max=10'); // with a name and connection pool

// MongoDB
dbms.init('mongodb://user:pass@localhost:27017/dbname');
dbms.init('mongo', 'mongodb://user:pass@localhost:27017/dbname?max=10'); // with a name and connection pool

// MongoDB with ReplicaSet
dbms.init('mongodb://user:pass@server1:27017,server2:27017,server3:27017/dbname?replicaSet=rs0&readPreference=secondaryPreferred&max=30');

// Total.js NoSQL embedded
dbms.init('nosql');
dbms.init('mynosql', 'nosql'); // with a name for more DB engines

// Total.js Table
dbms.init('table');
dbms.init('mytable', 'nosql'); // with a name for more DB engines
```

## Usage

```js {"id":"01J5MZWYZK2TDT6RFFP72RRWVP"}
// Is a global method
var db = DBMS();

// Finds records
// A response: Array
// returns QueryBuilder
db.find('collection_table_name');
db.find('mypg/collection_table_name');
db.find('mynosql/collection_table_name');
db.find('mytable/collection_table_name');

// Finds the one record
// A response: Object
// returns QueryBuilder
db.one('collection_table_name');
db.one('mypg/collection_table_name');
db.one('mynosql/collection_table_name');
db.one('mytable/collection_table_name');

// Inserts a new record
// A response: Number
// returns QueryBuilder
db.insert('collection_table_name', document, [unique]);
db.insert('mypg/collection_table_name', document, [unique]);
db.insert('mynosql/collection_table_name', document, [unique]);
db.insert('mytable/collection_table_name', document, [unique]);
```

## Connection Pooling

ICORM soporta connection pooling para PostgreSQL, MySQL y MongoDB. Los parámetros de configuración se pasan a través de la cadena de conexión.

### PostgreSQL Connection Pool

```js
// Formato: postgresql://user:pass@host:port/dbname?max=10&min=2&timeout=1000
// - max: número máximo de conexiones en el pool (por defecto: 8, recomendado: 8-20)
// - min: número mínimo de conexiones en el pool (por defecto: 2, recomendado: 2-4)
// - timeout: tiempo de inactividad en milisegundos (por defecto: 30000)
// - ssl: habilitar SSL (true/false)
// - pooling: habilitar pooling (por defecto: true)
// - native: usar bindings nativos (opcional)

dbms.init('postgresql://user:pass@localhost:5432/dbname?max=10&min=2&timeout=10000');

// Configuración optimizada para alta concurrencia (PostgreSQL v16):
dbms.init('postgresql://user:pass@10.21.24.200:5432/pro_icone?max=8&min=2&timeout=10000');
```

**Mejoras PostgreSQL v16:**
- ✅ Pool compartido con reconexión automática
- ✅ Reintentos inteligentes con backoff exponencial
- ✅ Manejadores de eventos del pool
- ✅ Soporte para `maxUses` (previene memory leaks)
- ✅ Compatible con PostgreSQL v16 y driver `pg` v8.x

### MySQL Connection Pool

```js
// Formato: mysql://user:pass@host:port/dbname?max=10
// - max: límite de conexiones (connectionLimit) (por defecto: 4)
// - ssl: habilitar SSL (true/false)

dbms.init('mysql://user:pass@localhost:3306/dbname?max=10');
```

### MongoDB Connection Pool

```js
// Formato: mongodb://user:pass@host:port/dbname?max=10
// - max o maxPoolSize: número máximo de conexiones en el pool (por defecto: 10)
// - Soporta todas las opciones estándar de MongoDB como replicaSet, readPreference, etc.

dbms.init('mongodb://user:pass@localhost:27017/dbname?max=10');

// Ejemplo con ReplicaSet
dbms.init('mongodb://user:pass@server1:27017,server2:27017,server3:27017/dbname?replicaSet=rs0&readPreference=secondaryPreferred&max=30');
```

### Cierre de conexiones

Puedes cerrar explícitamente las conexiones para MongoDB y PostgreSQL:

**MongoDB:**
```js
const mongo = require('./mongo');

// Cerrar la conexión explícitamente
await mongo.disconnect();

// O con callback
mongo.disconnect(function() {
  console.log('Conexión MongoDB cerrada');
});
```

**PostgreSQL:**
```js
const pg = require('./pg');

// Cerrar todos los pools de PostgreSQL
await pg.disconnect();

// O con callback
pg.disconnect(function(err) {
  if (err) console.error('Error al cerrar pools:', err);
  else console.log('Pools de PostgreSQL cerrados');
});
```

**En Total.js v4 (al cerrar la aplicación):**
```js
// definitions/events.js
ON('exit', async function() {
    console.log('Cerrando conexiones de base de datos...');
    await require('icorm/pg').disconnect();
    await require('icorm/mongo').disconnect();
    console.log('Conexiones cerradas correctamente');
});
```

---

## 📖 Más Información

Para aprender más sobre cómo usar icorm con MongoDB o PostgreSQL, consulta la documentación completa:

- 🍃 **[MongoDB - Documentación Completa](./docs/mongodb/)** - Guías, ejemplos y mejores prácticas
- 🐘 **[PostgreSQL - Documentación Completa](./docs/postgresql/)** - Guías, transacciones ACID y operaciones avanzadas
- 📚 **[Índice General](./docs/)** - Vista general de toda la documentación

**Incluye:**
- Guías de inicio rápido paso a paso
- Connection pooling optimizado
- Operaciones CRUD completas
- Query Builder avanzado con todos los operadores
- Operaciones matemáticas y SQL específicas
- Transacciones, Scalar operations, BLOB storage
- Ejemplos prácticos de sistemas completos
- Solución de problemas y mejores prácticas

**✅ Todo verificado con 167 tests certificados (59 MongoDB + 108 PostgreSQL)**

---

## 👥 Autor y Mantenimiento

**icorm v1.2.0** - Actualizado y mantenido por **[Teamnet.S.L.](https://www.teamnet.es)**

- 🔧 Mejoras de PostgreSQL v16 con connection pooling optimizado
- 🔧 Soporte completo para MongoDB con ReplicaSets
- 🔧 Reintentos automáticos con backoff exponencial
- 🔧 Event handlers y gestión avanzada de pools
- 📚 Documentación completa profesional (8,735+ líneas)
- ✅ 167 tests certificados

**Basado en Total.js DBMS** - Framework original por [Total.js Platform](https://www.totaljs.com)

---

## 📄 Licencia

Esta es una versión modificada y mejorada del ORM de Total.js, mantenida por Teamnet.S.L. para uso interno y de clientes.

Para la versión pública original, consulta: [Total.js DBMS](https://docs.totaljs.com/dbms/)