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 |
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: "https:", "http:" e "iap:".
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
-
<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 escrava é 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
boolean <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". -
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(idToken)
-
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 > Políticas de segurança > Provedores de identidade".
Parameters:
Name Type Description idToken
string Token de identificação do usuário.
-
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>
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.
-
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.
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);
-
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
-
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