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.
Ex.: ORACLE e MSSQL

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';

serverHost :string

Endereço do servidor da base de dados

Type:
  • string

trackingId :string

Esta é uma propriedade que, se definida, será utilizada pelo applyUpdates 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.

Para desfazer versões por iTag utilize a função undoLogByTag(iTag).

Recomenda-se que a string utilizada com nesta propriedade seja um GUID. 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 comportamento 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". Os processos que necessitem alterar a conexão padrão (variável connection) devem ter o cuidado de retornar o valor anterior após o uso, evitando assim afetar outros códigos que utilizem a connection.
No banco de dados Oracle, este parâmetro 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

Methods

applyUpdates(dataSets [, opt_log])

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.
opt_log boolean <optional>

Registra as alterações na iLog. Caso não seja informado, será considerado true.
Returns:

A versão (campo VERSAO) utilizada para registrar as alterações

Type
number

authenticateUser(userName, password)

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

Parameters:
Name Type Description
userName string

Nome do usuário
password string

Senha do usuário
Returns:

Chave do Usuário se o userName e password forem válidos ou -1 caso falhe

Type
number

createKey(keysQty [, opt_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.
opt_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

executeSQL(sql)

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

Parameters:
Name Type Description
sql String | Array

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

insertLog(logType, opt_content, opt_key, opt_classKey)

Insere um registro de Log na tabela iLog. Os campos iUser, iDate, iHour e iReferrer serão preenchidos automaticamente pelo sistema.

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.
opt_content string <nullable>

Conteúdo que será gravado no campo iContent.
opt_key number <nullable>

Chave do registro ao qual o log faz referência. Será gravado no campo iKey.
opt_classKey number <nullable>

Chave da classe do registro ao qual o log faz referência. Será gravado no campo iClass.

login(userName, 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
userName string

Nome do usuário
password string

Senha do usuário
Returns:

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

Type
boolean

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

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

parâmetros extras. A propriedade queryCacheLifeTime determina o tempo máximo(em segundos) que o DataSet retornado é mantido em cache, e retornado em consultas idênticas
Returns:

DataSet com resultado da consulta.

Type
DataSet

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.
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});

tableExists(tableName)

Verifica se a tabela informada existe na base dados.

Parameters:
Name Type Description
tableName string

Nome da tabela.
Returns:

True se a tabela existir.

Type
boolean