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.
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.
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:
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.
[ CONTEÚDO_INTEGRAL_DISPONÍVEL ]
Continuar: do schema local à operação segura CLIQUE PARA DESBLOQUEAR A LEITURA
Construindo aplicações robustas com arquitetura de alto nível e infraestrutura otimizada na edge do Cloudflare Workers com SurrealDB.
Segurança de dados e conformidade com privacidade desde o primeiro dia de código com tratamento de estados e sessões resilientes.
Métricas de performance para monitorar a experiência do usuário e otimizar custos operacionais em produção com dashboards estruturados.
Construindo aplicações robustas com arquitetura de alto nível e infraestrutura otimizada na edge do Cloudflare Workers com SurrealDB.
Segurança de dados e conformidade com privacidade desde o primeiro dia de código com tratamento de estados e sessões resilientes.
Métricas de performance para monitorar a experiência do usuário e otimizar custos operacionais em produção com dashboards estruturados.
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 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.
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.
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:
- alterar o schema em arquivo;
- gerar ou escrever a migração;
- revisar operações destrutivas;
- testar com dados representativos;
- 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.
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:
- decisões de modelagem e riscos;
- schema SurrealQL SCHEMAFULL;
- índices e asserts;
- permissões sugeridas;
- 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.
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.
