Repository navigation
FAQ
Preguntas frecuentes sobre GitDB.
GitDB es un ORM ligero que transforma repositorios Git en bases de datos relacionales. Combina el control de versiones de Git con operaciones CRUD type-safe.
✅ Usa GitDB para:
- Aplicaciones que necesitan auditoría completa
- Proyectos pequeños/medianos con pocos registros
- Sistemas con sincronización distribuida
- Data que se beneficia del historial de Git
❌ NO uses GitDB para:
- Millones de registros
- Aplicaciones con alto volumen transaccional
- Búsquedas complejas frecuentes
- Análisis de datos en tiempo real
GitDB funciona en memoria con datos en filesystem/Git. Para:
- < 10,000 registros: ✅ Excelente
- 10,000 - 100,000 registros:
⚠️ Acceptable (depende del hardware) -
100,000 registros: ❌ No recomendado
Node.js >= 20
Sí. Git debe estar disponible en el PATH del sistema.
which git # En macOS/LinuxNo. GitDB está diseñado para Node.js server-side.
GitDB no tiene migrations. Para cambiar schema:
- Edita la definición de entity en tu código
- Ejecuta un script que migre los datos manualmente
- GitDB crea automáticamente un commit con los cambios
// Viejo schema
const User = entity('users', {
id: uuid().primary(),
name: text()
});
// Nuevo schema
const User = entity('users', {
id: uuid().primary(),
name: text(),
email: text().unique() // Campo nuevo
});
// Migrar datos
const users = await db.select().from(User);
for (const user of users) {
await db.update(User)
.set({ email: `${user.name}@example.com` })
.where(eq('id', user.id));
}GitDB valida tipos en TypeScript. Para validación en runtime, usa bibliotecas como Zod:
import { z } from 'zod';
const UserSchema = z.object({
id: z.string().uuid(),
name: z.string(),
email: z.string().email()
});
const validated = UserSchema.parse(data);
await db.insert(User).values(validated);Los operadores WHERE son type-safe:
// ✅ Compilará
await db.select().from(User).where(eq('name', 'John'));
// ❌ Error en compilación - 'nonexistent' no existe
await db.select().from(User).where(eq('nonexistent', 'John'));Sí, combinando operadores:
const users = await db
.select()
.from(User)
.where(
or(
and(gte('age', 18), eq('country', 'US')),
and(gte('age', 21), eq('country', 'UK'))
)
);No integrada. Pero puedes implementarla:
const page = 2;
const pageSize = 10;
const users = await db.select().from(User);
const paginated = users.slice((page - 1) * pageSize, page * pageSize);defineRelations(User, {
posts: {
type: 'many',
entity: Post,
foreignKey: 'userId'
}
});No. Debes manejar manualmente:
// Eliminar posts primero
await db.delete().from(Post).where(eq('userId', userId));
// Luego eliminar usuario
await db.delete().from(User).where(eq('id', userId));Sí:
const user = await db
.select()
.from(User)
.include({
posts: {
include: {
comments: true
}
}
});Changesets es un sistema automático de versionado semántico. Automatiza:
- Versioning (MAJOR.MINOR.PATCH)
- Changelog generation
- Publicación en NPM
- Crea un changeset:
npm run changeset - Push a main/develop
- GitHub Actions crea PR de versión automáticamente
- Merge el PR → Publicación automática en NPM
Un NPM_TOKEN configurado en GitHub Secrets:
- npmjs.com → Account → Auth Tokens
- Crear token con permisos "Publish"
- GitHub → Settings → Secrets →
NPM_TOKEN
npm run releasePero es mejor usar changesets para historial limpio.
Sí. insert/update/delete crean commits automáticos:
await db.insert(User).values(data); // Commit automático
await db.update(User).set(updates).where(...); // Otro commitSí, con Git:
git log --oneline # Ver commits
git revert <commit-hash> # Revertir commit específico
git reset --hard HEAD~1 # Deshacer último commitSí. GitDB respeta las branches de Git:
git checkout -b feature/new-feature
# Editar datos con GitDB
# Hacer commits automáticos
git merge main- Filtra en la query:
// ❌ Lento - carga todos
const all = await db.select().from(User);
const filtered = all.filter(u => u.age > 18);
// ✅ Rápido - filtra en lectura
const filtered = await db
.select()
.from(User)
.where(gt('age', 18));- Usa campos específicos:
// ❌ Carga todo
const users = await db.select().from(User);
// ✅ Carga solo lo necesario
const users = await db.select(['id', 'name']).from(User);Git es muy eficiente:
- Almacenamiento: ~10% overhead por historial
- Lectura: ~1-5ms por operación en SSD
- Escritura: ~10-50ms por operación en SSD
// Caché simple
const cache = new Map();
async function getUser(id) {
if (cache.has(id)) return cache.get(id);
const user = await db.select().from(User).where(eq('id', id));
cache.set(id, user);
return user;
}Sí con npm run dev:
npm run dev # Watch modeconst db = await gitDb({
dir: './data',
author: { name: 'App', email: 'app@example.com' },
logger: console // Enable logging
});npm run typecheck # Verifica tipos sin compilar- Asegúrate que Git está instalado en el servidor
- Copia el repositorio con datos
- GitDB continuará funcionando normalmente
# En producción
git clone <repo-url>
cd <repo>
npm ci
npm startSí. Los datos son el Git repo. Cada cambio es un commit:
# Historial completo
git log --stat
# Ver cambios de datos
git show <commit-hash>Sí, con git pull/push:
# En servidor B
git pull origin main
# Datos sincronizados automáticamenteGit no está en el PATH. Instala Git:
# macOS
brew install git
# Linux
sudo apt install git
# Windows
choco install gitVerifica permisos del directorio:
chmod -R 755 ./dataAsegúrate que Git está configurado:
git config --global user.name "CI Bot"
git config --global user.email "ci@example.com"- Getting Started - Tutorial rápido
- API Reference - Documentación completa
- Examples - Ejemplos prácticos
- Abre un issue en GitHub