Motivação

LinConEs nasceu da necessidade de uma linguagem de consulta em português. No entanto, escrever código de produção diretamente com uma linguagem de consulta pode ocasionar uma série de problemas, como por exemplo ataques por SQL Injection, uma técnica bem conhecida em que uma consulta pode ser forjada para executar operações não desejadas pelos desenvolvedores originais.

Entidades é uma biblioteca para Delégua que trabalha com estruturas de manipulação de dados em alto nível, e que torna possível uma série de funcionalidades, como por exemplo:

• Gerar código em linguagem de consulta de maneira segura, a partir de classes e objetos em Delégua, observando parâmetros e impedindo a injeção de outras consultas indesejadas nas operações da sua aplicação;
• Trabalhar de maneira agnóstica, não importando qual tecnologia de dados esteja sendo usada, seja a própria memória do servidor, um banco de dados, etc.

Essa biblioteca usa uma outra biblioteca chamada lincones-js, onde uma lógica menos especializada é implementada para ler sentenças escritas em LinConEs e traduzi-las para SQL. Como um passo intermediário dessa tradução, há a geração de objetos de alto nível que representam comandos a serem executados em SQL. Esta biblioteca, portanto, utiliza código Delégua para também gerar esses objetos de operações de bancos de dados de alto nível, que então são utilizados por bibliotecas especializadas em uma ou outra tecnologia para a geração do SQL final.

Inspiração

• Active Record (Ruby on Rails);
• SQLAlchemy (Python)
• Entity Framework (.NET)

Utilização

Esta biblioteca funciona por si só apenas com Delégua, mas seu maior proveito ocorre com a utilização de outras bibliotecas, usadas para escrever diversas aplicações, como sistemas Web usando Líquido. Ao usar apenas por si só, toda a geração de sentenças pode ser feita ou em LinConEs, ou em SQL ANSI. Ao ser combinadas com outras bibliotecas, pode ser usada na geração de SQL mais direcionado, como por exemplo para SQLite ou PostgreSQL.

O ponto de entrada dessa biblioteca é uma classe chamada ContextoEntidades. Esta classe contém uma série do que chamamos de coleções de dados. Cada coleção é mapeada ou como uma collection de documentos ou registros (por exemplo, se usamos NoSQL), ou como uma tabela de banco de dados (quando o banco de dados é relacional). É cada uma dessas classes de coleções que geram as sentenças que as bibliotecas tecnológicas utilizam.

Para melhor ilustrar este funcionamento, vamos supor uma tabela de banco de dados de artigos. Cada artigo possui um identificador (abreviado como id), um título (texto) e um conteúdo (também texto). Em Delégua, cada linha desta tabela pode ser mapeada como a seguinte classe:

classe Artigo {
  id: numero
  titulo: texto
  conteudo: texto
}

Se queremos selecionar todos os artigos dessa classe e imprimi-los usando apenass Delégua, podemos fazê-lo da seguinte forma:

const entidades = importar('entidades')
const contexto = entidades.Contexto()
const artigos = contexto.colecao(Artigo).todos()
escreva(artigos) // Imprime a lista de todos os artigos encontrados.

Colunas computadas

Colunas computadas podem ser declaradas com o decorador @computada, informando a expressao SQL e se a coluna e persistida:

classe Pedido {
  id: numero
  quantidade: numero
  preco: numero

  @computada({ expressao: "quantidade * preco", persistida: verdadeiro })
  total: numero
}

Colunas computadas nao sao incluídas em inserts/updates, mas podem ser lidas normalmente nas consultas.

Comandos

Entidades conta com alguns comandos de seleção e manipulação de dados:

• contexto.colecao(Modelo).todos()
• contexto.colecao(Modelo).obterPorId()
• contexto.colecao(Modelo).obterPorCondicao()

Há também comandos de geração de SQL, se for interessante obter a consulta gerada antes da execução:

• contexto.modelo(Modelo).gerarSQLSelecionar()

Configuração em tempo de execução

A classe Configuracoes permite ajustar os parâmetros de conexão com o banco de dados diretamente no código Delégua, sem precisar editar o arquivo configuracao.delprops.

var configuracoes = entidades.Configuracoes()
configuracoes.caminho = "dados/meu-banco.db"
configuracoes.aplicar()

var contexto = entidades.Contexto() // Contexto agora usa o banco de dados configurado

Para bancos de dados em servidor:

var configuracoes = entidades.Configuracoes()
configuracoes.tecnologia = "postgresql"
configuracoes.host = "localhost"
configuracoes.porta = 5432
configuracoes.banco = "minha_base"
configuracoes.usuario = "postgres"
configuracoes.senha = "segredo"
configuracoes.aplicar()

var contexto = entidades.Contexto() // Contexto agora usa o banco de dados configurado

Propriedades disponíveis:

| Propriedade | Tipo | Descrição | |---------------|--------|-------------------------------------------------------| | caminho | texto | Caminho do arquivo de banco de dados (SQLite). | | porta | numero | Porta do servidor (PostgreSQL, MySQL). | | host | texto | Endereço do servidor de banco de dados. | | usuario | texto | Nome de usuário para autenticação. | | senha | texto | Senha para autenticação. | | banco | texto | Nome do banco de dados. | | tecnologia | texto | Tipo de banco: 'sqlite', 'postgresql', 'mysql'. |

Ordem de precedência na resolução da conexão:

Quando um Contexto é criado sem argumento explícito, a tecnologia é resolvida na seguinte ordem:

1. Configuracoes.aplicar() — configuração aplicada em memória (maior prioridade)
2. Arquivo configuracao.delprops no diretório de trabalho
3. SQLite padrão sem caminho (fallback)

Execução por linha de comando

Este pacote funciona sozinho em modo por linha de comando apenas com SQLite, que é o padrão deste projeto. Se houver necessidade de utilizar outro banco de dados, é necessário também instalar um dos pacotes específicos de tecnologia de LinConEs.