Table of Contents
Xojo Database API in the V4RB plugin
Xojo has its own special Database API documented in the Xojo documentation: https://documentation.xojo.com/api/databases/index.html
In previous versions of Xojo or REALbasic, this was referred to as the RBDB API and to use it required that you license a version of Xojo that supports this specific API. In this documentation, we refer to this as the Xojo Database API.
Overview of Xojo Database API
The Xojo Database API is an attempt to offer a unified API to access different databases. Because of this, the API tends to be minimalistic:
- Database - main class
- RowSet - Result of SelectSQL().
- DatabaseRow - optional, helper class for Database.AddRow() method.
- PreparedSQLStatement - helper class, produced by Database.Prepare() method. Allows using SQL queries with bound parameters.
Abstract class 'Database' and set of database-specific sub-classes:
- MSSQLServerDatabase
- MySQLCommunityServer
- ODBCDatabase
- OracleDatabase
- PostgreSQLDatabase
- SQLiteDatabase
There are important differences in those classes between SQLite and others, because SQLite is a local DB engine, while others are remote DB SQL Servers.
SQLiteDatabase
class has propertydb.DatabaseFile
, which means the path on HDD to a database file. Remote DB classes usedb.DatabaseName
property to specify just database name.SQLiteDatabase
class has methodCreateDatabase()
to create database on disk andConnect()
to open. Remote DB classes haveDB.connect()
method only.
V4RB Plugin and Xojo Database API
Starting with v6.0, V4RB plugin adds support for SQLite and provides 'Xojo Database API' for 2 databases:
- Valentina DB (Local and Client to Valentina DB Server) via class
VRBDatabase
. - SQLite DB (Local and Client to Valentina SQLite Server) via class
VSqliteDataBase
.
Both these classes inherit directly from the Database class of Xojo, so all its properties and methods can be used as described in the documentation of Xojo.
Xojo Database API for SQLite
The V4RB plugin provides the following for SQLite databases:
- access to local SQLite databases
- access to the SQLite implementation in the Valentina SQLite Server portion of Valentina Server
For the purposes of support and easy porting of solutions then, we provide:
- similar API for SqliteDatabase and VSqliteDatabase classes
- similar API for local and remote work
By maintaining this similarity, it allows you to
- easily migrate existing code of your Xojo app from built-in SQLite classes to the Valentina SQLite implementation
- have the same code working with both local and client-server SQLite databases
Xojo Database API for Valentina DB
VRBDatabase Class
The Valentina implementation of this class is minimal because
- Valentina developers prefer to use Valentina Native API, which provides more power and flexibility over the limitations of the VRBDatabase Class framework
- You can switch from the
VRBDatabase
class toVDatabase
class if it is necessary to take advantage of more features
Properties:
* ConnectionTimeout as Integer * DatabaseFile as FolderItem * Port as Integer * EmbeddedSerial as String * StructureEncryptionKey as String // new since v.10.4.16 * DataEncryptionKey as String // new since v.10.4.16
Methods:
* Connect() as boolean * CreateDataBaseFile() as boolean * OpenDataBaseFile() as boolean * OpenBLOB( inTableName as string, inFieldName as string, inRowID as Int64, inReadWrite as boolean ) As VSqliteBLOB
You can easily switch from Xojo Database classes for Valentina to native Valentina API classes with the help of VDatabase.Constructor( VRBDatabase inDB )
. See Valentina Reference.pdf for details.
Example:
Dim dbFile as FolderItem Dim db as VRBDataBase db = new VRBDataBase if gClient then db.Host = "localhost" db.UserName = "sa" db.Password = "sa" db.Port = 15432 db.databaseName = filename else dbFile = GetFolderItem(filename) db.databaseFile = dbFile end if // Optionally set encryption keys: db.StructureEncryptionKey = "456" db.DataEncryptionKey = "123" if db.Connect then ...