nginstack

Class: Database

@nginstack/engine/lib/database/Database~ Database

new Database(host, dbName)

Classe que representa o servidor de banco de dados.

Há uma variável global chamada database que representa o servidor de banco de dados da conexão corrente.

Parameters:
Name Type Description
host string | Connection

Endereço e porta do servidor de banco de dados no formato <IP ou Nome>:<Porta>, ou uma instância de Connection associada ao servidor que será conectado.
dbName string

Nome da base de dados.

Members

date :Date

Data/Hora em fuso local correspondente Data/Hora do banco de dados.

Type:
  • Date

dbName :string

Nome da base de dados.

Type:
  • string

dbType :string

Tipo da base de dados.

Pode ser retornado um dos seguintes valores: 'PGSQL', 'ORACLE' e 'MSSQL'.

Type:
  • string

protocol :string

Protocolo utilizado na comunicação com o Engine servidor. Valores possíveis: "http:" e "https:".

Type:
  • string

referrer :string

Informação enviada ao servidor para que o mesmo possa identificar nas estatísticas qual processo originou a requisição. Ela é automaticamente preenchida pelo sistema e normalmente não deve ser utilizada pelo desenvolvedor.

A alteração desta propriedade modificará também a mesma propriedade da instância de Connection informada na construção deste objeto, caso tenha sido informada uma.

Type:
  • string
Example
const Database = require('@nginstack/engine/lib/database/Database');

const db = new Database(host, dbName);
db.referrer = 'Processo de sincronismo de dados';

scope :string

Relação dos escopos de autorização permitidos ao usuário logado na base de dados.

Caso a autenticação na base de dados tenha sido feita por meio de um token de autorização, será retornado o escopo desse token. Caso tenha sido via credenciais do usuário, serão retornados todos os escopos de autorização atribuídos a esse usuário.

Type:
  • string
See:

serverHost :string

Endereço do servidor da base de dados

Type:
  • string

trackingId :string

Esta é uma propriedade que, se definida, será utilizada pelo applyUpdates e pelo executeDDL para preencher o campo iTag da iLog. Em sequência, caso o campo iTag tenha sido preenchido, o campo iFreshTrack será marcado com true, podendo ser alterado posteriormente por rotinas que façam processamento sobre registros da iLog com trackingId definido. Com o preenchimento do trackingId, é possível agrupar os registro na iLog por tag, facilitando o desfazimento.

Recomenda-se que a string utilizada nesta propriedade seja um identificador único. Para isto, utilize a função createGUID(removeFormatChars).

A alteração desta propriedade modificará também a mesma propriedade da instância de Connection informada na construção deste objeto, caso tenha sido informada uma.

Type:
  • string

uniqueId :string

Identificador único da base de dados.

Importante: atualmente esta propriedade gera o ID a partir do nome o que não é seguro. Em versões futuras do sistema, o formato do ID será alterado para ser único independente do nome da base. Ou seja, bases com o mesmo nome deverão ter IDs distintos. Por conta dessa alteração de comportamento prevista, não é recomendado que esse valor seja persistido no banco de dados.

Type:
  • string

userKey :number

Chave do usuário logado no servidor de banco de dados. Retorna -1 caso não exista usuário logado.

Type:
  • number

userLanguage :number

Chave do idioma do usuário.

Type:
  • number

userName :string

Nome do usuário logado no servidor de banco de dados.

Type:
  • string

workloadType :string

Indica para o banco de dados qual é o tipo de carga da aplicação que está requisitando os dados. Valores possíveis:

  • 'olap' (Online analytical processing): indicado para relatórios ou processos de consulta. Normalmente, interagem com uma massa de dados média ou elevada. Prioridade de atendimento média.
  • 'oltp' (Online transaction processing): indicado para processos que realizam a leitura ou gravação de poucos registros. Prioridade de atendimento alta.
  • 'dw' (Data Warehouse): indicado para processos que consolidam grandes massas de dados para pesquisas posteriores. Prioridade de atendimento baixa.

O valor padrão desta propriedade é "olap" e os processos que necessitem alterar a conexão padrão (variável global database) devem ter o cuidado de retornar o valor anterior após o uso, evitando assim afetar outros códigos que utilizem a a mesma instância global. Para modificar o tipo de carga de algumas consultas específicas, é preferível informar o workloadType nas opções do método query.

No banco de dados Oracle, este parâmetro é utilizado para definir o tamanho do buffer para a leitura de registros em bloco, sendo alocada mais memória para as cargas do tipo "olap" e "dw". Seu valor também estará disponível no campo "ACTION" da view "v$session", possibilitando ao DBA otimizar e priorizar o atendimento de acordo com o tipo informado.

Type:
  • string
See:

Methods

<static> fromConfig(key)

Retorna uma instância de Database associada à base de dados informada.

Observação: a chave informada deve ser de um registro da base de dados corrente.

Parameters:
Name Type Description
key DBKey | number

Chave do cadastro da base de dados. Essa chave deve ser um registro da classe "/Dados/Sistema/Bases de dados".
Returns:

Instância de Database associada à base de dados informada.

Type
Database

applyUpdates(dataSets [, logChanges])

Efetiva as alterações realizadas no dataSets no banco de dados.

Note que se a propriedade trackingId deste objeto estiver preenchida, as versões da iLog geradas por este método terão o campo iTag da iLog preenchido com o valor da propriedade trackingId deste objeto. Em sequência, caso o campo iTag tenha sido preenchido, o campo iFreshTrack será marcado com true, podendo ser alterado posteriormente por rotinas que façam processamento sobre registros da iLog com trackingId definido.

Parameters:
Name Type Argument Description
dataSets DataSet | Array

DataSet ou Array de DataSets cujas alterações serão efetivadas no banco de dados.
logChanges boolean <optional>

Registra as alterações na tabela iLog. Caso não seja informado, será considerado true. Este parâmetro é ignorado para tabelas que participam do cache local, pois o registro de log para essas tabelas é obrigatório.

Atenção: a desativação do log transacional não permite o desfazimento das alterações realizadas e prejudica a auditoria do sistema em inspeções de segurança. Modificações sem geração de log também não são aplicadas nas bases de dados destino dos processos de replicação de dados. Essas modificações podem ser perdidas em cenários de migração de banco de dados onde uma base de dados é sincronizada a partir do log transacional.
Returns:

Versão das alterações ou zero caso não existam diferenças a serem gravadas. O valor retornado também é gravado nos campos iVersion ou VERSAO dos registros.

Type
number

authenticateUser(userId, password)

Autentica o nome e senha do usuário no servidor.

Parameters:
Name Type Description
userId string

Nome ou e-mail do usuário
password string

Senha do usuário
Returns:

Chave do usuário se o userId e password forem válidos ou -1 caso falhe.

Type
number

columnExists(tableOrViewName, columnName)

Verifica se uma coluna existe em uma tabela ou visão da base de dados.

Parameters:
Name Type Description
tableOrViewName string

Nome da tabela ou visão.
columnName string

Nome da coluna a ser verificada.
Returns:

True se a coluna existir na tabela ou visão informada. Retornará false se a tabela, visão ou coluna não existirem na base de dados.

Type
boolean

createKey(keysQty [, useHighKeys])

Cria um bloco de chaves na base de dados. Caso a propriedade KeyRangeForCreateKey for informada, será criada uma chave negativa na licença informada. Para isto o usuário logado deve ter permissão para alterar a licença.

Parameters:
Name Type Argument Description
keysQty number

Quantidade de chaves que devem ser criadas.
useHighKeys boolean <optional>

Deprecated. Indica se deve ser criada utilizando a faixa de chaves altas (de 1 ã 2 bilhões).
Returns:

Primeira chave do bloco de chaves gerado ( Result -> (Result + count - 1) )

Type
number

discardCaches()

Sinaliza para todos os Engines conectados à base de dados que os caches locais de dados e chaves devem ser reconstruídos no próximo reinício do Engine. Imediatamente após a execução deste método, os Engines devem ser reiniciados para que a operação seja de fato efetivada.

Importante: a reconstrução do cache local de todos os Engines é uma operação com elevado impacto de desempenho e deixará o sistema fora do ar enquanto essa reconstrução ocorrer. Este método deve ser utilizado apenas em cenários de recriação de uma base de dados ou na restauração de um backup onde houve perda de dados.

discardEndpointInfoCache()

Descarta o cache de informações das capacidades conhecidas do Engine remoto acessado por meio desta conexão.

Este é um método avançado que em situações normais de uso não deve ser utilizado. Ele deve ser empregado apenas quando for conhecido que um Engine remoto tenha sido atualizado e quando as capacidades da nova versão desse Engine são requeridas imediatamente.

executeDDL(statement)

Executa uma expressão DLL com o objetivo de alterar o esquema da base de dados.

O uso deste método requer que o usuário tenha permissão ao escopo de autorização "database.alterSchema".

Importante: a sintaxe dos comandos de alteração de esquema da base de dados não são padronizados pelos SGBDs. Ao utilizar este método diretamente, é necessário criar instruções compatíveis com cada SGBD suportado pelo Engine. Para esse fim, avalie o uso de classes mais especializadas na manipulação do esquema da base de dados, como a DatabaseSchema.

Parameters:
Name Type Description
statement string

Instrução DDL que será executada na base de dados.
See:
  • module:@nginstack/engine/lib/schema/DatabaseSchema~DatabaseSchema DatabaseSchema
Example
database.executeDDL('ALTER TABLE iGroupUser ADD zTestColumn BIGINT');

executeSQL(sql)

Executa uma expressão SQL ou um conjunto de expressões SQLs ignorando os registros retornados, caso existam.

Para executar instruções de alteração do esquema da base de dados utilize o método #executeDDL. O uso do método executeSQL para esse fim deixará de ser suportado em versões futuras do Engine.

Parameters:
Name Type Description
sql string | Array.<string>

Expressão SQL ou Array de expressões SQLs que devem ser executadas no banco de dados.

getApproximatedVersion()

Retorna um Array com as versões APROXIMADAS atuais da base de dados. O vetor possui tamanho igual a 3(três), sendo que cada índice do vetor corresponde as seguintes versões:
Índice 0: A versao APROXIMADA da ultima alteração de um registro. Índice 1: A versao APROXIMADA da ultima alteração de um registro que faca parte do cache local. Índice 2: A versao APROXIMADA da base de dados. A versao da base de dados e alterada quando ocorre uma alteração na base de dados que nao foi registrada através do controle de versao (ex: um retorno de backup).

Returns:

vetor de versões APROXIMADAS.

Type
Array

getExecutionPlan(sql)

Obtém o plano de execução do banco de dados para a expressão SQL informada. O plano de execução é uma informação gerada pelo banco de dados que permite ao desenvolvedor compreender como o query será executado e determinar se a expressão SQL criada possui um bom desempenho. Cada banco de dados possui um modelo de plano de execução e a documentação do mesmo deve ser lida para compreender as informações retornadas. Normalmente, este método não é conveniente para o desenvolvedor, pois a informação retornada no DataSet é extensa e a utilização de DataSets em logs não é simples. É recomendada a utilização dos métodos da classe QueryAnalyzer para obter a informação do plano de execução em um formato mais simples.

Parameters:
Name Type Description
sql string

Expressão SQL da qual deve ser obtido o plano de execução.

getReferences(key, tableName [, maxReturnCount] [, ignoredTables])

Pega todas as referências de uma chave. O DataSet retornado possui os seguintes campos: iKey - Chave do registro que referencia key. iClass - Classe do registro que referencia key. Este campo é útil para filtrar as ocorrência que podem ser exibidas para um determinado usuário. iTableName - Nome da tabela de qual faz parte o registro que referencia key. iFieldName - Nome do campo que referencia key. iFieldLabel - Nome de exibição do campo que referencia key.

Parameters:
Name Type Argument Description
key number

Chave da qual se deseja obter as referências.
tableName string

Nome da tabela da qual key faz parte
maxReturnCount number <optional>

Número máximo de referências que devem ser retornadas. É importante que este valor não seja alto, pois getReferences() pode retornar uma quantidade muito elevada de registros.
ignoredTables string <optional>

Tabelas cujos registros não podem ser considerados como referências.
Returns:

DataSet com as referências aos registros. Este dataSet deve ser destruído por quem chamou este método.

Type
DataSet

getVersion()

Retorna um Array com as versões atuais da base de dados. O vetor possui tamanho igual a 3(três), sendo que cada índice do vetor corresponde as seguintes versões:
Índice 0: A versão da última alteração de um registro. Índice 1: A versão da última alteração de um registro que faça parte do cache local. Índice 2: A versão da base de dados. A versão da base de dados é alterada quando ocorre uma alteração na base de dados que não foi registrada através do controle de versão (ex: um retorno de backup).

Returns:

Vetor de versões

Type
Array

getVersionInfo()

Retorna informações de versão do gerenciador de banco de dados e do driver de conexão.

Returns:
Type
DatabaseVersionInfo

incVersion()

Incrementa a versão da base de dados e retorna a versão gerada.

A versão retornada não é associada a nenhuma alteração da base de dados e o seu valor pode ser utilizado na geração de dados ou logs associados a uma versão da base de dados, mas que não são gravados via applyUpdates.

Returns:

Versão da base de dados.

Type
number

insertLog(logType [, options])

Insere um registro de log na tabela iLog.

Os campos "iUser", "iDate", "iHour" e "iReferrer" serão preenchidos automaticamente pelo sistema. Para fins de compatibilidade, este método também aceita a seguinte assinatura:

  • insertLog(logType, content, key, classKey);
Parameters:
Name Type Argument Description
logType number

Chave do tipo de log que está sendo registrado. Deve ser um registro da classe "/data/system/Auxiliary Tables/Log Type". Será gravado no campo iType.
options Object <optional>

Opções de inserção do log.

Properties
Name Type Argument Description
content string <optional>

Conteúdo que será gravado no campo "iContent".
key number | DBKey <optional>

Chave do registro ao qual o log faz referência. Será gravado no campo "iKey".
classKey number | DBKey <optional>

Chave da classe do registro ao qual o log faz referência. Será gravado no campo "iClass".
version number | DBKey <optional>

Número de versão que será gravado no campo "iVersion". Importante: para não prejudicar a legibilidade dos logs de auditoria, informe apenas números de versões que tenham sido gerados logo antes da execução do método insertLog, garantindo assim que as colunas "iDate" e "iHour" da tabela iLog tenham uma ordem cronológica similar a da "iVersion".
async boolean <optional>

Indica se a inclusão do registro de log deve ser feita de modo assíncrono. Essa opção faz com que a gravação do log no banco de dados seja deferida e executada por uma rotina executando em segundo plano. Esse modo de inserção permite que rotinas que funcionem com o Engine offline consigam gerar registros de log. Essa opção não pode ser utilizada em conexões remotas.
tag string <optional>

Permite informar um valor para ser preenchido no campo iTag da tabela de log.

isEdgeServer()

Determina se esta conexão com a base de dados é servida por um Engine configurado como servidor de borda.

Um Engine servidor de borda se conecta indiretamente ao banco de dados, portanto, os métodos que acessam diretamente o SGBD, como applyUpdates, query, executeSQL e executeDDL, não estarão disponíveis e irão gerar um erro caso sejam utilizados. Um servidor de borda deve ser preferencialmente utilizado para atender requisições HTTP, executar tarefas agendadas ou para a execução de scripts remotos.

Todos os Engines sem acesso direto ao SGBD são considerados servidores de borda por este método, inclusive os Engines clientes instalados em computadores pessoais.

Returns:

Indica se o Engine remoto está configurado como servidor de borda.

Type
boolean

login(userId, password)

Realiza o login na conexão com a base de dados, permitindo o usuário acessar informações do banco de dados. Todos os queries e alterações ficaram serão registradas em nome do usuário logado.

Parameters:
Name Type Description
userId string

Nome ou e-mail do usuário
password string

Senha do usuário
Returns:

True, se o nome de usuário e senha foram válidos

Type
boolean

loginByAuthToken(authToken)

Efetua o login na conexão com a base de dados utilizando um token criado no sistema anteriormente pela classe AuthToken ou por meio de tokens de identificação gerados por provedores de identidade externos ao sistema.

Tokens do sistema devem ser autorizados utilizando os métodos Session.authorizeToken ou Security.authorizeToken, momento em que será gerado o token de identificação esperado por este método.

Tokens de identificação externos podem ser gerados utilizando a classe OpenIdClient. Somente serão aceitos tokens dos provedores de identidade configurados em "Admin > Segurança > Provedores de identidade".

Para logar utilizando este método, o usuário necessita do escopo security.externalAccess, mesmo que o servidor de banco de dados representado por este objeto seja o mesmo da conexão corrente.

Parameters:
Name Type Description
authToken string

Token de autorização do usuário.
See:

loginBySession(session)

Utiliza a sessão corrente para realizar o login na nova conexão remota. Não é permitida a utilização desse método para conexão entre bases de dados diferentes.

Parameters:
Name Type Description
session Session

Sessão cujo usuário corrente será utilizado para realizar o login.
See:
Returns:

True, se o nome de usuário e senha foram válidos.

Type
boolean
Example
const db = new Database(remoteEngineHost, database.dbName);
db.loginBySession(session);

logout()

Fecha a sessão com a servidor do banco de dados.

query(sql [, options])

Execute a expressão SQL e retorna os resultados no dataSet.

Parameters:
Name Type Argument Description
sql string | Array.<string>

Expressão SQL ou Array de expressões SQLs que devem ser executada no banco de dados.
options Object <optional>

Opções da consulta.

Properties
Name Type Argument Description
queryCacheLifeTime number <optional>

Determina o tempo máximo (em segundos) que o DataSet retornado é mantido em cache, e retornado em consultas idênticas
workloadType string <optional>

Determina o tipo de carga desta consulta específica sem modificar o valor corrente da propriedade workloadType desta instância de Database.
See:
Returns:

DataSet com resultado da consulta.

Type
DataSet | Array.<DataSet>
Example
const toSqlString = require('@nginstack/engine/lib/string/toSqlString.js');
const ds = database.query('SELECT * FROM iLog WHERE ' +
    'iDate = ' + toSqlString(new Date()) + ' AND iType = -1898145931', {
  workloadType: 'olap'
});

runScript(scriptKeyOrURI [, parameters] [, options])

Executa um script no servidor.

Parameters:
Name Type Argument Description
scriptKeyOrURI number | string

Chave ou URI do script que deve ser executado.
parameters Object <optional>

Objeto contendo os parâmetros a serem repassados para script em execução.
options Object <optional>

Objeto que contém o parâmetro de TimeOut para execução do script em milissegundos.

Properties
Name Type Argument Description
timeout number <optional>

Tempo máximo de espera da execução do script em milissegundos.
Returns:

Retorna o resultado da última expressão avaliada, desde que esta foi o último statement executado.

Type
*
Examples
database.runScript(585858, {codigoEntidade:123456, data: new Date()});
database.runScript('/products/Engine/tests/Teste.js',
   {codigoEntidade:123456, data: new Date()});
database.runScript(585858, {codigoEntidade:123456, data: new Date()}, {timeout: 10000});
database.runScript('/products/Engine/tests/Teste.js', null, {timeout: 3000});

sendEmail(email)

Envia um email utilizando o Engine servidor desta conexão.

Importante: a partir da versão 71 do Engine é recomendado que os e-mails sempre sejam enviados pelo método send da classe Email. Esse método leva em consideração a configuração do servidor SMTP e redireciona automaticamente para o Engine servidor caso seja necessário.

Parameters:
Name Type Description
email Email

Objeto que contém as definições do email a ser enviado.
Example
const email = new Email();
 email.addRecipient('Nome do destinatário', 'nome@dominio.com.br');
 email.subject = 'Assunto';
 email.htmlContent = '<html><body><b>Teste de Email</b><br><br></body></html>';
 database.sendEmail(email);

sendPendingLogs( [wait] [, timeout])

Envia para o banco de dados os registros de log que estão temporariamente retidos no Engine local em decorrência da inserção utilizando o modo assíncrono.

Parameters:
Name Type Argument Description
wait boolean <optional>

Se a chamada a esse método deve aguardar a conclusão da inserção dos logs.
timeout number <optional>

Tempo máximo de espera para a execução deste método.
See:
Returns:

Indica se os logs pendentes foram enviados com sucesso para o banco de dados.

Type
boolean

sequenceExists(name)

Verifica se existe uma sequência com o nome informado na base de dados.

Parameters:
Name Type Description
name string

Nome da sequência.
Returns:

True se a sequência existir.

Type
boolean

tableExists(tableName)

Verifica se existe uma tabela com o nome informado na base de dados.

Parameters:
Name Type Description
tableName string

Nome da tabela.
Returns:

True se a tabela existir.

Type
boolean

updateLogs(filters, values)

Atualiza registros de log transacional da tabela iLog.

Parameters:
Name Type Description
filters Object

Filtros utilizados na consulta aos registros de log.

Properties
Name Type Argument Description
version number <optional>

Permite filtrar os registros de log pelo numero de versão.
tag string <optional>

Permite filtrar os registros de log pelo valor de tag.
values Object

Valores que serão atualizados nos registros selecionados.

Properties
Name Type Description
freshTrack boolean

Permite definir o valor da coluna "iFreshTrack" dos registros de log selecionados. Atualmente somente esse campo pode ser alterado.
See:

userHasScope(userKey, scope)

Verifica se o escopo informado foi atribuído ao usuário.

Parameters:
Name Type Description
userKey DBKey | number

Chave do usuário ao qual se deseja verificar a atribuição do escopo.
scope string | DBKey | number

Nome ou chave do escopo a ter a atribuição verificada.
Returns:

True se o escopo indicado por scope tiver sido atribuído ao usuário.

Type
boolean

viewExists(viewName)

Verifica se existe uma visão com o nome informado na base de dados.

Parameters:
Name Type Description
viewName string

Nome da visão.
Returns:

True se a visão existir.

Type
boolean