Carno.js CLI

The CLI (Command Line Interface) for Carno.js.

Instalação

To install, you can use npm or bun:

bun install @carnojs/cli

Uso

Você pode usar a CLI com npx ou bunx.

Gerar uma nova migração

Para gerar uma nova migração, use o comando

bunx cli migration:generate

Isso irá gerar um novo arquivo de migração com apenas as diferenças desde a última migration.

Partial indexes (Postgres) definidos nas entidades também são gerados automaticamente no SQL de migration. Em MySQL, predicates em índices não são suportados.

Sistema de Snapshot

O CLI mantém um arquivo schema-snapshot.json no diretório de migrations que armazena o estado atual do schema. Isso garante que:

• Apenas as mudanças desde a última migration sejam geradas
• Não há regeneração de queries já executadas
• O histórico de mudanças é mantido de forma incremental

O snapshot é atualizado automaticamente após cada migration gerada.

Executar todas as migrações pendentes

Para executar todas as migrações pendentes, use o comando

bunx cli migration:run

Exemplo de Fluxo de Trabalho

# 1. Defina suas entidades
# src/entities/user.entity.ts
@Entity()
class User extends BaseEntity {
  @PrimaryKey()
  id: number;
  
  @Property()
  email: string;
}

# 2. Gere a primeira migration
bunx cli migration:generate
# Cria: database/migrations/migration_20231021120000.sql
# Cria: database/migrations/schema-snapshot.json

# 3. Execute a migration
bunx cli migration:run

# 4. Adicione uma nova coluna
@Entity()
class User extends BaseEntity {
  @PrimaryKey()
  id: number;
  
  @Property()
  email: string;
  
  @Property()
  password: string;  // Nova coluna
}

# 5. Gere apenas o diff
bunx cli migration:generate
# Cria: database/migrations/migration_20231021120100.sql
# Atualiza: database/migrations/schema-snapshot.json
# Contém apenas: ALTER TABLE user ADD COLUMN password...

# 6. Execute a nova migration
bunx cli migration:run

Troubleshooting

Erro: "undefined is not an object (evaluating 'bdCol.type.includes')"

Este erro ocorre quando o snapshot está corrompido ou incompleto. O CLI agora detecta e limpa automaticamente snapshots corrompidos. Se o problema persistir:

1. Delete o arquivo schema-snapshot.json do diretório de migrations
2. Execute bunx carno migration:generate novamente
3. O snapshot será recriado do zero

Snapshot Corrompido

Se você suspeita que o snapshot está corrompido (colunas duplicadas, colunas sem type, etc.):

# Opção 1: Deixe o CLI limpar automaticamente
bunx carno migration:generate

# Opção 2: Delete e recrie manualmente
rm src/migrations/schema-snapshot.json
bunx carno migration:generate

O CLI agora gera snapshots corretamente:

• ✅ Cada tabela tem apenas suas próprias colunas
• ✅ Não há duplicação de colunas entre tabelas
• ✅ Não há warnings desnecessários
• ✅ Migrations são geradas apenas quando há mudanças reais

Contribuição

Contribuições são bem-vindas. Por favor, abra um problema ou faça um pull request com suas mudanças.