🗄️ Schema do banco

O User é a raiz do grafo. Tudo (contas sociais, posts, mídia) pertence a um usuário. Use uuid como id — IDs sequenciais expõem volume de cadastros e facilitam enumeração. O email precisa de @unique e o passwordHash nunca é exposto na API — só o servidor lê.

Antes de escrever modelos, declare o datasource e o generator. O Prisma só sabe gerar o client se essa configuração existir no topo do schema.prisma.

// prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id           String   @id @default(uuid())
  email        String   @unique
  passwordHash String
  name         String?
  createdAt    DateTime @default(now())
  updatedAt    DateTime @updatedAt

  socialAccounts SocialAccount[]
  posts          Post[]
  media          Media[]

  @@index([createdAt])
}

Conceitos-chave

Cada usuário conecta N contas — Twitter, LinkedIn, Instagram. O SocialAccount guarda o token OAuth de cada uma. Os campos accessToken e refreshToken são criptografados em repouso (AES-GCM com chave fora do banco) antes do INSERT — o Prisma só vê o ciphertext.

Use enum Platform em vez de string livre. Enum previne typo ("twiter" vs "twitter") e dá autocomplete no client gerado.

enum Platform {
  TWITTER
  LINKEDIN
  INSTAGRAM
  FACEBOOK
  THREADS
  BLUESKY
}

model SocialAccount {
  id           String   @id @default(uuid())
  userId       String
  platform     Platform
  handle       String
  accessToken  String   // ciphertext AES-GCM
  refreshToken String?  // ciphertext AES-GCM
  expiresAt    DateTime?
  scope        String?
  createdAt    DateTime @default(now())
  updatedAt    DateTime @updatedAt

  user    User         @relation(fields: [userId], references: [id], onDelete: Cascade)
  targets PostTarget[]

  @@unique([userId, platform, handle])
  @@index([userId])
  @@index([expiresAt])
}

Conceitos-chave

O Post é o conteúdo na visão do usuário — não na visão da rede. Um único Post pode disparar publicações em várias plataformas (isso é o PostTarget, próximo tópico). O campo mediaUrls é String[] nativo do Postgres — array é mais barato que tabela de junção quando só importa ordem.

O status é um enum de máquina de estado: DRAFT → SCHEDULED → PUBLISHING → PUBLISHED, com FAILED como ramo de erro. scheduledAt indexado é o que o worker lê a cada minuto.

enum PostStatus {
  DRAFT
  SCHEDULED
  PUBLISHING
  PUBLISHED
  FAILED
  CANCELLED
}

model Post {
  id          String     @id @default(uuid())
  userId      String
  text        String     @db.Text
  mediaUrls   String[]
  scheduledAt DateTime?
  publishedAt DateTime?
  status      PostStatus @default(DRAFT)
  createdAt   DateTime   @default(now())
  updatedAt   DateTime   @updatedAt

  user    User         @relation(fields: [userId], references: [id], onDelete: Cascade)
  targets PostTarget[]

  @@index([userId, status])
  @@index([scheduledAt])
}

Conceitos-chave

Esse é o modelo que separa amador de produção. Um Post dispara N publicações reais — uma por rede. Cada PostTarget tem seu próprio status, sua mensagem de erro e o platformPostId retornado pela API da rede.

Sem essa tabela, falha no Twitter cascateia para o LinkedIn no log do mesmo Post — e fica impossível fazer retry seletivo. 1 Post → N PostTarget é o jeito certo.

enum TargetStatus {
  PENDING
  PUBLISHING
  PUBLISHED
  FAILED
  SKIPPED
}

model PostTarget {
  id              String       @id @default(uuid())
  postId          String
  socialAccountId String
  status          TargetStatus @default(PENDING)
  platformPostId  String?      // id retornado pela rede (ex.: tweet id)
  platformUrl     String?      // URL pública do post na rede
  error           String?      @db.Text
  attempts        Int          @default(0)
  lastAttemptAt   DateTime?
  publishedAt     DateTime?

  post          Post          @relation(fields: [postId], references: [id], onDelete: Cascade)
  socialAccount SocialAccount @relation(fields: [socialAccountId], references: [id], onDelete: Cascade)

  @@unique([postId, socialAccountId])
  @@index([status])
  @@index([postId])
}

Conceitos-chave

Imagens e vídeos não vão no banco. Vão para S3 (ou R2/Spaces) e o banco guarda só a url, o mimeType e o size. Persistir bytes de mídia no Postgres custa caro: backup explode, MVCC sofre, vacuum trava.

O Media aqui é o registro do upload feito pelo usuário. O Post.mediaUrls referencia essas URLs, mas não há FK — o usuário pode anexar a mesma mídia em N posts e excluir o Post sem perder a Media.

model Media {
  id        String   @id @default(uuid())
  userId    String
  url       String   // s3://bucket/uploads/uuid.jpg ou https://cdn.../...
  key       String   // chave S3 — usar para delete
  mimeType  String   // image/jpeg, video/mp4, image/png
  size      Int      // bytes
  width     Int?
  height    Int?
  duration  Int?     // segundos, só vídeo
  createdAt DateTime @default(now())

  user User @relation(fields: [userId], references: [id], onDelete: Cascade)

  @@index([userId, createdAt])
  @@index([key])
}

Conceitos-chave

Schema escrito não vira tabela sozinho. prisma migrate gera SQL versionado em prisma/migrations/ — arquivos que você commita e que rodam idênticos em dev, staging e produção.

npx prisma migrate dev --name init

npx prisma migrate dev --name add_post_scheduled_index

npx prisma migrate deploy

npx prisma migrate reset

npx prisma migrate status

npx prisma studio

# Fluxo típico após editar schema.prisma
npx prisma format                    # arruma indentação
npx prisma validate                  # checa sintaxe
npx prisma migrate dev --name xxx    # gera SQL + aplica
git add prisma/migrations/ prisma/schema.prisma
git commit -m "feat(db): xxx"

# No CI/CD da produção (no entrypoint do container)
npx prisma migrate deploy
npx prisma generate

Conceitos-chave