nginstack

Class: DatabaseSchema

@nginstack/engine/lib/schema/DatabaseSchema~ DatabaseSchema

new DatabaseSchema( [database])

Classe que permite obter informações do esquema de uma base de dados de forma padronizada em todos os SGBDs suportados pelo Engine.

Os nomes das tabelas, colunas, índices, visões e triggers retornados pelos métodos desta classe são normalizados em caixa baixa.

Parameters:
Name Type Argument Description
database Database <optional>

Base de dados que terá o seu esquema de dados consultado ou alterado.

Members

database :Database

Base de dados que terá o seu esquema de dados consultado ou alterado.

Type:

Methods

<static> deregisterObserver(observer)

Remove um observador registrado previamente pela função registerObserver.

Parameters:
Name Type Description
observer module:@nginstack/engine/lib/schema/DatabaseSchemaObserver~DatabaseSchemaObserver

Observador que irá parar de observar as alterações no esquema da base de dados.

<static> registerObserver(observer)

Registra um observador das alterações no esquema da base de dados realizadas por meio desta classe.

Observadores também podem ser registrados de forma global no sistema por meio da propriedade `databaseSchemaObservers´ na classe de configuração "/Configuração/Base de dados".

Parameters:
Name Type Description
observer module:@nginstack/engine/lib/schema/DatabaseSchemaObserver~DatabaseSchemaObserver

Observador a ser registrado.

addTableColumns(tableName, columns [, options])

Adiciona as colunas na tabela informada.

Parameters:
Name Type Argument Description
tableName string

Nome da tabela que terá as colunas adicionadas.
columns Array.<ColumnDef>

Colunas a serem adicionadas na tabela.
options Object <optional>

Opções da adição das colunas na tabela.

Properties
Name Type Description
dryRun boolean

Indica que o comando será gerado e retornado por esta função, mas não será executado na base de dados.
Returns:

Comando de adição das colunas na tabela informada.

Type
string

alterTable(tableName, options)

Altera as configurações gerais de uma tabela.

Atualmente somente é possível alterar a chave primária. Para modificar as colunas de uma tabela, utilize #alterTableColumns.

Dependendo das modificações realizadas, este método poderá retornar um ou vários comandos separados por ";". No caso do Oracle, múltiplos comandos serão contidos em um bloco PL/SQL.

Parameters:
Name Type Description
tableName string

Nome da tabela que será modificada.
options Object

Opções de alteração da tabela.

Properties
Name Type Description
dryRun boolean

Indica que o comando será gerado e retornado por esta função, mas não será executado na base de dados.
primaryKey Array.<string>

Colunas que definem a chave primária da tabela.
indexTablespace string

Tablespace onde o índice da chave primária deve ser criado.
Returns:

Comando de alteração da tabela informada.

Type
string

alterTableColumns(tableName, columns [, options])

Altera as colunas da tabela informada.

Dependendo das modificações realizadas, este método poderá retornar um ou vários comandos separados por ";". No caso do Oracle, múltiplos comandos serão contidos em um bloco PL/SQL.

Observações:

  1. O Microsoft SQL Server não permite modificar o tipo de uma coluna que participa de índices, incluindo o índice utilizado para validar a chave primária. No caso da chave primária, ela será removida antes da alteração do tipo e restaurada logo após a mudança. Enquanto durar a conversão e caso o comando de alteração de tipo falhe, a tabela ficará sem chave primária. Em caso de falha, ela precisará ser restaurada via método #alterTable. No caso dos demais índices, eles serão removidos e precisarão ser recriados posteriormente utilizando o método #createTableIndex.
  2. O Oracle não permite a alteração do tipo de dado de uma coluna se ela possuir valores não nulos. É permitido apenas alterar o tamanho de colunas do tipo char ou varchar e a precisão e escala dos tipos numéricos.
Parameters:
Name Type Argument Description
tableName string

Nome da tabela que terá as colunas alteradas.
columns Array.<ColumnDef>

Novas definições das colunas que serão alteradas na tabela. As colunas não informadas serão preservadas.
options Object <optional>

Opções da alteração das colunas na tabela.

Properties
Name Type Description
dryRun boolean

Indica que o comando será gerado e retornado por esta função, mas não será executado na base de dados.
indexTablespace string

Tablespace que deve ser utilizado pelo índice da chave primária, caso ele precise ser recriado.
Returns:

Comando de alteração das colunas na tabela informada.

Type
string

createTable(tableName, columns [, options])

Cria uma tabela na base de dados.

Parameters:
Name Type Argument Description
tableName string

Nome da tabela a ser criada.
columns Array.<ColumnDef>

Colunas da tabela a ser criada.
options Object <optional>

Opções da criação da tabela.

Properties
Name Type Description
dryRun boolean

Indica que o comando será gerado e retornado por esta função, mas não será executado na base de dados.
primaryKey Array.<string>

Colunas que definem a chave primária da tabela.
tablespace string

Tablespace onde a tabela deverá ser criada.
indexTablespace string

Tablespace onde o índice da chave primária deve ser criado.
Returns:

Comando DDL de criação da tabela.

Type
string

createTableIndex(tableName, indexDef [, options])

Cria um índice na base de dados.

Parameters:
Name Type Argument Description
tableName string

Nome da tabela na qual o índice será criado.
indexDef IndexDef

Definição do índice que será criado.
options Object <optional>

Opções da criação do índice.

Properties
Name Type Description
dryRun boolean

Indica que o comando será gerado e retornado por esta função, mas não será executado na base de dados.
online boolean

Indica que o índice deve ser criado sem bloquear a leitura da tabela indexada. Esse recurso não é suportado em todas as versões dos SGBDs, sendo uma funcionalidade exclusiva da versão "Enterprise" do Oracle e do Microsoft SQL Server.
Returns:

Comando DDL de criação do índice.

Type
string

dropTable(tableName [, options])

Remove a tabela da base de dados.

Parameters:
Name Type Argument Description
tableName string

Nome da tabela a ser removida.
options Object <optional>

Opções da remoção da tabela.

Properties
Name Type Description
dryRun boolean

Indica que o comando será gerado e retornado por esta função, mas não será executado na base de dados.
Returns:

Comando de remoção da tabela.

Type
string

dropTableColumns(tableName, columns [, options])

Remove as colunas na tabela informada.

Observação: no Oracle as colunas são apenas marcadas como não utilizadas, não sendo removidas fisicamente da tabela. Para reclamar o espaço utilizado por essas colunas, deve ser utilizado o comando: ALTER TABLE <table_name> DROP UNUSED COLUMNS. Esse comando irá bloquear a tabela durante a remoção das colunas. Avalie utilizar a opção CHECKPOINT para minimizar o tamanho do undo log durante a operação. Mais detalhes em https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/ALTER-TABLE.html.

Parameters:
Name Type Argument Description
tableName string

Nome da tabela que terá as colunas removidas.
columns Array.<string>

Nome das colunas a serem removidas.
options Object <optional>

Opções da remoção de colunas na tabela.

Properties
Name Type Description
dryRun boolean

Indica que o comando será gerado e retornado por esta função, mas não será executado na base de dados.
Returns:

Comando de remoção das colunas na tabela informada.

Type
string

dropTableIndex(tableName, indexName [, options])

Remove um índice da base de dados.

Parameters:
Name Type Argument Description
tableName string

Nome da tabela que contém o índice que será removido.
indexName string

Nome do índice que será removido.
options Object <optional>

Opções da remoção do índice.

Properties
Name Type Description
dryRun boolean

Indica que o comando será gerado e retornado por esta função, mas não será executado na base de dados.
online boolean

Indica que o índice deve ser removido sem bloquear a leitura da tabela indexada. Esse recurso não é suportado em todas as versões dos SGBDs, sendo uma funcionalidade exclusiva da versão "Enterprise" do Oracle (12c ou superior) e do Microsoft SQL Server.
Returns:

Comando DDL de remoção do índice.

Type
string

dropView(viewName [, options])

Remove a visão da base de dados.

Parameters:
Name Type Argument Description
viewName string

Nome da visão a ser removida.
options Object <optional>

Opções da remoção da visão.

Properties
Name Type Description
dryRun boolean

Indica que o comando será gerado e retornado por esta função, mas não será executado na base de dados.
Returns:

Comando de remoção da visão.

Type
string

getAllTablesAndViewsColumns()

Obtém as informações das colunas de todas as tabelas e visões da base de dados.

Returns:

Objeto cujas propriedades serão os nomes das tabelas ou visões, e os valores serão um array com as informações das colunas da tabela ou visão associada.

Type
Record.<string, Array.<ColumnInfo>>

getAllTablesIndexes()

Obtém informações dos índices de todas as tabelas da base de dados.

Returns:

Objeto cujas propriedades serão os nomes das tabelas que possuem índices e os valores serão um array com as informações dos índices da tabela associada.

Type
Record.<string, Array.<IndexInfo>>

getTableColumns(tableName)

Obtém informações das colunas de uma tabela da base de dados.

Parameters:
Name Type Description
tableName string

Nome da tabela que será consultada.
Returns:

Informações sobre as colunas de uma tabela da base de dados.

Type
Array.<ColumnInfo>
Example
const DatabaseSchema = require('@nginstack/engine/lib/schema/DatabaseSchema');
const schema = new DatabaseSchema(database);
const columns = schema.getTableColumns('iGroupUser');
let info = columns.find(function (elem) {
  return elem.name === 'ikey';
});
info.name; // => 'ikey'
info.dataType; // => 'integer'
info.nullable; // =>  false

getTableIndexes(tableName)

Obtém informações dos índices de uma tabela da base de dados.

Parameters:
Name Type Description
tableName string

Nome da tabela que será consultada.
Returns:

Informações sobre os índices de uma tabela da base de dados.

Type
Array.<IndexInfo>

getTables( [tableNames])

Obtém informações das tabelas públicas do esquema padrão da base de dados.

Não serão retornadas informações das visões de tabelas. Para isso, utilize o método #getViews.

Parameters:
Name Type Argument Description
tableNames Array.<string> <optional>

Nomes das tabelas cuja informação de esquema de ser obtida. Caso não seja informado, serão retornadas as informações de todas as tabelas do esquema corrente.
Returns:

Informações das tabelas da base de dados.

Type
Array.<TableInfo>
Example
const DatabaseSchema = require('@nginstack/engine/lib/schema/DatabaseSchema');
const schema = new DatabaseSchema(database);
const tables = schema.getTables();
const info = tables.find(function (elem) {
  return elem.name === 'igroupuser';
});
info.name; => 'igroupuser'
info.primaryKey; // => ['ikey']

getTableTriggers(tableName)

Obtém informações dos triggers de uma tabela da base de dados.

Parameters:
Name Type Description
tableName string

Nome da tabela que será consultada.
Returns:

Informações sobre os triggers de uma tabela da base de dados.

Type
Array.<TriggerInfo>

getViewColumns(tableName)

Obtém informações das colunas de uma visão da base de dados.

Observação: o SGBD PostgreSQL tem limitações na rastreabilidade das restrições de colunas das visões e a propriedade nullable não preserva o valor deste atributo da coluna de origem.

Parameters:
Name Type Description
tableName string

Nome da visão que será consultada.
Returns:

Informações sobre as colunas de uma visão da base de dados.

Type
Array.<ColumnInfo>

getViews( [viewNames])

Obtém informações das visões de tabelas públicas do esquema padrão da base de dados.

Parameters:
Name Type Argument Description
viewNames Array.<string> <optional>

Nomes das visões cuja informação de esquema de ser obtida. Caso não seja informado, serão retornadas as informações de todas as visões do esquema corrente.
Returns:

Informações das visões de tabelas da base de dados.

Type
Array.<ViewInfo>

renameTableColumn(tableName, columnName, newColumnName [, options])

Altera o nome de uma coluna de uma tabela da base de dados.

Parameters:
Name Type Argument Description
tableName string

Nome da tabela que terá a coluna renomeada.
columnName string

Nome atual da coluna
newColumnName string

Nome da coluna após ser renomeada.
options Object <optional>

Opções da alteração da coluna.

Properties
Name Type Description
dryRun boolean

Indica que o comando será gerado e retornado por esta função, mas não será executado na base de dados.
Returns:

Comando DDL de alteração da coluna.

Type
string

renameTableIndex(tableName, indexName, newIndexName [, options])

Altera o nome um índice na base de dados.

Parameters:
Name Type Argument Description
tableName string

Nome da tabela que contém o índice que será renomeado.
indexName string

Nome atual do índice.
newIndexName string

Nome que o índice terá após ser renomeado.
options Object <optional>

Opções da alteração do índice.

Properties
Name Type Description
dryRun boolean

Indica que o comando será gerado e retornado por esta função, mas não será executado na base de dados.
Returns:

Comando DDL de alteração do índice.

Type
string

supportsOnlineIndexCreation()

Indica se a base de dados suporta a criação de índices sem bloqueio das tabelas indexadas.

Returns:

True se a base de dados suportar a criação de índices concorrentemente com a utilização das tabelas.

Type
boolean

supportsOnlineIndexDrop()

Indica se a base de dados suporta a remoção de índices sem bloqueio das tabelas indexadas.

Returns:

True se a base de dados suportar a remoção de índices concorrentemente com a utilização das tabelas.

Type
boolean