Ligar bases de dados

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.

#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).

#A partir do painel Dados

1. Abre o separador Dados da barra lateral.
2. 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."
3. Preenche o Nome interno e escolhe o Tipo.
4. Preenche os campos de ligação do tipo escolhido.
5. 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.
6. 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

1. Abre a página Datasources e carrega em Adicionar datasource.
2. 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).
3. Preenche, testa com Testar ligação, e carrega em Criar.
4. Voltas à lista, com a confirmação "Datasource criado.".

#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:

1. No painel Dados, abre o menu ⋯ do datasource e escolhe Editar ligação.
2. 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.
3. Altera o que precisares, carrega em Testar ligação para confirmar, e depois em Gravar. A confirmação é "Ligação gravada.".

#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.

#Eliminar um datasource

1. Na página Datasources, carrega no ícone do caixote na linha do datasource — ou, no painel Dados, abre o menu ⋯ e escolhe Eliminar datasource.
2. 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.
3. 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)

#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 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 :nomeDoArg e 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."