Do erro de módulo ao Bun-only: o guia real de troubleshooting do prisma no Linux

Recentemente, enfrentei uma sequência de barreiras ao inicializar, migrar e popular um banco de dados PostgreSQL usando Prisma em um ambiente Linux. O que parecia ser apenas uma execução rotineira de scripts se transformou em uma jornada de resolução de módulos, permissões, diferenças entre motores de execução e padronização para um ecossistema 100% focado em Bun.

Aqui está o relato prático sobre cada gargalo encontrado, a causa raiz no sistema operacional e como estruturei a solução definitiva.

1. O problema inicial: module not found "prisma/seed.ts"#

Tudo começou ao tentar executar o seeding do banco de dados com o comando tradicional do Prisma:

error: Module not found "prisma/seed.ts"

A causa raiz#

Ao invocar o comando prisma db seed, a CLI do Prisma consulta o package.json em busca da chave prisma.seed e dispara um processo filho para executar o script configurado.

Se o runner padrão de TypeScript (ts-node) tentar resolver o caminho sem levar em conta o diretório de trabalho atual (process.cwd()), a chamada de sistema (openat/stat) retorna ENOENT (No such file or directory).

Além disso, projetos configurados com ES Modules ("type": "module") ou arquivos tsconfig.json com rootDir restritivo quebram a transpilação em tempo de execução do ts-node.

A solução técnica#

Ajustar a declaração do runner para executores modernos ou apontar o caminho explícito resolve o problema de resolução:

"prisma": {
  "seed": "npx tsx ./prisma/seed.ts"
}

2. Preparando a base: criação do banco e permissões no PostgreSQL#

Antes de aplicar qualquer migração, precisei garantir a infraestrutura de dados no PostgreSQL via linha de comando. Existem duas formas de abordar isso:

Via utilitários do sistema operacional#

Ideais para scripts de provisionamento e automação:

# 1. Cria o usuario/role solicitando senha
sudo -u postgres createuser --interactive --pwprompt

# 2. Cria o banco associando a role como proprietaria (Owner)
sudo -u postgres createdb -O app_user app_db

Via prompt SQL (psql)#

Para controle granular de permissões e compatibilidade com versões mais recentes (PostgreSQL 15+):

-- Criacao do usuario com senha
CREATE USER app_user WITH PASSWORD 'sua_senha_segura';

-- Criacao do banco com encoding padrao UTF8
CREATE DATABASE app_db OWNER app_user;

-- Concessao de privilegios (no PostgreSQL 15+, o OWNER ja possui acesso pleno; caso delegue para outros usuarios, libere tambem o schema public):
GRANT ALL PRIVILEGES ON DATABASE app_db TO app_user;
GRANT ALL ON SCHEMA public TO app_user;

Atenção à autenticação (pg_hba.conf): Conexões locais via Unix Sockets usam o método peer por padrão no Linux (casando o UID do sistema operacional). Para conectar via TCP/IP (host) ou senhas da aplicação, o arquivo de configuração precisa aceitar scram-sha-256 ou md5, e o serviço deve estar escutando na porta padrão (ss -nltp | grep 5432).

3. O ciclo de comandos do prisma: dev, deploy e generate#

Com o banco ativo, o ciclo de vida do schema do Prisma se divide em três operações fundamentais:

1. Desenvolvimento com Shadow Database:

   npx prisma migrate dev --name init

Cria um banco auxiliar temporário (shadow DB) para aplicar o histórico de migrações em uma base limpa, detectar drift e verificar se o schema final resultante confere com as definições do schema.prisma.

1. Deploy em Produção:

   npx prisma migrate deploy

Apenas executa os arquivos SQL pendentes mapeados na tabela _prisma_migrations, sem necessidade de shadow DB.

1. Geração do Client e Binários:

   npx prisma generate

Compila os artefatos de tipo TypeScript e copia o Query Engine compilado em Rust para node_modules/.prisma/client.

4. O erro de localização: schema.prisma: file not found#

Ao tentar rodar a geração do cliente, recebi o seguinte erro:

set it as `prisma.schema` in your package.json,
or put it into the default location (`./prisma/schema.prisma`, or `./schema.prisma`).
Checked following paths:

schema.prisma: file not found
prisma/schema.prisma: file not found

O motor do Prisma realiza verificações no filesystem. Se o arquivo estiver com sensibilidade de caixa incorreta (como Schema.prisma no Linux) ou se o comando for disparado fora da raiz do projeto, a CLI aborta.

A solução foi consolidar o arquivo no diretório padrão:

mkdir -p prisma && mv schema.prisma prisma/schema.prisma

5. A fragmentação do ambiente: Bun, yarn e NPM conflitantes#

Ao trabalhar no servidor de aplicação, tentei rodar o comando usando o runtime Bun:

bun prisma generate --schema=./prisma/schema.prisma
# Erro: Script not found "prisma"

O Bun interpretou bun prisma como uma busca por um script chamado "prisma" no bloco "scripts" do package.json.

Ao tentar usar bunx, o Prisma acusou a falta do pacote do cliente:

Loaded Prisma config from prisma.config.ts.
Prisma schema loaded from prisma/schema.prisma.
Error: Could not resolve @prisma/client.
Please try to install it with yarn install @prisma/client and rerun npx "prisma generate".

E ao testar os comandos sugeridos:

yarn install @prisma/client
# bash: yarn: command not found

npx prisma generate
# bash: npx: command not found

O servidor não tinha yarn ou npm/npx disponíveis globalmente no $PATH, e as dependências estavam incompletas.

6. A decisão arquitetural: padronização 100% Bun#

Para eliminar a sobrecarga de ferramentas duplicadas e evitar inconsistências de pacotes entre gerenciadores, decidi padronizar a infraestrutura para usar apenas o Bun e o bunx.

Etapa 1: Limpeza de lockfiles e módulos antigos#

# Remove resquicios do NPM e Yarn
rm -f package-lock.json yarn.lock
rm -rf node_modules

# Instalacao limpa gerando o bun.lock (ou bun.lockb em versoes legadas)
bun install

# Adiciona explicitamente o cliente do Prisma
bun add @prisma/client

Etapa 2: Reestruturação do package.json#

Corrigi scripts com recursividade incorreta (como "dev": "bun run dev", que gerava loops infinitos) e aproveitei o sistema nativo de monitoramento de arquivos (inotify) do Bun:

{
  "name": "app-project",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "db:generate": "prisma generate --schema=./prisma/schema.prisma",
    "db:migrate": "prisma migrate dev --schema=./prisma/schema.prisma",
    "db:deploy": "prisma migrate deploy --schema=./prisma/schema.prisma",
    "db:seed": "prisma db seed",
    "app:dev": "bun --watch src/index.ts",
    "app:start": "bun run src/index.ts",
    "app:build": "echo 'No build step needed for Bun'"
  },
  "prisma": {
    "seed": "bun prisma/seed.ts"
  }
}

7. O conflito final: prisma.config.ts versus package.json#

Ao rodar finalmente o comando de seed:

bun run db:seed
# $ prisma db seed
# Loaded Prisma config from prisma.config.ts.
# ⚠️ No seed command configured
# To seed your database, add a seed property to the migrations section in your Prisma config file.

Por que isso aconteceu?#

O Prisma introduziu suporte ao arquivo de configuração programática prisma.config.ts. Quando esse arquivo está presente na raiz, a CLI ignora completamente o bloco "prisma": { "seed": "..." } do package.json e passa a exigir que o comando seja declarado dentro do arquivo .ts.

A solução#

Como toda a orquestração do runner já estava mapeada no package.json, o arquivo prisma.config.ts era redundante.

A remoção simplificou a cadeia de configuração:

rm prisma.config.ts

Após a exclusão, a CLI do Prisma voltou a ler diretamente o package.json, disparando o comando bun prisma/seed.ts. O Bun executou o TypeScript nativamente em memória, conectou ao PostgreSQL e concluiu a inserção dos dados sem depender de transpilações lentas de Node.js.

Conclusão: resumo dos comandos operacionais no ambiente Bun#

Para o dia a dia na infraestrutura, os comandos ficaram enxutos e diretos:

Ao alinhar os scripts com o executável correto e limpar arquivos de configuração conflitantes, a esteira de banco de dados passou a rodar de forma rápida, previsível e sem sobrecarga no servidor.

Veja também

Desenvolvimento Bun, Node.js e PM2 em produção: quando usar, quando evitar e trade-offs arquiteturais

Desenvolvimento Do Docker à produção: resolvendo a persistência e erros de runtime no "pé no barro

Infraestrutura Troubleshooting prisma studio no Linux: `spawn xdg-open ENOENT` - diagnóstico, correção e hardening de ambiente

Este post está licenciado sob CC BY-NC.