From 4319cb390893fceb392bc4049bbaea24ce326956 Mon Sep 17 00:00:00 2001
From: Alvar San Martin <alvarsanmartin@savefamilygps.com>
Date: Fri, 20 Feb 2026 15:09:53 +0100
Subject: [PATCH] Docs

---
 README.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)

diff --git a/README.md b/README.md
index e69de29..ea34a51 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,85 @@
+# db-migration
+
+Herramienta de CLI orientada a aplicar migraciones de la base de datos,
+específicamente para *PostgreSQL*
+
+## Instalación
+
+De momento solo esta disponible para descargar desde el repositorio:
+
+``` bash
+# npm
+npm install "https://git.savefamilygps.net/alvarsanmartin/herramienta-migracion.git"
+
+# yarn
+yarn add "db-migrate@https://git.savefamilygps.net/alvarsanmartin/herramienta-migracion.git"
+```
+
+Para desarrollo local se puede linkar como paquete global o instalar como paquete
+local.
+
+```bash
+# global
+npm run link
+yarn link
+
+#local
+npm install /path
+yarn add /path
+
+```
+
+## Estructura de migraciones
+
+Para que la herramienta funcione se debe usar un directorio de migraciones que contenga
+archivos de migraciones con la siguiente estructura:
+
+``` text
+migrations/
+├ 1.0.0_create-tables.sql
+├ 1.2.0_date-columns.sql
+└ 1.2.5_date-format-fix.sql
+```
+
+Las migraciones se van a lanzar secuencialmente dentro de una transacción por
+lo que si alguna fallase, el resto no se aplicarían. *No se deben definir
+transacciones dentro de las migraciones*
+
+## Tabla de versiones
+
+La versión de la última migración aplicada se almacena en la bases de datos en una
+tabla llamada db_versions (a no ser que se especifique otro nombre), junto a la
+fecha en la que se ha aplicado la versión. Por defecto se usará la ultima versión
+registrada, pero se puede sobrescribir desde los parámetros si se hubiesen hecho
+cambios manuales.
+
+## Parámetros
+
+> Toda la información también se encuentra usando el parámetro --help
+
+```
+      --help          Show help                                        [boolean]
+      --version       Show version number                              [boolean]
+  -t, --target        Versión objetivo de la migracion                  [string]
+  -e, --env           Path del archivo .env con los datos de la BDD     [string]
+  -m, --migrations    Path del directorio de migrations                 [string]
+  -v, --versionTable  Nombre de la tabla donde se almacenan las versiones de la
+                      BDD, por defecto 'db_versions'
+                                               [string] [default: "db_versions"]
+  -b, --baseVersion   Versión a partir de la cual se aplican las migraciones
+                      independientemente de la almacenada en BDD        [string]
+```
+
+## Variables de entrono
+
+Para establecer la conexión con postgres se leen las siguientes variables de entorno
+por defecto deberían ser PG_DATABASE, PG_HOST... pero por compatibilidad con el
+proyecto anterior las mantengo así. En el futuro igual migro a las nativas.
+
+``` env
+POSTGRES_DATABASE=
+POSTGRES_HOST=
+POSTGRES_PORT=
+POSTGRES_USER=
+POSTGRES_PASSWORD=
+```