@prisma-psm/core 1.0.5 → 1.0.6

package/README.en.md

@@ -0,0 +1,189 @@
+# PSM - Prisma Safe Migrate
+
+## Description
+
+**PSM (Prisma Safe Migrate)** is an advanced tool for generating and safely applying SQL migrations based on the Prisma model. Its main objective is to ensure that database changes are applied without risk of data loss, something that Prisma's standard migration system does not fully guarantee.
+
+---
+
+## Motivation
+
+Database migrations are critical processes that need to preserve the integrity of existing data. Prisma provides an efficient migration system, but it does not guarantee absolute data loss due to complex changes, such as renaming columns, changing data types, or dropping tables.
+
+PSM fills this gap by creating an extra layer of validation, strict revision control, and safe incremental application in production environments.
+
+---
+
+## Installation
+
+Install the PSM packages as development dependencies in your project:
+
+```bash
+npm install --save-dev @prisma-psm/core @prisma-psm/pg
+```
+
+---
+
+## Configuration
+
+In your `schema.prisma` file, configure the PSM generator to generate the SQL files and connect to the database:
+
+```prisma
+generator psm {
+provider = "psm generate"
+output = "./psm/"
+driver = "@prisma-psm/pg"
+url = env("DATABASE_URL")
+}
+```
+
+- **provider**: PSM generator that replaces Prisma's default migration generator.
+- **output**: directory where the SQL files and PSM artifacts will be generated. - **driver**: Database-specific driver (e.g., PostgreSQL).
+- **url**: Environment variable containing the database connection string.
+
+---
+
+## How it works - General flow
+
+### 1. Migration generation (`npx prisma generate`)
+
+- Generates Prisma artifacts normally.
+- Generates two main files in the `next` folder:
+- `migration.next.check.sql`: Script to validate whether the migration is consistent with the current database.
+- `migration.next.sql`: Script that will apply the changes.
+- If `DATABASE_URL` is configured:
+- Automatically executes the check script.
+- If successful: Keeps both files in the `next` folder.
+- If failed: Keeps only `migration.next.check.sql` and an error file, removing `migration.next.sql` if it exists. - If `DATABASE_URL` is not defined:
+- Only generates both files, without validating.
+- Updates the `psm.yml` file with migration information, such as status, driver, URL, schema, and history.
+
+### 2. Applying the migration (`psm commit`)
+
+- Validates the migration again by running `migration.next.check.sql`.
+- If validated:
+- Applies `migration.next.sql` to the database.
+- Generates a definitive revision in `revision/${timestamp}-${label}/` with:
+- Applied migration script.
+- Updated `psm.yml` file.
+- Registers the applied migration in the database for control.
+- If failure occurs, abort and display the error.
+
+### 3. Deploy to production (`psm deploy`)
+
+- Applies all pending revisions stored in the `revision/` folder incrementally. - Ensures the database is always synchronized with the migration history.
+
+---
+
+## Detailed Migration Engine
+
+PSM uses a temporary shadow schema to ensure data security:
+
+1. Creates a temporary schema `shadow_${random}`.
+2. Creates temporary tables for each Prisma model, without constraints (e.g., `temp_1_user` for the `user` model).
+3. Copies data from the real tables to the temporary tables.
+4. Applies constraints (keys, indexes, relationships) to the temporary tables.
+5. If everything passes during validation (check):
+- Removes the shadow schema and temporary tables.
+6. If everything passes during application (migrate next):
+- Removes the real tables.
+- Moves the temporary tables from the shadow schema to the final schema.
+- Renames the temporary tables to their real names.
+- Removes the shadow schema. - Records the applied migration in the database for control purposes.
+
+This process prevents direct destructive changes to the actual tables before full validation, preventing data loss.
+
+---
+
+## Generated file structure
+
+- **next/**
+- `migration.next.check.sql` — script to validate the migration.
+- `migration.next.sql` — script to apply the migration.
+- (optional) error file in case of failure.
+- **revision/${timestamp}-${label}/**
+- `migration.sql` — final migration script.
+- `psm.yml` — metadata and history of the applied migration.
+- **psm.yml**
+- Main file with status, configurations, history, and validation results.
+
+---
+
+## Environment Variable
+
+Configure the connection to your database in the `.env` file or in the environment:
+
+```env
+DATABASE_URL="postgresql://username:password@localhost:5432/yourbank"
+```
+
+---
+## Main Commands
+
+| Command | Description |
+|----------------------|------------------------------------------------------------------------|
+| `npx prisma generate` | Generates the migration files in the `next` folder and validates them (if `DATABASE_URL` is set). |
+| `psm commit` | Validates and applies the next migration. Creates the final revision in the `revision/` folder. |
+| `psm deploy` | Applies all pending migrations from the `revision/` folder in the correct order. |
+
+---
+
+## Usage Example
+
+```bash
+# Generate migration and validate (if DATABASE_URL is set)
+npx prisma generate
+
+# Validate and apply the generated migration
+psm commit
+
+# Apply all pending migrations in production
+psm deploy
+```
+
+---
+
+## Benefits
+
+- **Data loss guarantee** with strict validation. - Easy rollback and revision control.
+- Automatic validation during migration generation.
+- Detailed history of applied changes.
+- Initial support for PostgreSQL, with expansion options.
+
+---
+
+## Roadmap
+
+- Support for more databases (MySQL, SQLite, etc.).
+- Graphical interface for migration management.
+- Integration with CI/CD pipelines.
+- Manual and custom migrations.
+- Multi-schema and multi-tenant support.
+
+---
+
+## Contribution
+
+Contributions are welcome! Open issues for bugs or suggestions, and send pull requests for improvements.
+
+---
+
+## License
+
+Project licensed under [Apache 2.0](./LICENSE).
+
+---
+
+## Traduções
+
+[Português](./README.pt.md) | [English](./README.en.md)
+
+---
+
+## Contact
+
+For questions, suggestions, or support, open an issue or contact us via email.
+
+---
+
+**PSM - Safe and reliable migrations for your database with Prisma.**

package/README.md

@@ -1,23 +1,22 @@
-
 # PSM - Prisma Safe Migrate
 
-## Descrição
+## Description
 
-**PSM (Prisma Safe Migrate)** é uma ferramenta avançada para geração e aplicação segura de migrações SQL baseadas no modelo Prisma. Seu principal objetivo é garantir que alterações no banco de dados sejam aplicadas sem risco de perda de dados, algo que o sistema padrão de migrações do Prisma não assegura completamente.
+**PSM (Prisma Safe Migrate)** is an advanced tool for generating and safely applying SQL migrations based on the Prisma model. Its main objective is to ensure that database changes are applied without risk of data loss, something that Prisma's standard migration system does not fully guarantee.
 
 ---
 
-## Motivação
+## Motivation
 
-Migrações de banco de dados são processos críticos que precisam preservar a integridade e os dados existentes. O Prisma fornece um sistema eficiente para migrações, porém sem garantias absolutas contra perda de dados em alterações complexas, como renomear colunas, alterar tipos de dados ou remover tabelas.
+Database migrations are critical processes that need to preserve the integrity of existing data. Prisma provides an efficient migration system, but it does not guarantee absolute data loss due to complex changes, such as renaming columns, changing data types, or dropping tables.
 
-O PSM preenche essa lacuna ao criar uma camada extra de validação, controle rigoroso de revisões e aplicação incremental segura em ambientes de produção.
+PSM fills this gap by creating an extra layer of validation, strict revision control, and safe incremental application in production environments.
 
 ---
 
-## Instalação
+## Installation
 
-Instale os pacotes do PSM como dependências de desenvolvimento no seu projeto:
+Install the PSM packages as development dependencies in your project:
 
 ```bash
 npm install --save-dev @prisma-psm/core @prisma-psm/pg
@@ -25,166 +24,166 @@ npm install --save-dev @prisma-psm/core @prisma-psm/pg
 
 ---
 
-## Configuração
+## Configuration
 
-No seu arquivo `schema.prisma`, configure o gerador do PSM para gerar os arquivos SQL e conectar ao banco:
+In your `schema.prisma` file, configure the PSM generator to generate the SQL files and connect to the database:
 
 ```prisma
 generator psm {
-  provider = "psm migrate generate"
-  output   = "./psm/"
-  driver   = "@prisma-psm/pg"
-  url      = env("DATABASE_URL")
+provider = "psm generate"
+output = "./psm/"
+driver = "@prisma-psm/pg"
+url = env("DATABASE_URL")
 }
 ```
 
-- **provider**: gerador do PSM que substitui o padrão do Prisma para geração de migrações.
-- **output**: diretório onde serão gerados os arquivos SQL e artefatos do PSM.
-- **driver**: driver específico para o banco (exemplo: PostgreSQL).
-- **url**: variável de ambiente contendo a string de conexão ao banco.
+- **provider**: PSM generator that replaces Prisma's default migration generator.
+- **output**: directory where the SQL files and PSM artifacts will be generated. - **driver**: Database-specific driver (e.g., PostgreSQL).
+- **url**: Environment variable containing the database connection string.
 
 ---
 
-## Como funciona - Fluxo geral
+## How it works - General flow
 
-### 1. Geração da migração (`npx prisma generate`)
+### 1. Migration generation (`npx prisma generate`)
 
-- Gera os artefatos do Prisma normalmente.
-- Gera dois arquivos principais na pasta `next`:
-    - `migration.next.check.sql`: script para validar se a migração está consistente com o banco atual.
-    - `migration.next.sql`: script que aplicará as alterações.
-- Se `DATABASE_URL` estiver configurada:
-    - Executa automaticamente o script de check.
-    - Se sucesso: mantém os dois arquivos na pasta `next`.
-    - Se falha: mantém só `migration.next.check.sql` e um arquivo de erro, removendo `migration.next.sql` se existir.
-- Se `DATABASE_URL` não estiver definida:
-    - Apenas gera ambos os arquivos, sem validar.
-- Atualiza o arquivo `psm.yml` com informações da migração, como status, driver, URL, esquema, e histórico.
+- Generates Prisma artifacts normally.
+- Generates two main files in the `next` folder:
+- `migration.next.check.sql`: Script to validate whether the migration is consistent with the current database.
+- `migration.next.sql`: Script that will apply the changes.
+- If `DATABASE_URL` is configured:
+- Automatically executes the check script.
+- If successful: Keeps both files in the `next` folder.
+- If failed: Keeps only `migration.next.check.sql` and an error file, removing `migration.next.sql` if it exists. - If `DATABASE_URL` is not defined:
+- Only generates both files, without validating.
+- Updates the `psm.yml` file with migration information, such as status, driver, URL, schema, and history.
 
-### 2. Aplicação da migração (`psm migrate commit`)
+### 2. Applying the migration (`psm commit`)
 
-- Valida novamente a migração executando `migration.next.check.sql`.
-- Se validado:
-    - Aplica o `migration.next.sql` no banco.
-    - Gera uma revisão definitiva em `revision/${timestamp}-${label}/` com:
-        - Script da migração aplicada.
-        - Arquivo `psm.yml` atualizado.
-    - Registra no banco a migração aplicada para controle.
-- Se falha, aborta e mostra o erro.
+- Validates the migration again by running `migration.next.check.sql`.
+- If validated:
+- Applies `migration.next.sql` to the database.
+- Generates a definitive revision in `revision/${timestamp}-${label}/` with:
+- Applied migration script.
+- Updated `psm.yml` file.
+- Registers the applied migration in the database for control.
+- If failure occurs, abort and display the error.
 
-### 3. Deploy em produção (`psm migrate deploy`)
+### 3. Deploy to production (`psm deploy`)
 
-- Aplica todas as revisões pendentes armazenadas na pasta `revision/` de forma incremental.
-- Garante que o banco esteja sempre sincronizado com o histórico de migrações.
+- Applies all pending revisions stored in the `revision/` folder incrementally. - Ensures the database is always synchronized with the migration history.
 
 ---
 
-## Motor de migração (engine) detalhado
+## Detailed Migration Engine
 
-O PSM usa um esquema shadow temporário para garantir segurança dos dados:
+PSM uses a temporary shadow schema to ensure data security:
 
-1. Cria um schema temporário `shadow_${random}`.
-2. Cria tabelas temporárias para cada modelo Prisma, sem constraints (ex: `temp_1_user` para o modelo `user`).
-3. Copia os dados das tabelas reais para as temporárias.
-4. Aplica as constraints (chaves, índices, relacionamentos) nas tabelas temporárias.
-5. Se na validação (check) tudo passar:
-    - Remove o schema shadow e as tabelas temporárias.
-6. Se na aplicação (migrate next) tudo passar:
-    - Remove as tabelas reais.
-    - Move as tabelas temporárias do schema shadow para o schema final.
-    - Renomeia as tabelas temporárias para os nomes reais.
-    - Remove o schema shadow.
-    - Registra a migração aplicada no banco para controle.
+1. Creates a temporary schema `shadow_${random}`.
+2. Creates temporary tables for each Prisma model, without constraints (e.g., `temp_1_user` for the `user` model).
+3. Copies data from the real tables to the temporary tables.
+4. Applies constraints (keys, indexes, relationships) to the temporary tables.
+5. If everything passes during validation (check):
+- Removes the shadow schema and temporary tables.
+6. If everything passes during application (migrate next):
+- Removes the real tables.
+- Moves the temporary tables from the shadow schema to the final schema.
+- Renames the temporary tables to their real names.
+- Removes the shadow schema. - Records the applied migration in the database for control purposes.
 
-Esse processo impede alterações destrutivas diretas nas tabelas reais antes da validação completa, evitando perda de dados.
+This process prevents direct destructive changes to the actual tables before full validation, preventing data loss.
 
 ---
 
-## Estrutura de arquivos gerados
+## Generated file structure
 
 - **next/**
-    - `migration.next.check.sql` — script para validar a migração.
-    - `migration.next.sql` — script para aplicar a migração.
-    - (opcional) arquivo de erro em caso de falha.
+- `migration.next.check.sql` — script to validate the migration.
+- `migration.next.sql` — script to apply the migration.
+- (optional) error file in case of failure.
 - **revision/${timestamp}-${label}/**
-    - `migration.sql` — script definitivo da migração.
-    - `psm.yml` — metadados e histórico da migração aplicada.
+- `migration.sql` — final migration script.
+- `psm.yml` — metadata and history of the applied migration.
 - **psm.yml**
-    - Arquivo principal com estado, configurações, histórico e resultados das validações.
+- Main file with status, configurations, history, and validation results.
 
 ---
 
-## Variável de ambiente
+## Environment Variable
 
-Configure a conexão com seu banco no arquivo `.env` ou no ambiente:
+Configure the connection to your database in the `.env` file or in the environment:
 
 ```env
-DATABASE_URL="postgresql://usuario:senha@localhost:5432/seubanco"
+DATABASE_URL="postgresql://username:password@localhost:5432/yourbank"
 ```
 
 ---
+## Main Commands
 
-## Comandos principais
-
-| Comando               | Descrição                                                                                   |
-|-----------------------|---------------------------------------------------------------------------------------------|
-| `npx prisma generate` | Gera os arquivos de migração na pasta `next` e valida (se `DATABASE_URL` configurada).      |
-| `psm migrate commit`  | Valida e aplica a próxima migração. Cria revisão definitiva na pasta `revision/`.          |
-| `psm migrate deploy`  | Aplica todas as migrações pendentes da pasta `revision/` na ordem correta.                  |
+| Command | Description |
+|-----------------------|------------------------------------------------------------------------|
+| `npx prisma generate` | Generates the migration files in the `next` folder and validates them (if `DATABASE_URL` is set). |
+| `psm commit` | Validates and applies the next migration. Creates the final revision in the `revision/` folder. |
+| `psm deploy` | Applies all pending migrations from the `revision/` folder in the correct order. |
 
 ---
 
-## Exemplo de uso
+## Usage Example
 
 ```bash
-# Gerar migração e validar (se DATABASE_URL definida)
+# Generate migration and validate (if DATABASE_URL is set)
 npx prisma generate
 
-# Validar e aplicar a migração gerada
-psm migrate commit
+# Validate and apply the generated migration
+psm commit
 
-# Aplicar todas as migrações pendentes em produção
-psm migrate deploy
+# Apply all pending migrations in production
+psm deploy
 ```
 
 ---
 
-## Benefícios
+## Benefits
 
-- **Garantia contra perda de dados** com validação rigorosa.
-- **Rollback facilitado** e controle de revisões.
-- **Validação automática** durante geração de migrações.
-- **Histórico detalhado** das alterações aplicadas.
-- **Suporte inicial para PostgreSQL**, com possibilidade de expansão.
+- **Data loss guarantee** with strict validation. - Easy rollback and revision control.
+- Automatic validation during migration generation.
+- Detailed history of applied changes.
+- Initial support for PostgreSQL, with expansion options.
 
 ---
 
 ## Roadmap
 
-- Suporte a mais bancos (MySQL, SQLite, etc.).
-- Interface gráfica para gestão de migrações.
-- Integração com pipelines CI/CD.
-- Migrações manuais e customizadas.
-- Suporte multi-schema e multi-tenant.
+- Support for more databases (MySQL, SQLite, etc.).
+- Graphical interface for migration management.
+- Integration with CI/CD pipelines.
+- Manual and custom migrations.
+- Multi-schema and multi-tenant support.
+
+---
+
+## Contribution
+
+Contributions are welcome! Open issues for bugs or suggestions, and send pull requests for improvements.
 
 ---
 
-## Contribuição
+## License
 
-Contribuições são bem-vindas! Abra issues para bugs ou sugestões, e envie pull requests para melhorias.
+Project licensed under [Apache 2.0](./LICENSE).
 
 ---
 
-## Licença
+## Traduções
 
-Projeto licenciado sob a [Apache 2.0](./LICENSE).
+[Português](./README.pt.md) | [English](./README.en.md)
 
 ---
 
-## Contato
+## Contact
 
-Para dúvidas, sugestões ou suporte, abra uma issue ou entre em contato via email.
+For questions, suggestions, or support, open an issue or contact us via email.
 
 ---
 
-**PSM - Migrações seguras e confiáveis para seu banco de dados com Prisma.**
+**PSM - Safe and reliable migrations for your database with Prisma.**