Tabelas e campos

Antes de haver ecrãs há dados: as tabelas onde a aplicação guarda contas, contactos, encomendas ou pedidos de férias. No Keplin esses dados vivem numa base de dados ligada à app (um datasource) e são descritos num modelo — o desenho de tabelas, campos, chaves e relações que todo o resto da plataforma lê.

Esta página é sobre a primeira metade desse trabalho: criar e alterar tabelas, escolher tipos, definir chaves e índices. As relações e os campos enumerados têm página própria em Relações e enums.

Os exemplos são da app Gestão de Clientes: um CRM com três tabelas — contas, contactos e oportunidades.

#Duas camadas: a base de dados e o modelo

Vale a pena separar desde já duas coisas que se parecem:

Camada	O que é	Quem a usa
A base de dados	As tabelas, colunas e índices que existem mesmo no motor ligado à app.	O motor de base de dados. Alterá-la é executar comandos reais.
O modelo	A descrição dessas tabelas para a plataforma: entidades, campos, nomes amigáveis, descrições, relações e enums.	As APIs, os ecrãs, os scripts e os relatórios.

Uma tabela só entra no modelo quando a importas — e sair do modelo não apaga nada na base de dados. É por isso que a plataforma distingue sempre Remover do modelo de Eliminar.

#Abrir o modelo

1. Abre a app e escolhe o separador Dados na barra lateral.
2. Em Fontes de dados, clica no nome do datasource — na Gestão de Clientes, Dados CRM.
3. Abre um separador com o diagrama do modelo ao centro, a consola SQL em baixo, e a árvore de objectos do datasource expandida na barra lateral.

O diagrama arrasta-se com o rato; os botões no canto inferior esquerdo fazem zoom e enquadram tudo. A posição de cada entidade fica guardada — arrumas o diagrama uma vez e é assim que ele volta a abrir.

#A árvore de objectos

Debaixo do datasource, a árvore mostra o que existe na base de dados, agrupado e com a contagem de cada grupo:

Grupo	O que lista
Tabelas	As tabelas do motor. Cada uma tem menu próprio (⋯).
Vistas	As vistas (consultas guardadas com nome).
Programação	Funções / Procedimentos e Triggers — ver Triggers.

A caixa Procurar em tudo… no topo da barra lateral filtra a árvore; com pesquisa activa os grupos abrem-se sozinhos e um grupo sem resultados desaparece.

#Criar uma tabela

1. Passa o rato pelo datasource e abre o menu ⋯ (Acções de …).
2. Escolhe Nova tabela.
3. Preenche o Nome da tabela — é o nome que fica na base de dados (minúsculas e underscore poupam-te dores de cabeça: actividades, linhas_encomenda).
4. Schema (opcional) só interessa em motores com schemas; deixa vazio se não usas.
5. Em Descrição da tabela, escreve para que serve. Não é decoração: esta descrição acompanha a tabela na plataforma e é o que explica a tabela a quem lá chegar depois de ti.
6. Define as colunas (a seguir) e confirma com Criar tabela.

#As colunas

O painel esquerdo do diálogo é a lista de colunas (Colunas (N)) e o botão + acrescenta uma. Clica numa coluna da lista para a editar à direita.

A tabela começa sempre com uma coluna id, do tipo integer, com Chave primária (PK) e Auto-incremento ligados — o arranque que serve 9 em cada 10 tabelas.

Campo	O que faz
Nome	O nome da coluna na base de dados.
Tipo	O tipo lógico da coluna (lista completa abaixo).
Tamanho	Só em text e char — quantos caracteres cabem.
Precisão · Escala	Só em decimal — total de dígitos e quantos ficam à direita da vírgula (18 · 2 para dinheiro).
Itens do enum	Só em enum — ver Relações e enums.
Permite NULL	Se a coluna aceita ficar vazia. Desligado, a base de dados recusa registos sem valor.
Chave primária (PK)	Identifica o registo de forma única.
Auto-incremento	O motor gera o valor a cada inserção.
Descrição	Para que serve esta coluna.

O caixote do lixo que aparece ao passar o rato sobre uma coluna da lista remove-a (numa tabela nova, sai logo da lista).

#Os tipos de coluna

Os tipos são lógicos: descreves o que a coluna guarda e a plataforma traduz para o tipo certo do motor ligado. O mesmo desenho serve qualquer base de dados suportada.

Tipo	Para quê
text	Texto de comprimento variável — nomes, descrições, notas.
char	Texto de comprimento fixo — códigos de país, siglas.
integer	Números inteiros. O tipo natural de um id.
smallint	Inteiros pequenos.
bigint	Inteiros grandes — contadores, identificadores externos.
decimal	Números exactos com casas decimais. É o tipo do dinheiro.
float	Números aproximados — medições, percentagens científicas.
boolean	Sim/Não.
date	Uma data, sem horas.
time	Uma hora, sem data.
datetime	Data e hora.
uuid	Identificadores universais.
json	Estruturas livres guardadas como texto estruturado.
binary	Conteúdo binário.
enum	Um conjunto fechado de valores, definido ali mesmo — ver Relações e enums.

#Chaves primárias

A Chave primária (PK) é o que identifica um registo. Não é opcional na prática: sem PK, uma tabela pode ser lida mas não pode ser editada nem apagada a partir dos ecrãs — a Tabela avisa O datastore precisa de uma chave primária, e o Kanban desliga o arrasto. Se a chave é composta por mais do que uma coluna, liga Chave primária (PK) em cada uma.

O Auto-incremento entrega ao motor o trabalho de numerar. Só faz sentido em colunas inteiras.

#Trazer uma tabela para o modelo

Uma tabela que já exista na base de dados (criada por ti aqui, ou que já lá estava antes) tem de entrar no modelo para as APIs e os ecrãs a verem. Há dois caminhos, e dão no mesmo:

• Arrastar a tabela da árvore para o diagrama — cai no sítio onde a largares.
• Abrir o menu ⋯ da tabela e escolher Importar p/ modelo.

A plataforma lê a estrutura da tabela e cria a entidade: um nome em maiúscula inicial (contas → Contas), os campos, as chaves e as relações que encontrar declaradas na base de dados.

#O cartão de uma entidade

Cada entidade é um cartão no diagrama:

• O nome da entidade no cabeçalho, e dois botões: Localizar na árvore (marca a tabela correspondente na barra lateral) e Remover do modelo.
• Um campo por linha, com o nome à esquerda e o tipo à direita. A marca PK assinala a chave primária, e um ! depois do tipo significa que o campo não aceita vazio.
• Campos enumerados aparecem em itálico, com o nome do enum em vez do tipo.
• Com muitos campos, o cartão encolhe e oferece Mostrar mais N campos / Mostrar menos.
• No fundo, a secção Navegação lista os caminhos para as entidades relacionadas — assunto de Relações e enums.

#Alterar uma tabela

O menu ⋯ de uma tabela → Editar estrutura abre o editor da estrutura, com dois separadores: Colunas e Índices (N).

No topo estão as três coisas que descrevem a tabela:

Campo	O que é
Nome na BD	O nome real da tabela.
Nome amigável (apps)	O nome por que a tabela é conhecida na app.
Descrição da tabela	Para que serve.

O Nome amigável (apps) é a ponte entre uma base de dados que herdaste e uma app legível: a coluna pode chamar-se cli_nm_fis na base de dados e nome na app. Também existe por coluna — e é o nome amigável que aparece nas APIs, nos datastores e nos ecrãs.

#Mexer nas colunas

Clica numa coluna da lista da esquerda para a editar. As alterações não são imediatas: acumulam-se e só acontecem quando carregas em Aplicar alterações.

• Uma coluna acrescentada com + aparece marcada como nova e traz a nota Coluna nova — é criada ao aplicar as alterações.
• Apagar uma coluna existente (o caixote no fim da linha) risca-a e mostra Marcada para eliminar (DROP) ao aplicar; Anular desfaz.
• Se não houver nada para aplicar, a plataforma diz Sem alterações.

#Índices

O separador Índices (N) lista os índices da tabela — nome, marca unique e as colunas — e permite criar e eliminar.

Para criar um índice:

1. Escreve o nome (a convenção ix_alguma_coisa é boa e é a que o campo sugere).
2. Marca unique se o índice também serve para impedir valores repetidos — é assim que se garante que não há dois clientes com o mesmo NIF.
3. Clica nas colunas que fazem parte do índice (a ordem em que clicas é a ordem do índice).
4. Criar índice.

Uma tabela sem índices próprios diz Sem índices (além da PK) — a chave primária já é um índice, não precisa de ser criada.

#Ver os dados

O menu ⋯ de uma tabela → Ver dados abre a consola SQL em baixo, já com a consulta feita e o resultado à vista. É a forma rápida de confirmar o que lá está sem sair do modelo.

A consola também aceita SQL escrito por ti: escreve à esquerda, Executar, e o resultado aparece à direita com a contagem de linhas. A barra que separa a consola do diagrama arrasta-se, e a seta no canto recolhe-a.

#Apagar uma tabela

O menu ⋯ de uma tabela tem Eliminar, com confirmação: Esta operação é permanente e remove o objeto da base de dados. Não confundir com Remover do modelo, que só tira a entidade da descrição da app.

#Porque não…?

• Porque não vejo a minha tabela nas APIs? Provavelmente ainda não está no modelo. Arrasta-a da árvore para o diagrama, ou usa Importar p/ modelo.
• Porque criei uma coluna e ela não aparece? Confirma que carregaste em Aplicar alterações — no editor de estrutura, nada acontece antes disso.
• Porque é que a minha tabela nova não deixa editar registos nos ecrãs? Falta a Chave primária (PK). Sem ela, os ecrãs só sabem ler.
• Porque não consigo mudar o tipo de uma coluna? Há motores sem "alterar coluna". A plataforma avisa-te e o caminho é coluna nova → copiar dados → apagar a velha.
• Porque é que o nome do campo na app não é o da base de dados? Está definido o Nome amigável (apps) dessa coluna. É de propósito — e edita-se no mesmo sítio.
• Porque desapareceu a entidade do diagrama mas a tabela continua na árvore? Foi removida do modelo. Arrasta-a outra vez da árvore para o diagrama.