Ligar bases de dados
Registar uma base de dados como datasource da app, editar a ligação, renomear e eliminar — e onde essa ligação passa a ser usada.
Um datasource é uma base de dados registada numa app: uma ligação com nome, tipo e credenciais, que fica disponível para tudo o que nessa app precisa de dados reais — os passos SQL das APIs, os scripts, o modelo de dados (e, através dele, a API GraphQL e os ecrãs). A ligação regista-se uma vez; a partir daí toda a app se refere a ela pelo nome.
Na app de exemplo Gestão de Clientes, o datasource chama-se crm — uma
base PostgreSQL com as tabelas de contas, contactos e oportunidades. É ele
que vais ver em todas as figuras deste capítulo.
Nota
Os datasources são por app: cada app tem a sua lista, e uma ligação registada numa app não aparece nas outras. Se duas apps precisam da mesma base de dados, regista-se a ligação em cada uma.
Onde encontras os datasources
Há duas portas de entrada, e vais usar as duas:
- O painel Dados — na barra lateral do espaço de trabalho da app, separador Dados, secção Fontes de dados. É o sítio do dia-a-dia: cada datasource expande-se numa árvore com as tabelas, vistas e programação da base de dados, e o menu de cada um dá acesso a todas as acções.
- A página Datasources — a lista completa da app, com o tipo e a data de criação de cada ligação ("Bases de dados acessíveis às APIs e aos scripts desta app"). É também para aqui que apontam os atalhos da plataforma — por exemplo o link Adiciona o primeiro que aparece num passo SQL quando a app ainda não tem datasources. Em ecrãs pequenos, a navegação da app mostra Datasources directamente.


Criar um datasource
Vais precisar dos dados de ligação da base de dados: endereço do servidor, porto, nome da base, utilizador e password — os campos exactos variam com o tipo (a página Tipos suportados detalha cada um).
Interno ou externo
O modal de criação tem dois separadores, e a escolha decide o que te é pedido:
| Separador | Para quê | O que preenches |
|---|---|---|
| Interno | Uma base de dados criada e guardada pela plataforma para esta app. | Só o Nome interno e o motor: PostgreSQL (uma base nova no servidor da instalação, com credenciais só dela) ou SQLite (um ficheiro guardado com a app, com importação opcional de um ficheiro existente). |
| Externo | Uma base de dados que já existe, tua ou de outro sistema. | O tipo (PostgreSQL, MySQL, MariaDB, SQL Server ou Oracle) e os dados de ligação; o botão Testar ligação confirma antes de gravar. |
Numa base interna nunca vês nem escreves dados de ligação: a plataforma cria-a, guarda as credenciais cifradas e liga-se por ti. Se a opção PostgreSQL do separador Interno aparecer desactivada, o servidor PostgreSQL da instalação ainda não foi configurado; pede-o ao administrador da instalação.
A partir do painel Dados
- Abre o separador Dados da barra lateral.
- Na secção Fontes de dados, carrega no botão + (Novo datasource). Abre um modal — "Liga uma base de dados a esta app. Tudo é cifrado em repouso."
- Preenche o Nome interno e escolhe o Tipo.
- Preenche os campos de ligação do tipo escolhido.
- Carrega em Testar ligação e espera pelo "Ligação OK." — a página Testar a ligação e segurança explica o que o teste faz e como ler os erros.
- Carrega em Gravar. A árvore passa a mostrar o datasource, e o ecrã Modelo dele abre de seguida — pronto para importares tabelas.
A partir da página Datasources
- Abre a página Datasources e carrega em Adicionar datasource.
- Abre a página Novo datasource — "Regista as credenciais e testa a ligação antes de gravar. Tudo é cifrado em repouso." O formulário tem duas secções: Identificação (Nome interno e tipo de base de dados) e Ligação (credenciais e parâmetros de conexão).
- Preenche, testa com Testar ligação, e carrega em Criar.
- Voltas à lista, com a confirmação "Datasource criado.".

Dica
O caminho do modal é o mais curto quando estás a construir: ao gravar, o Modelo do datasource abre logo e podes continuar sem sair do espaço de trabalho.
O nome interno é a identidade
O Nome interno (ex.: warehouse-prod, ou crm no nosso exemplo) não é
um rótulo decorativo — é o identificador pelo qual as APIs e os scripts
chamam a ligação:
- Num script Python:
db("crm").query("select * from contas"). - Num passo SQL de uma API: o campo Datasource do passo lista os nomes registados.
Por isso:
| Regra | O que acontece se falhar |
|---|---|
| Único dentro da app | "Já existe um datasource com o nome … neste projecto." |
| Sem colisões com outro datasource | "O nome … colide com o datasource …" |
| Estável — muda-o só com intenção | Ver "Renomear um datasource" abaixo |
Editar a ligação
A base de dados mudou de servidor, de password, ou queres ligar o SSL:
- No painel Dados, abre o menu ⋯ do datasource e escolhe Editar ligação.
- O modal abre com tudo preenchido excepto a password — o campo passa a chamar-se Password (vazio = manter). Deixa-o em branco para manter a password actual; escreve para a substituir.
- Altera o que precisares, carrega em Testar ligação para confirmar, e depois em Gravar. A confirmação é "Ligação gravada.".

Nota
Na página Datasources, carregar no nome de um datasource abre o Modelo dele — a edição da ligação faz-se sempre pelo modal Editar ligação do painel Dados.
Nota
Num datasource interno (SQLite ou PostgreSQL da plataforma) o modal de edição só deixa mudar o Nome interno. Os dados de ligação são da plataforma, não se mostram nem se alteram, e não há Testar ligação; apenas o nome da base aparece, para a reconheceres.
Proteger a base: o acesso
O campo Acesso, ao criar ou editar um datasource, diz o que o Keplin pode fazer na base de dados:
| Acesso | Dados | Estrutura (tabelas, colunas, índices, triggers, chaves estrangeiras) |
|---|---|---|
| Leitura e escrita | Lêem-se e gravam-se | Altera-se |
| Estrutura protegida | Lêem-se e gravam-se | Não se altera |
| Só leitura | Só se lêem | Não se altera |
- Estrutura protegida serve para uma base que outro software também usa.
As APIs, os ecrãs e os scripts gravam dados, mas criar e alterar tabelas,
índices, triggers e relações físicas é recusado, tal como as instruções
CREATE,ALTEReDROPna consola SQL, nos passos SQL e nos scripts. - Só leitura serve para uma base cujos dados não se podem alterar por
engano. As APIs de tabela só lêem, e na consola SQL, nos passos SQL e nos
scripts só passam leituras (
SELECT). As chamadas a procedimentos (EXEC,CALL) também são recusadas. - Em qualquer acesso, o modelo da app continua livre: importar tabelas, entidades e relações lógicas não tocam na base.
- As mesmas regras valem para os agentes que trabalham pelo MCP.
- O painel Dados mostra uma marca ao lado do nome dos datasources protegidos.
Atenção
O acesso protege a base do lado do Keplin. A garantia total é dar ao Keplin um utilizador da base de dados com as permissões certas (por exemplo, só de leitura).
Renomear um datasource
Faz duplo clique no nome do datasource na árvore do painel Dados e escreve o novo nome (ou muda o Nome interno em Editar ligação). As tabelas já importadas para o modelo seguem o novo nome automaticamente.
Atenção
O que não é reescrito ao renomear: os passos SQL de APIs que escolheram
o datasource pelo nome antigo e as chamadas db("nome-antigo") nos
scripts. Depois de renomear, revê essas APIs e scripts — até lá, ficam a
apontar para um nome que já não existe e falham ao executar.
Eliminar um datasource
- Na página Datasources, carrega no ícone do caixote na linha do datasource — ou, no painel Dados, abre o menu ⋯ e escolhe Eliminar datasource.
- Lê a confirmação com atenção: "As APIs e os scripts que usam este datasource deixam de conseguir executar. Esta acção é permanente." Na árvore, o aviso acrescenta que o modelo associado sai também.
- Confirma em Eliminar datasource.
O que a eliminação remove — e o que não toca:
| Sai | Fica |
|---|---|
| A ligação registada (nome, tipo, credenciais) | A base de dados em si — nada é apagado no servidor de origem |
| As tabelas desse datasource no modelo da app | As APIs e scripts que o usavam (ficam a falhar até apontarem para outro datasource) |

Atenção
Num datasource do tipo SQLite, a base de dados vive com a app — ao eliminares o datasource estás a despedir-te desses dados. Nos restantes tipos, eliminar é só esquecer a ligação.
Atenção
O mesmo vale para um datasource interno PostgreSQL: a base de dados foi criada pela plataforma para este datasource e é apagada com ele, no servidor, com todos os dados. Por isso a confirmação pede que escrevas o nome do datasource. Num datasource externo, a tua base de dados fica exactamente onde está.
Onde a ligação é usada
Registar o datasource é o primeiro passo; o valor está no que ele desbloqueia:
A árvore de objectos — expande o datasource no painel Dados para veres Tabelas, Vistas e Programação (funções, procedimentos e triggers). Cada tabela tem Ver dados (abre a tabela num separador, onde os dados se vêem e alteram), Abrir na consola SQL (abre a consola com um select pronto) e Importar p/ modelo.
O modelo de dados — as tabelas importadas viram entidades do modelo, com relações e nomes amigáveis. É o modelo que alimenta a API GraphQL da app e os blocos Tabela das APIs. O capítulo do modelo de dados trata isto a fundo.
As APIs — num passo SQL, escolhe a base no campo Datasource e escreve a Query SQL. Os argumentos da API entram como
:nomeDoArge o resultado do passo anterior como:prev— "Os valores vão sempre parametrizados — nunca concatenados." Há um interruptor Devolver só a primeira linha para consultas de registo único.Os scripts — em Python, importa o acesso e consulta pelo nome:
from api_manager import db def main(input): contas = db("crm").query( "select id, nome from contas where cidade = $1", ["Lisboa"] ) return {"total": len(contas)}Os marcadores de parâmetros (
$1,?,:1, …) variam com o motor — a tabela está na página Tipos suportados.

Porque não vejo…?
- …o botão Adicionar datasource? Criar, editar e eliminar datasources é reservado a quem tem perfil de administrador na app. Com perfil de developer consultas a lista e usas os datasources, mas não mexes na ligação.
- …datasources no passo SQL da minha API? A app ainda não tem nenhum — o passo mostra "Esta app não tem datasources." com o link Adiciona o primeiro.
- …tabelas no bloco Tabela da API? O bloco Tabela lê do modelo, não do datasource directamente: "Importa tabelas no separador "Modelo" de um datasource primeiro."