Ajuda do LibreOffice 24.8
O serviço Database permite o acesso a bancos de dados embutidos ou descritos por documentos Base. Este serviço fornece métodos para:
Obter acesso aos dados de tabelas em bancos de dados
Realizar consultas SELECT e executar funções agregadas.
Realizar ações baseadas em comandos SQL como INSERT, UPDATE, DELETE, etc.
Cada instância do serviço Database representa um único banco de dados e dá acesso a suas tabelas, consultas e dados.
Este serviço não fornece acesso aos formulários ou relatórios do documento Base que contém o banco de dados. Para acessar os formulários em um documento Base, consulte o método FormDocuments do serviço Base.
Todas as trocas entre este serviço e o banco de dados são feitas usando SQL apenas.
Comandos SQL podem ser executados nos modos direto ou indireto. No modo direto o comando é transferido ao banco de dados sem verificação ou revisão de sintaxe.
Os interfaces fornecidas incluem tabelas e listas de consultas, bem como acesso aos dados contidos no banco de dados.
Para tornar instruções SQL mais legíveis, colchetes "[ ]" podem ser usados em volta de nomes de tabelas, consultas e campos em vez de usar outros caracteres que pode ser exclusivos de certos Sistemas de Gerenciamento de Bancos de Dados Relacionais (SGBDR). Porém esteja ciente que caracteres delimitadores são obrigatórios neste contexto.
Por padrão, o banco de dados lida com transações no modo de confirmação automática (auto-commit), o que significa que uma confirmação é feita após cada instrução SQL.
Use o método SetTransactionMode para alterar o comportamento padrão, que permite commits e reversões manuais.
Os métodos Commit e Rollback são usados para delimitar transações.
No LibreOffice há cinco tipos de modos de isolamento de transações, os quais são definidos no grupo de constantes com.sun.star.sdbc.TransactionIsolation:
| Constante | Valor | Interpretação | 
|---|---|---|
| NONE | 0 | A manipulação de transações é desabilitada e o banco de dados passa a usar o modo de confirmação automática padrão. | 
| READ_UNCOMMITTED | 1 | Podem ocorrer leituras sujas, leituras não repetíveis e leituras fantasmas. Se uma linha for alterada por uma transação, outra transação poderá ler essas alterações mesmo que elas não tenham sido confirmadas. | 
| READ_COMMITTED | 2 | Leituras sujas são evitadas, porém podem ocorrer leituras não repetíveis e leituras fantasmas. Este nível impede que as linhas com alterações não confirmadas sejam lidas. | 
| REPEATABLE_READ | 4 | Leituras sujas e leituras não repetíveis são evitadas. No entanto, podem ocorrer leituras fantasmas. Além de impedir a leitura de dados não confirmados, também evita que duas operações de leitura na mesma transação retornem resultados diferentes. | 
| SERIALIZABLE | 8 | Leituras sujas, leituras não repetíveis e leituras fantasmas são evitadas. Além das restrições do nível anterior, também garante que o conjunto de registros que correspondem a uma cláusula WHERE permaneça inalterado dentro da mesma transação. | 
Leia a página da Wikipedia intitulada Isolation in Database Systems para saber mais sobre integridade de transações.
Antes de usar o serviço Database a biblioteca ScriptForge precisa ser carregada ou importada:
Para criar uma instância do serviço Database você pode usar o método CreateScriptService:
CreateScriptService("SFDatabases.Database", [filename: str], [registrationname], [readonly], [user, [password]]): svc
Na sintaxe descrita acima pode-se usar "SFDatabases.Database" ou simplesmente "Database" como o primeiro argumento do método CreateScriptService.
filename: Nome do arquivo Base. Deve ser expresso usando a notação SF_FileSystem.FileNaming.
registrationname: Nome de banco de dados registrado. Se filename for especificado, este argumento não deve ser usado.
Por outro lado, se o argumento registrationname for especificado o parâmetro filename não deve ser definido.
readonly: Determina se o banco de dados será aberto como somente leitura (Padrão = True).
user, password: Parâmetros adicionais de conexão a serem enviados ao servidor de banco de dados.
      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDatabase as Object
      Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      ' Executa consultas, comandos SQL, etc...
      myDatabase.CloseDatabase()
    
      from scriptforge import CreateScriptService
      myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      # Executa consultas, comandos SQL, etc...
      myDatabase.CloseDatabase()
    Também é possível acessar o banco de dados associado a um documento Base usando o serviço ScriptForge.UI, conforme mostrado no exemplo abaixo:
      Dim myDoc As Object, myDatabase As Object, ui As Object
      Set ui = CreateScriptService("UI")
      Set myDoc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      ' Nome de usuário e senha são informados abaixo, se necessário
      Set myDatabase = myDoc.GetDatabase()
      ' Executa consultas, comandos SQL, etc...
      myDatabase.CloseDatabase()
      myDoc.CloseDocument()
    
      ui = CreateScriptService("UI")
      doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      # Nome de usuário e senha são informados abaixo, se necessário
      myDatabase = doc.GetDatabase()
      # Executa consultas, comandos SQL, etc...
      myDatabase.CloseDatabase()
      doc.CloseDocument()
    O método GetDatabase usado no exemplo acima é parte do serviço Base da biblioteca ScriptForge.
| Nome | Somente leitura | Tipo | Descrição | 
|---|---|---|---|
| Queries | Sim | Array de Strings | Lista das consultas armazenadas. | 
| Tables | Sim | Array de Strings | Lista de tabelas armazenadas. | 
| XConnection | Sim | Objeto UNO representando a atual conexão de banco de dados. | |
| XMetaData | Sim | Objeto UNO representando os metadados que descrevem os atributos do sistema de banco de dados. | 
| Lista de Métodos no Serviço Database | ||
|---|---|---|
Fecha a conexão atual com a base de dados.
db.CloseDatabase()
    myDatabase.CloseDatabase() ' Basic
  
    myDatabase.CloseDatabase() # Python
  Confirma todas as atualizações feitas desde a chamada Commit ou Rollback anterior.
Este método é ignorado se as confirmações forem feitas automaticamente após cada instrução SQL, ou seja, o banco de dados estiver definido para o modo de confirmação automática padrão.
db.Commit()
      ' Define o nível de transação REPEATABLE_READ
      myDB.SetTransactionMode(4)
      myDB.RunSql("UPDATE ...")
      myDB.Commit()
      myDB.RunSql("DELETE ...")
      ' Testa alguma condição antes de confirmar
      If bSomeCondition Then
          myDB.Commit()
      Else
          myDB.Rollback()
      End If
      ' Restaura o modo de confirmação automática
      myDB.SetTransactionMode()
    
      myDB.SetTransactionMode(4)
      myDB.RunSql("UPDATE ...")
      myDB.Commit()
      myDB.RunSql("DELETE ...")
      if some_condition:
          myDB.Commit()
      else:
          myDB.Rollback()
      myDB.SetTransactionMode()
    Cria uma instância do serviço Dataset com base em uma tabela, consulta ou instrução SQL SELECT.
db.CreateDataset(sqlcommand: str, opt directsql: bool, opt filter: str, opt orderby: str): svc
sqlcommand: um nome de tabela, um nome de consulta ou uma instrução SQL SELECT válida. Os identificadores podem ser colocados entre colchetes. Este argumento diferencia maiúsculas de minúsculas.
directsql: defina este argumento como True para enviar a instrução diretamente ao mecanismo de banco de dados sem pré-processamento do LibreOffice (Padrão = False).
filtro: especifica a condição que os registros devem atender para serem incluídos no conjunto de dados retornado. Este argumento é expresso como uma instrução SQL WHERE sem a palavra-chave "WHERE".
orderby: especifica a ordem do conjunto de dados como uma instrução SQL ORDER BY sem a palavra-chave "ORDER BY".
Os exemplos a seguir em Basic e Python retornam um conjunto de dados com os registros de uma tabela chamada "Clientes".
      oDataset = myDatabase.CreateDataset("Clientes", Filter := "[Name] LIKE 'A'")
    
      dataset = myDatabase.CreateDataset("Clientes", Filter = "[Name] LIKE 'A'")
    Computa a função agregada em um campo ou expressão pertencente a uma tabela.
Opcionalmente, uma cláusula WHERE pode ser especificada como um filtro que será aplicado antes da função agregada.
db.DAvg(expression: str, tablename: str, [criteria: str]): any
db.DCount(expression: str, tablename: str, [criteria: str]): any
db.DMin(expression: str, tablename: str, [criteria: str]): any
db.DMax(expression: str, tablename: str, [criteria: str]): any
db.DSum(expression: str, tablename: str, [criteria: str]): any
expression: Uma expressão SQL na qual os nomes dos campos são delimitados por colchetes.
tablename: Nome da tabela (sem colchetes).
criteria: Uma cláusula WHERE sem a palavra-chave "WHERE", na qual os nomes dos campos são delimitados por colchetes.
O exemplo abaixo assume que o arquivo Employees.odb possui uma tabela com o nome EmployeeData.
      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDB as Variant
      Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
      ' Conta o número de empregados na tabela
      MsgBox myDB.DCount("[ID]", "EmployeeData")
      ' Retorna a soma de todos os salários na tabela
      MsgBox myDB.DSum("[Salary]", "EmployeeData")
      ' Abaixo estão alguns exemplos de como tabelas podem ser filtradas
      MsgBox myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Manager'")
      MsgBox myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Sales' AND [City] = 'Chicago'")
      MsgBox myDB.DCount("[ID]", "EmployeeData", "[FirstName] LIKE 'Paul%'")
    
      myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
      bas = CreateScriptService("Basic")
      bas.MsgBox(myDB.DCount("[ID]", "EmployeeData"))
      bas.MsgBox(myDB.DSum("[Salary]", "EmployeeData"))
      bas.MsgBox(myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Manager'"))
      bas.MsgBox(myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Sales' AND [City] = 'Chicago'"))
      bas.MsgBox(myDB.DCount("[ID]", "EmployeeData", "[FirstName] LIKE 'Paul%'"))
    Calcula uma expressão SQL em um único registro retornado por uma cláusula WHERE definida pelo parâmetro Criteria.
Se a consulta retornar múltiplos registros, apenas o primeiro é considerado. Use o parâmetro OrderClause para determinar como os resultados da consulta serão ordenados.
db.DLookup(expression: str, tablename: str, [criteria:str], [orderclause: str]): any
expression: Uma expressão SQL na qual os nomes dos campos são delimitados por colchetes.
tablename: Nome da tabela (sem colchetes).
criteria: Uma cláusula WHERE sem a palavra-chave "WHERE", na qual os nomes dos campos são delimitados por colchetes.
orderclause: Uma cláusula ORDER BY sem a palavra-chave "ORDER BY". Nomes de campos devem ser delimitados por colchetes.
      MsgBox myDB.DLookup("[FirstName]", "EmployeeData", Criteria := "[LastName] LIKE 'Smith'", OrderClause := "[FirstName] DESC")
      MsgBox myDB.DLookup("[Salary]", "EmployeeData", Criteria := "[ID] = '3'")
      MsgBox myDB.DLookup("[Quantity] * [Value]", "Sales", Criteria := "[SaleID] = '5014'")
    
      bas = CreateScriptService("Basic")
      bas.MsgBox(myDB.DLookup("[FirstName]", "EmployeeData", criteria = "[LastName] LIKE 'Smith'", orderclause = "[FirstName] DESC"))
      bas.MsgBox(myDB.DLookup("[Salary]", "EmployeeData", criteria = "[ID] = '3'"))
      bas.MsgBox(myDB.DLookup("[Quantity] * [Value]", "Sales", criteria = "[SaleID] = '5014'"))
    Armazena o conteúdo de uma tabela ou os resultados de uma consulta SELECT ou de um comando SQL em um Array de duas dimensões. O primeiro índice do Array corresponde às linhas e o segundo índice refere-se às colunas.
Um limite superior pode ser especificado para a quantidade de linhas retornadas. Opcionalmente os nomes das colunas podem ser inseridos na primeira linha do Array.
O Array retornado pode estar vazio se nenhuma linha for retornada e os cabeçalhos das colunas não tiverem sido requeridos.
db.GetRows(sqlcommand: str, directsql: bool = False, header: bool = False, maxrows: int = 0): any
sqlcommand: Um nome de tabela ou consulta (sem colchetes) ou um comando SQL do tipo SELECT.
directsql: Se True, o comando SQL é enviado ao banco de dados diretamente sem análise prévia. O valor padrão é False. Este argumento é ignorado para tabelas. Para consultas, a opção aplicada é a definida quando a consulta foi criada.
header: Se True, a primeira linha do array retornado contém os cabeçalhos das colunas.
maxrows: Quantidade máxima de linhas a serem retornadas. O valor padrão é zero, indicando que não há limite para o número de registros retornados.
Abaixo estão alguns exemplos de como o método GetRows pode ser usado:
      Dim queryResults as Variant
      ' Retorna todas as linhas na tabela juntamente com os cabeçalhos
      queryResults = myDB.GetRows("EmployeeData", Header := True)
      ' Retorna os primeiros 50 registros de funcionários ordenados pelo campo 'FirstName'
      queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", MaxRows := 50)
    
      queryResults = myDB.GetRows("EmployeeData", header = True)
      queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", maxrows = 50)
    Abre o documento de formulário especificado no modo normal. Este método retorna uma instância do serviço FormDocument correspondente ao documento de formulário especificado.
Se o documento de formulário já estiver aberto, a janela do documento de formulário será ativada.
Se o documento de formulário especificado não existir, então Nothing será retornado.
svc.OpenFormDocument(formdocument: str): svc
formdocument: O nome do FormDocument a ser aberto, como uma string que diferencia maiúsculas de minúsculas.
A maioria dos documentos de formulário são armazenados na raiz do documento Base e podem ser abertos simplesmente usando seus nomes, como no exemplo abaixo:
    Dim oFormDoc As Object
    oFormDoc = myDB.OpenFormDocument("myFormDocument")
  Se os documentos do formulário estiverem organizados em pastas, torna-se necessário incluir o nome da pasta para especificar o documento do formulário a ser aberto, conforme ilustrado no exemplo a seguir:
    oFormDoc = myDB.OpenFormDocument("myFolder/myFormDocument")
  
    formDoc = myDB.OpenFormDocument("myFormDocument")
  
    formDoc = myDB.OpenFormDocument("myFolder/myFormDocument")
  Abre a janela de exibição de dados da consulta especificada e retorna uma instância de serviço da Datasheet.
Se a consulta não puder ser aberta, retorna Nothing.
db.OpenQuery(queryname: str): obj
queryname: o nome de uma consulta existente como uma string que diferencia maiúsculas de minúsculas.
      myDatabase.OpenQuery("MyQuery")
    
      myDatabase.OpenQuery("MyQuery")
    Executa um comando SQL SELECT, abre uma janela de exibição de dados com os resultados e retorna uma instância do serviço Datasheet.
db.OpenSql(sql: str, directsql: bool): obj
sql: Uma string contendo uma instrução SQL SELECT válida. Os identificadores podem ser colocados entre colchetes.
directsql: Quando True, o comando SQL é enviado para o mecanismo de banco de dados sem pré-análise (Padrão = False).
      myDatabase.OpenSql("SELECT * FROM [Customers] ORDER BY [CITY]")
    
      myDatabase.OpenSql("SELECT * FROM [Customers] ORDER BY [CITY]")
    Abre a janela Exibição de dados da tabela especificada e retorna uma instância do serviço Datasheet.
db.OpenTable(tablename: str): obj
tablename: O nome de uma tabela existente como uma String que diferencia maiúsculas de minúsculas.
      myDatabase.OpenTable("MyTable")
    
      myDatabase.OpenTable("MyTable")
    Cancela todas as alterações feitas no banco de dados desde a última chamada de Commit ou Rollback.
db.Rollback()
      myDB.SetTransactionMode(1)
      myDB.RunSql("UPDATE ...")
      ' ...
      If bSomeCondition Then
          myDB.Rollback()
      End If
    
      myDB.SetTransactionMode(1)
      myDB.RunSql("UPDATE ...")
      # ...
      if bSomeCondition:
          myDB.Rollback()
    Executa comandos SQL de ação, tais como como a criação tabelas, bem como a inserção, atualização ou remoção de registros.
Este método retorna True quando for bem-sucedido.
O método RunSql é rejeitado com uma mensagem de erro se o banco de dados foi previamente aberto no modo somente leitura.
db.RunSql(sqlcommand: str, directsql: bool = False): bool
sqlcommand: Nome da consulta (sem colchetes) ou um comando SQL.
directsql: Se True, o comando SQL é enviado ao banco de dados diretamente sem análise prévia. O valor padrão é False. Para consultas, a opção aplicada é a definida quando a consulta foi criada.
      myDatabase.RunSql("INSERT INTO [EmployeeData] VALUES(25, 'Smith', 'John')", DirectSQL := True)
    
      myDatabase.RunSql("INSERT INTO [EmployeeData] VALUES(25, 'Smith', 'John')", directsql = True)
    Define o nível de isolamento nas transações do banco de dados.
Por padrão, os bancos de dados gerenciam transações no modo de confirmação automática, o que significa que um Commit é executado automaticamente após cada instrução SQL.
Use este método para determinar manualmente o nível de isolamento das transações. Quando um modo de transação diferente de NONE é especificado, o script deve chamar explicitamente o método Commit para aplicar as alterações ao banco de dados.
Este método retorna True quando for bem-sucedido.
Alterar o modo de transação fecha todas as instâncias do serviço Dataset criadas a partir do banco de dados atual.
db.SetTransactionMode(transactionmode: int = 0): bool
transactionmode: Especifica o modo de transação. Este argumento deve ser uma das constantes definidas em com.sun.star.sdbc.TransactionIsolation (Padrão = NONE)
Leia a seção Manipulação de transações acima para saber mais sobre os níveis de isolamento de transações usados no LibreOffice.
      myDB.SetTransactionMode(com.sun.star.sdbc.TransactionIsolation.REPEATABLE_READ)
      oDataset = myDB.CreateDataset("SELECT ...")
      ' ...
      ' Redefine o modo de transação para o padrão
      myDB.SetTransactionMode()
    
      from com.sun.star.sdbc import TransactionIsolation
      myDB.SetTransactionMode(TransactionIsolation.REPEATABLE_READ)
      dataset = myDB.CreateDataset("SELECT ...")
      # ...
      myDB.SetTransactionMode()