Pomoc LibreOffice 25.2
Usługa Database zapewnia dostęp do baz danych osadzonych lub opisanych w dokumentach Base. Usługa ta zapewnia metody umożliwiające:
Uzyskanie dostępu do danych w tabelach bazy danych.
Uruchamianie kwerendy SELECT i wykonywanie funkcji agregujących.
Uruchamianie instrukcji działania SQL, takich jak INSERT, UPDATE, DELETE itp.
Każda instancja usługi Database reprezentuje pojedynczą bazę danych i daje dostęp do jej tabel, zapytań i danych.
Usługa ta nie zapewnia dostępu do formularzy i raportów znajdujących się w dokumencie Base zawierającym bazę danych. Aby uzyskać dostęp do formularzy w dokumencie Base, zapoznaj się z metodą FormDocuments usługi Base.
Cała wymiana między tą usługą a bazą danych odbywa się wyłącznie przy użyciu SQL.
Instrukcje SQL mogą być uruchamiane w trybie bezpośrednim lub pośrednim. W trybie bezpośrednim instrukcja jest przesyłana do silnika bazy danych bez sprawdzania i przeglądania składni.
Dostarczone interfejsy obejmują proste tabele i listy kwerend, a także dostęp do danych z baz danych.
Aby zwiększyć czytelność instrukcji SQL, można użyć nawiasów kwadratowych „[ ]” do ujęcia nazw tabel, kwerend i pól, zamiast używać innych znaków otaczających, które mogą być dostępne wyłącznie w niektórych systemach zarządzania relacyjnymi bazami danych (RDBMS). Należy jednak pamiętać, że w tym kontekście znaki otaczające są obowiązkowe.
Domyślnie baza danych obsługuje transakcje w trybie automatycznego zatwierdzania, co oznacza, że zatwierdzenie jest wykonywane po każdej instrukcji SQL.
Użyj metody SetTransactionMode, aby zmienić domyślne zachowanie, które pozwala na ręczne zatwierdzanie i wycofywanie zmian.
Metody Commit i Rollback służą do oddzielania transakcji.
W LibreOffice istnieje pięć typów trybów izolacji transakcji zdefiniowanych w grupie stałych com.sun.star.sdbc.TransactionIsolation:
| Stała | Wartość | Interpretacja | 
|---|---|---|
| NONE | 0 | Obsługa transakcji jest wyłączona, a baza danych ustawiona jest na domyślny tryb automatycznego zatwierdzania. | 
| READ_UNCOMMITTED | 1 | Mogą wystąpić odczyty brudne, odczyty niepowtarzalne i odczyty fantomowe. Jeśli wiersz zostanie zmieniony przez transakcję, inna transakcja będzie mogła odczytać te zmiany, nawet jeśli nie zostały one zatwierdzone. | 
| READ_COMMITTED | 2 | Zapobiega błędnym odczytom, jednakże mogą wystąpić odczyty niepowtarzalne i odczyty fantomowe. Ten poziom zapobiega odczytywaniu wierszy z niezatwierdzonymi zmianami. | 
| REPEATABLE_READ | 4 | Zapobiega błędnym odczytom i odczytom niepowtarzalnym. Mogą jednak wystąpić odczyty fantomowe. Oprócz zapobiegania odczytywaniu niezatwierdzonych danych, zapobiega także sytuacji, w której dwie operacje odczytu w tej samej transakcji zwracają różne wyniki. | 
| SERIALIZABLE | 8 | Zapobiega odczytom brudnym, odczytom niepowtarzalnym i odczytom fantomowym. Oprócz ograniczeń z poprzedniego poziomu zapewnia to również, że zestaw rekordów pasujących do klauzuli WHERE pozostanie niezmieniony w ramach tej samej transakcji. | 
Przeczytaj stronę Wikipedii w języku angielskim na temat Izolacja w systemach baz danych, aby dowiedzieć się więcej o integralności transakcji.
Przed użyciem usługi Database należy załadować lub zaimportować bibliotekę ScriptForge:
Aby utworzyć instancję usługi Database możesz skorzystać z metody CreateScriptService:
CreateScriptService("SFDatabases.Database", [filename: str], [registrationname], [readonly], [user, [password]]): svc
W składni opisanej powyżej możesz użyć "SFDatabases.Database" lub po prostu "Database" jako pierwszego argumentu metody CreateScriptService.
filename: nazwa pliku Base. Należy wyrazić przy użyciu notacji SF_FileSystem.FileNaming.
registrationname: nazwa zarejestrowanej bazy danych. Jeśli podano filename, nie należy używać tego argumentu.
I odwrotnie, jeśli określono registrationname, nie należy definiować parametru filename.
readonly: określa, czy baza danych zostanie otwarta w trybie tylko do odczytu (domyślnie = True).
user, password: dodatkowe parametry połączenia z serwerem bazy danych.
      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDatabase as Object
      Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      ' Uruchamiaj kwerendy, instrukcje SQL, ...
      myDatabase.CloseDatabase()
    
      from scriptforge import CreateScriptService
      myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      # Uruchamiaj kwerendy, instrukcje SQL, ...
      myDatabase.CloseDatabase()
    Dostęp do bazy danych powiązanej z dokumentem Base można także uzyskać za pomocą usługi ScriptForge.UI jak pokazano na poniższych przykładach:
      Dim myDoc As Object, myDatabase As Object, ui As Object
      Set ui = CreateScriptService("UI")
      Set myDoc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      ' Poniżej znajduje się nazwa użytkownika i hasło w razie potrzeby
      Set myDatabase = myDoc.GetDatabase()
      ' Uruchamiaj kwerendy, instrukcje SQL, ...
      myDatabase.CloseDatabase()
      myDoc.CloseDocument()
    
      ui = CreateScriptService("UI")
      doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      # W razie potrzeby poniżej podano użytkownika i hasło
      myDatabase = doc.GetDatabase()
      # Uruchamiaj kwerendy, instrukcje SQL, ...
      myDatabase.CloseDatabase()
      doc.CloseDocument()
    Metoda GetDatabase użyta w powyższym przykładzie jest częścią usługi Base ScriptForge.
| Nazwa | Tylko do odczytu | Typ | Opis | 
|---|---|---|---|
| Queries | Tak | Tablica ciągów | Lista przechowywanych kwerend. | 
| Tables | Tak | Tablica ciągów | Lista przechowywanych tabel. | 
| XConnection | Tak | Obiekt UNO reprezentujący bieżące połączenie z bazą danych. | |
| XMetaData | Tak | Obiekt UNO reprezentujący metadane opisujące atrybuty systemu bazy danych. | 
| Lista metod w usłudze Database | ||
|---|---|---|
Zamyka bieżące połączenie z bazą danych.
db.CloseDatabase()
    myDatabase.CloseDatabase() ' Basic
  
    myDatabase.CloseDatabase() # Python
  Zatwierdza wszystkie aktualizacje wykonane od poprzedniego wywołania Commit lub Rollback.
Ta metoda jest ignorowana, jeśli zatwierdzenia są wykonywane automatycznie po każdej instrukcji SQL, tj. baza danych jest ustawiona na domyślny tryb automatycznego zatwierdzania.
db.Commit()
      ' Ustaw poziom transakcji REPEATABLE_READ
      myDB.SetTransactionMode(4)
      myDB.RunSql("UPDATE ...")
      myDB.Commit()
      myDB.RunSql("DELETE ...")
      ' Przetestuj jakiś warunek przed zatwierdzeniem
      If bSomeCondition Then
          myDB.Commit()
      Else
          myDB.Rollback()
      End If
      ' Przywróć tryb automatycznego zatwierdzania
      myDB.SetTransactionMode()
    
      myDB.SetTransactionMode(4)
      myDB.RunSql("UPDATE ...")
      myDB.Commit()
      myDB.RunSql("DELETE ...")
      if some_condition:
          myDB.Commit()
      else:
          myDB.Rollback()
      myDB.SetTransactionMode()
    Tworzy instancję usługi Dataset na podstawie tabeli, kwerendy lub instrukcji SQL SELECT.
db.CreateDataset(sqlcommand: str, opt directsql: bool, opt filter: str, opt orderby: str): svc
sqlcommand: nazwa tabeli, nazwa kwerendy lub prawidłowa instrukcja SQL SELECT. Identyfikatory można ująć w nawiasy kwadratowe. W tym argumencie rozróżniana jest wielkość liter.
directsql: ustaw ten argument na True, aby wysłać instrukcję bezpośrednio do silnika bazy danych bez wstępnego przetwarzania przez LibreOffice (domyślnie = False).
filter: określa warunek, który muszą spełnić rekordy, aby zostały uwzględnione w zwróconym zbiorze danych. Argument ten jest wyrażony jako instrukcja SQL WHERE bez słowa kluczowego "WHERE".
orderby: określa kolejność zbioru danych jako instrukcja SQL ORDER BY bez słowa kluczowego "ORDER BY".
Poniższe przykłady w języku Basic i Python zwracają zestaw danych zawierający rekordy tabeli o nazwie "Customers".
      oDataset = myDatabase.CreateDataset("Customers", Filter := "[Name] LIKE 'A'")
    
      dataset = myDatabase.CreateDataset("Customers", Filter = "[Name] LIKE 'A'")
    Oblicza daną funkcję agregującą w polu lub wyrażeniu należącym do tabeli.
Opcjonalnie można określić klauzulę SQL WHERE jako filtr, który zostanie zastosowany przed funkcją agregującą.
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: wyrażenie SQL, w którym nazwy pól są ujęte w nawiasy kwadratowe.
tablename: nazwa tabeli (bez nawiasów kwadratowych).
criteria: klauzula WHERE bez słowa kluczowego „WHERE”, w której nazwy pól są ujęte w nawiasy kwadratowe.
W poniższym przykładzie założono, że plik Employees.odb zawiera tabelę o nazwie EmployeeData.
      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDB as Variant
      Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
      ' Zlicza w tabeli liczbę pracowników
      MsgBox myDB.DCount("[ID]", "EmployeeData")
      ' Zwraca w tabeli sumę wszystkich wynagrodzeń
      MsgBox myDB.DSum("[Salary]", "EmployeeData")
      ' Poniżej znajduje się kilka przykładów filtrowania tabel
      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%'"))
    Oblicza wyrażenie SQL na pojedynczym rekordzie zwróconym przez klauzulę WHERE zdefiniowaną przez parametr Criteria.
Jeśli kwerenda zwróci wiele rekordów, pod uwagę brana będzie tylko pierwsza z nich. Użyj parametru OrderClause, aby określić sposób sortowania wyników kwerendy.
db.DLookup(expression: str, tablename: str, [criteria:str], [orderclause: str]): any
expression: wyrażenie SQL, w którym nazwy pól są ujęte w nawiasy kwadratowe.
tablename: nazwa tabeli (bez nawiasów kwadratowych).
criteria: klauzula WHERE bez słowa kluczowego „WHERE”, w której nazwy pól są ujęte w nawiasy kwadratowe.
orderclause: klauzula ORDER BY bez słów kluczowych „ORDER BY”. Nazwy pól należy ująć w nawiasy kwadratowe.
      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'"))
    Przechowuje zawartość tabeli lub wyniki kwerendy SELECT albo instrukcji SQL w tablicy dwuwymiarowej. Pierwszy indeks w tablicy odpowiada wierszom, drugi zaś kolumnom.
Można określić górny limit liczby zwracanych wierszy. Opcjonalnie nazwy kolumn można wstawić w pierwszym wierszu tablicy.
Zwrócona tablica będzie pusta, jeśli nie zostaną zwrócone żadne wiersze, a główki kolumn nie są wymagane.
db.GetRows(sqlcommand: str, directsql: bool = False, header: bool = False, maxrows: int = 0): any
sqlcommand: nazwa tabeli lub kwerendy (bez nawiasów kwadratowych) albo instrukcja SQL SELECT.
directsql: gdy True, polecenie SQL jest wysyłane do silnika bazy danych bez wstępnej analizy. Wartość domyślna to False. Argument ten jest ignorowany w przypadku tabel. W przypadku kwerend zastosowaną opcją jest ta ustawiona podczas definiowania kwerendy.
header: gdy True, pierwszy wiersz zwróconej tablicy zawiera główki kolumn.
maxrows: maksymalna liczba wierszy do zwrócenia. Wartością domyślną jest zero, co oznacza, że nie ma ograniczenia liczby zwracanych wierszy.
Poniżej znajduje się kilka przykładów wykorzystania metody GetRows:
      Dim queryResults as Variant
      ' Zwraca wszystkie wiersze tabeli z główkami kolumn
      queryResults = myDB.GetRows("EmployeeData", Header := True)
      ' Zwraca pierwszych 50 rekordów pracowników uporządkowanych według pola '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)
    Otwiera określony dokument formularza w trybie normalnym. Ta metoda zwraca instancję usługi FormDocument odpowiadającą określonemu dokumentowi formularza.
Jeżeli dokument formularza jest już otwarty, aktywowane jest okno dokumentu formularza.
Jeśli określony dokument formularza nie istnieje, zwracane jest Nothing.
svc.OpenFormDocument(formdocument: str): svc
formdocument: nazwa FormDocument do otworzenia jako ciąg znaków, w którym rozróżniana jest wielkość liter.
Większość dokumentów formularzy jest przechowywana w katalogu głównym dokumentu Base i można je otwierać, używając ich nazw, jak w poniższym przykładzie:
    Dim oFormDoc As Object
    oFormDoc = myDB.OpenFormDocument("myFormDocument")
  Jeśli dokumenty formularza są zorganizowane w folderach, konieczne staje się uwzględnienie nazwy folderu w celu określenia dokumentu formularza, który ma zostać otwarty, jak pokazano w poniższym przykładzie:
    oFormDoc = myDB.OpenFormDocument("myFolder/myFormDocument")
  
    formDoc = myDB.OpenFormDocument("myFormDocument")
  
    formDoc = myDB.OpenFormDocument("myFolder/myFormDocument")
  Otwiera okno Widok danych określonej kwerendy i zwraca instancję usługi Datasheet.
Jeżeli nie można było otworzyć kwerendy, zwracane jest Nothing.
db.OpenQuery(queryname: str): obj
queryname: nazwa istniejącej kwerendy jako ciąg znaków, w którym rozróżniana jest wielkość liter.
      myDatabase.OpenQuery("MyQuery")
    
      myDatabase.OpenQuery("MyQuery")
    Uruchamia polecenie SQL SELECT, otwiera okno Widoku danych z wynikami i zwraca instancję usługi Datasheet.
db.OpenSql(sql: str, directsql: bool): obj
sql: ciąg zawierający prawidłową instrukcję SQL SELECT. Identyfikatory można ująć w nawiasy kwadratowe.
directsql: gdy True, polecenie SQL jest wysyłane do silnika bazy danych bez wstępnej analizy (domyślnie = False).
      myDatabase.OpenSql("SELECT * FROM [Customers] ORDER BY [CITY]")
    
      myDatabase.OpenSql("SELECT * FROM [Customers] ORDER BY [CITY]")
    Otwiera okno Widok danych określonej tabeli i zwraca instancję usługi Datasheet.
db.OpenTable(tablename: str): obj
tablename: nazwa istniejącej tabeli jako ciąg tekstowy z rozróżnianiem wielkości liter.
      myDatabase.OpenTable("MyTable")
    
      myDatabase.OpenTable("MyTable")
    Anuluje wszystkie zmiany wprowadzone w bazie danych od ostatniego wywołania Commit lub 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()
    Wykonuje kwerendę działania instrukcji SQL, takiej jak utworzenie tabeli, a także wstawianie, aktualizowanie i usuwanie rekordów.
Metoda zwraca wartość True, jeśli operacja się powiedzie.
Metoda RunSql jest odrzucana z komunikatem o błędzie w przypadku, gdy baza danych była wcześniej otwarta w trybie tylko do odczytu.
db.RunSql(sqlcommand: str, directsql: bool = False): bool
sqlcommand: nazwa kwerendy (bez nawiasów kwadratowych) lub instrukcja SQL.
directsql: gdy True, polecenie SQL jest wysyłane do silnika bazy danych bez wstępnej analizy (domyślnie = False). W przypadku kwerend zastosowaną opcją jest ta ustawiona podczas definiowania kwerendy.
      myDatabase.RunSql("INSERT INTO [EmployeeData] VALUES(25, 'Smith', 'John')", DirectSQL := True)
    
      myDatabase.RunSql("INSERT INTO [EmployeeData] VALUES(25, 'Smith', 'John')", directsql = True)
    Określa poziom izolacji w transakcjach bazy danych.
Domyślnie bazy danych zarządzają transakcjami w trybie automatycznego zatwierdzania, co oznacza, że Commit jest wykonywane automatycznie po każdej instrukcji SQL.
Użyj tej metody, aby ręcznie określić poziom izolacji transakcji. Gdy ustawiony jest tryb transakcji inny niż NONE, skrypt musi jawnie wywołać metodę Commit, aby zastosować zmiany do bazy danych.
Ta metoda zwraca wartość True, jeśli operacja się powiedzie.
Zmiana trybu transakcji powoduje zamknięcie wszystkich instancji Dataset utworzonych z bieżącej bazy danych.
db.SetTransactionMode(transactionmode: int = 0): bool
transactionmode: określa tryb transakcji. Argument ten musi być jedną ze stałych zdefiniowanych w com.sun.star.sdbc.TransactionIsolation (domyślnie = NONE)
Przeczytaj sekcję Obsługa transakcji powyżej, aby dowiedzieć się więcej o poziomach izolacji transakcji stosowanych w LibreOffice.
      myDB.SetTransactionMode(com.sun.star.sdbc.TransactionIsolation.REPEATABLE_READ)
      oDataset = myDB.CreateDataset("SELECT ...")
      ' ...
      ' Przywróć domyślny tryb transakcji
      myDB.SetTransactionMode()
    
      from com.sun.star.sdbc import TransactionIsolation
      myDB.SetTransactionMode(TransactionIsolation.REPEATABLE_READ)
      dataset = myDB.CreateDataset("SELECT ...")
      # ...
      myDB.SetTransactionMode()