# SurrealDB para vibe coding: do primeiro schema a um produto real > Um guia completo para sair do banco improvisado pela IA e criar uma base com schema, relações, permissões, migrações e operação preparada para usuários reais. **Autores:** Mauro Mequelussi **Publicado:** 2026-07-13T12:00:00.000Z **Atualizado:** 2026-07-20T15:00:48.230389352Z **Tags:** surrealql, vibe-coding, arquitetura, tutorial, banco-de-dados, surrealdb --- Vibe coding encurtou o caminho entre uma ideia e a primeira tela. O banco de dados continua sendo o lugar onde essa ideia vira — ou deixa de virar — um produto confiável. **SurrealDB** é um banco multi-modelo que reúne documentos, relações de grafo, consultas em tempo real, busca textual e vetorial em uma única plataforma. Para quem cria com IA, isso reduz a quantidade de serviços que o agente precisa conectar e dá ao projeto um modelo de dados explícito para seguir. Este guia mostra como começar sem transformar velocidade em dívida técnica. A meta não é apenas salvar um cadastro: é criar uma base que possa receber autenticação, permissões, pagamentos e usuários reais. ## O que é SurrealDB? SurrealDB é um banco de dados multi-modelo: o mesmo registro pode ter campos estruturados e objetos aninhados, apontar diretamente para outros registros e participar de relações com propriedades próprias. Tudo é consultado com **SurrealQL**, uma linguagem parecida com SQL, mas preparada para documentos e grafos. Na prática, isso permite começar com um único banco para vários problemas que normalmente pediriam Postgres, um banco de documentos, uma camada de tempo real e um serviço de vetores. | Necessidade do produto | Recurso no SurrealDB | | --- | --- | | Cadastros e transações | tabelas, campos, índices e transações | | Dados flexíveis | objetos e arrays dentro do registro | | Comunidade e recomendações | relações de grafo com `RELATE` | | Interfaces atualizadas | live queries e WebSocket | | Busca por significado | vetores e índices HNSW ou MTree | | Controle de acesso | autenticação e permissões no banco | Essa combinação não elimina arquitetura. Ela diminui a quantidade de peças, enquanto deixa mais visível o que o produto realmente precisa modelar. ## Por que ele combina com vibe coding? Uma IA produz código melhor quando encontra contratos claros. Se o banco aceita qualquer campo, qualquer formato e qualquer operação, o agente também tende a improvisar. Com tabelas `SCHEMAFULL`, tipos e regras de validação, o schema vira contexto executável: ele orienta a IA e rejeita dados que não respeitam o produto. ::callout{type="info" title="Flexível não significa sem schema"} Use a flexibilidade para modelar objetos e relações com naturalidade. Use `SCHEMAFULL`, tipos, índices e permissões para proteger tudo que já virou regra do negócio. :: ## Um primeiro schema que já nasce como produto Imagine um aplicativo brasileiro para profissionais autônomos organizarem clientes e serviços. O protótipo precisa cadastrar clientes; o produto precisa impedir e-mails inválidos, representar preços com precisão e saber quem contratou qual serviço. ::code-demo{language="surql" filename="database/schema.surql"} ```surql DEFINE TABLE cliente SCHEMAFULL; DEFINE FIELD nome ON cliente TYPE string; DEFINE FIELD email ON cliente TYPE string ASSERT string::is_email($value); DEFINE FIELD criado_em ON cliente TYPE datetime DEFAULT time::now(); DEFINE INDEX cliente_email ON cliente FIELDS email UNIQUE; DEFINE TABLE servico SCHEMAFULL; DEFINE FIELD nome ON servico TYPE string; DEFINE FIELD preco_centavos ON servico TYPE int ASSERT $value >= 0; DEFINE FIELD ativo ON servico TYPE bool DEFAULT true; DEFINE TABLE contratou SCHEMAFULL TYPE RELATION IN cliente OUT servico; DEFINE FIELD status ON contratou TYPE string ASSERT $value IN ['interessado', 'ativo', 'encerrado']; DEFINE FIELD contratado_em ON contratou TYPE datetime DEFAULT time::now(); DEFINE INDEX contratacao_unica ON contratou FIELDS in, out UNIQUE; ``` :: Há decisões de produto escondidas nesse exemplo. Dinheiro fica em centavos para evitar arredondamento de ponto flutuante. O e-mail é único. A contratação é uma relação que guarda estado e data. O índice na aresta impede o mesmo cliente de contratar o mesmo serviço duas vezes por acidente. ## Criando e consultando dados com SurrealQL Com o schema aplicado, podemos criar os registros e conectá-los: ::code-demo{language="surql" filename="database/primeiros-dados.surql"} ```surql CREATE cliente:ana CONTENT { nome: 'Ana Souza', email: 'ana@example.com' }; CREATE servico:mentoria CONTENT { nome: 'Mentoria de produto', preco_centavos: 35000 }; RELATE cliente:ana->contratou->servico:mentoria SET status = 'ativo'; SELECT nome, ->contratou.{ status, contratado_em, out.nome AS servico } FROM cliente:ana; ``` :: O ganho não está em escrever menos caracteres. Está em consultar uma pergunta do domínio — “quais serviços Ana contratou e qual é o estado de cada contratação?” — sem esconder o significado da relação numa tabela genérica. ::read-more{slug="surrealdb-para-vibe-coding" label="Continuar: do schema local à operação segura" placement="mid_content"} ## Local, Cloud ou servidor próprio? O modo de execução deve acompanhar o estágio e o risco do produto. | Estágio | Caminho sensato | Cuidado principal | | --- | --- | --- | | Aprendizado | Surrealist Sandbox ou instância local | sandbox não serve para medir desempenho | | Protótipo persistente | local com armazenamento em disco | backup e credenciais continuam necessários | | MVP público | SurrealDB Cloud ou single-node bem operado | TLS, backup, observabilidade e atualização | | Operação crítica | Cloud com alta disponibilidade ou cluster apropriado | custo, recuperação e tolerância a falhas | A [documentação oficial de deployment](https://surrealdb.com/docs/build/deployment) explica os modelos gerenciado, single-node, distribuído e embarcado. Para quem está lançando o primeiro produto, a melhor escolha costuma ser a que reduz operação sem esconder como os dados são protegidos. ## A fronteira correta entre navegador e banco SurrealDB permite autenticação e permissões detalhadas, mas isso não autoriza colocar uma credencial administrativa no front-end. O navegador deve receber apenas uma sessão limitada ao usuário. Operações internas — conciliação de pagamento, administração, importação e manutenção — ficam atrás de uma API ou de uma conexão de serviço protegida. Em um produto com dados pessoais, trate nome, telefone, endereço, documentos e histórico como informações que precisam de finalidade, retenção e acesso definidos. A LGPD não se resolve escolhendo um banco; ela exige que o produto saiba quais dados coleta, por que coleta e quem consegue lê-los. ::callout{type="warning" title="Nunca entregue root para a interface ou para um agente"} Crie usuários e acessos com o menor privilégio possível. Uma ferramenta de IA deve enxergar apenas o namespace, o banco e as operações necessárias para a tarefa atual. :: ## Use parâmetros, não concatenação Código gerado por IA frequentemente monta consultas juntando texto. Isso abre espaço para injeção e erros de tipo. Prefira variáveis vinculadas pelo SDK. ::code-demo{language="ts" filename="server/repositories/clientes.ts"} ```ts export async function buscarClientePorEmail(db: Surreal, email: string) { const [clientes] = await db.query( 'SELECT * FROM cliente WHERE email = $email LIMIT 1', { email }, ) return clientes?.[0] ?? null } ``` :: O banco recebe a consulta e os dados separadamente. Além de ser mais seguro, esse padrão deixa clara a fronteira entre código e entrada do usuário. ## Schema também precisa de versão Quando o projeto sai do protótipo, editar o banco manualmente deixa de ser aceitável. Guarde definições e mudanças no repositório, revise o plano antes de aplicar e teste a migração contra uma base descartável. O **SurrealKit** existe para organizar schema, rollouts, seeds e testes. A ferramenta não substitui revisão: uma remoção de campo, um novo índice único ou uma mudança de tipo pode falhar por causa dos dados que já existem. Um fluxo responsável tem cinco passos: 1. alterar o schema em arquivo; 2. gerar ou escrever a migração; 3. revisar operações destrutivas; 4. testar com dados representativos; 5. aplicar com backup e caminho de recuperação. ## O prompt que dá contexto sem dar poder demais Em vez de pedir “crie meu banco”, descreva o domínio e peça uma proposta revisável. ::prompt-snippet{title="Modelar um MVP no SurrealDB" model="Agente de código"} Você vai propor um schema SurrealDB para um MVP brasileiro de agenda de serviços. Entidades: profissional, cliente, servico e agendamento. Regras: - preços armazenados em centavos; - datas em datetime e timezone tratado pela aplicação; - um profissional só acessa seus próprios clientes; - um horário não pode ser reservado duas vezes; - cancelamentos precisam manter histórico. Entregue: 1. decisões de modelagem e riscos; 2. schema SurrealQL SCHEMAFULL; 3. índices e asserts; 4. permissões sugeridas; 5. cinco testes que devem falhar quando uma regra for violada. Não aplique nada e não use credenciais administrativas. :: Esse formato força o agente a explicar decisões antes de alterar dados. Também torna as regras verificáveis. ## Checklist antes de colocar usuários reais - schema versionado e reproduzível; - credenciais diferentes para desenvolvimento e produção; - nenhum segredo enviado ao navegador; - consultas parametrizadas; - permissões testadas com usuário comum, não apenas com root; - índices para unicidade e consultas frequentes; - política de backup e teste de restauração; - logs sem senhas, tokens ou dados pessoais desnecessários; - ambiente de staging ou base descartável para migrações; - monitoramento de erro e tempo de consulta. ## Perguntas frequentes sobre SurrealDB ### SurrealDB substitui Postgres? Não em todos os casos. Postgres continua excelente para domínios relacionais tradicionais e equipes que dependem de seu ecossistema maduro. SurrealDB faz mais sentido quando documentos, grafos, tempo real ou vetores reduzem a quantidade de sistemas do produto. Veja a análise completa em [SurrealDB vs Postgres](/blog/surrealdb-vs-postgres). ### Preciso saber SQL? Conhecer SQL ajuda porque SurrealQL mantém conceitos familiares como `SELECT`, `CREATE`, índices e transações. Você também precisará aprender record IDs, objetos, relações e travessias de grafo. ### Posso usar SurrealDB com Nuxt, React ou aplicativos mobile? Sim. Existem SDKs e APIs para diferentes runtimes. A decisão importante é onde cada conexão roda e quais permissões ela recebe, não o framework visual. ### SurrealDB é uma boa escolha para meu primeiro SaaS? Pode ser, principalmente quando as relações do domínio são centrais. Faça uma prova de conceito com as consultas mais importantes, autenticação e uma migração antes de assumir que qualquer banco atenderá todo o produto. ## O próximo passo Crie uma base pequena, mas completa: duas ou três entidades, uma relação importante, um índice de unicidade, uma regra de acesso e um teste que prova que a regra funciona. Depois conecte a interface. A IA pode escrever o primeiro rascunho em minutos. O produto nasce quando você consegue explicar o modelo, reproduzir o schema e impedir operações que nunca deveriam acontecer. **Do vibe ao produto. Com método.** ::