Módulo de base de dados

Instalação e configuração

Antes de qualquer etapa, leia Antes de começar e Noções básicas sobre terminal. Estas instruções presumem que você abriu o monorepo supastack completo no VS Code; sua raiz package.json marca a raiz do repositório. Nos comandos pnpm, um pacote de espaço de trabalho é um aplicativo ou uma pasta de código compartilhado; no produto, um espaço de trabalho é o contêiner de dados e o limite de segurança de uma equipe. corepack pnpm --filter ... seleciona um pacote do monorepo enquanto os comandos são executados a partir de sua raiz. Se você abriu apenas uma pasta móvel ou desktop sincronizada, ela não contém o back-end da Web, a configuração do Docker ou os scripts raiz: execute o back-end deste monorepo ou de um servidor hospedado acessível e use os próprios scripts da pasta da plataforma. Uma variável de ambiente é uma configuração nomeada armazenada em um arquivo .env local ou no painel de hospedagem; reinicie o aplicativo relevante após alterá-lo e mantenha os segredos do servidor fora dos valores NEXT_PUBLIC_ e EXPO_PUBLIC_.

1. Instale e inicie Docker Desktop.

2. Copie .env.example para .env na raiz para ferramentas de migração e para apps/web/.env.local para Next.js (PowerShell: Copy-Item .env.example .env; Copy-Item .env.example apps/web/.env.local. macOS/Linux/Git Bash: cp .env.example .env; cp .env.exemplo apps/web/.env.local). Mantenha DATABASE_URL igual em ambos os arquivos; o exemplo já corresponde ao banco de dados Docker local.

3. Na raiz do repositório, execute docker compose up -d postgres e docker compose ps; espere até que o postgres reporte saudável.

4. Execute corepack pnpm --filter @supastack/db db:migrate da raiz para aplicar as migrações já enviadas com o kit. Somente após editar packages/db/src/schema.ts, execute db:generate, inspecione o SQL gerado e execute db:migrate. Esperado: o contêiner Postgres local está íntegro e o aplicativo Web usa seu banco de dados migrado. Nunca aponte esta primeira execução para a produção.

Configura DATABASE_URL para a base Postgres alvo no ambiente de servidor. Usa uma base descartável separada para aceitação de integração. Nunca apontes migrações de teste para uma base de produção.

O workspace de base de dados exporta definições de esquema e helpers de persistência. Reveja packages/db/src/schema.ts e o diretório de migrações antes de introduzir uma tabela ou coluna.

docker compose up -d postgres
docker compose ps
corepack pnpm --filter @supastack/db db:migrate

# Only after changing packages/db/src/schema.ts:
corepack pnpm --filter @supastack/db db:generate
corepack pnpm --filter @supastack/db db:migrate

Comandos para copiar

Siga os comentários para ver em qual pasta um comando é executado. Se dois terminais estiverem rotulados, abra duas janelas de terminal e mantenha o primeiro comando em execução enquanto usa o segundo.

# Choose one copy method for your terminal:
# PowerShell:
Copy-Item .env.example .env
Copy-Item .env.example apps/web/.env.local

# macOS/Linux/Git Bash alternative:
# cp .env.example .env
# cp .env.example apps/web/.env.local

docker compose up -d postgres
docker compose ps
corepack pnpm --filter @supastack/db db:migrate

Fluxo de implementação

Gera uma migração depois de modificar o esquema, inspeciona o SQL gerado e committa-o com a alteração de esquema. Planeia como os registos existentes recebem valores antes de adicionar uma coluna obrigatória.

Inclui workspaceId em cada registo pertencente ao utilizador e transporta esse limite através de leituras e escritas. Usa histórico imutável de modelo-preço para contabilidade de IA em vez de reescrever preços referenciados por registos de utilização existentes.

Verificação e resolução de problemas

Se o Docker disser que não consegue se conectar ao seu mecanismo, inicie o Docker Desktop e espere que ele termine de carregar. Se o postgres não estiver íntegro, execute docker compose logs postgres da raiz e corrija esse erro antes de migrar. Se a Web disser que DATABASE_URL está faltando, verifique apps/web/.env.local; se db:migrate não puder se conectar, verifique o .env raiz. Se você alterar os bancos de dados, atualize ambos os arquivos. Leia a primeira instrução de migração com falha antes de tentar novamente; nunca repita isso contra a produção.

Aplica migrações numa base isolada e corre sobre ela os testes condicionados pela base. Credenciais em falta devem produzir uma porta explicitamente ignorada, não uma afirmação de persistência bem-sucedida. Se uma migração falhar, inspeciona que instrução falhou e o esquema atual antes de tentar de novo.