I first created Storm in 2008 when I was working on consulting projects as a way to more rapidly create database apps for clients. It has been updated over the years and the latest version is available on GitHub:

Storm

An ORM lets you write code like this to set database column values and save them:

Var dodgers As New Team
dodgers.Name = "LA Dodgers"
dodgers.Coach = "Dave Roberts"
dodgers.Save

Team is a table in the database with a corresponding class in Xojo that inherits from Storm.DBObject.

The included demo projects shows how you can implement a simple UI for a database with Team and Player tables.

The docs for Storm are contained within its Github repository wiki.

In addition to accessing the full repository on GitHub, you can also download Storm as a ZIP.

I’ve created a forum topic for you to start sharing your Year of Code projects and I’ll also be sure to include this one as well. Remember, participants can win a $100 to use in the Xojo Store!

Paul learned to program in BASIC at age 13 and has programmed in more languages than he remembers, with Xojo being an obvious favorite. When not working on Xojo, you can find him talking about retrocomputing at Goto 10 and on Mastodon @lefebvre@hachyderm.io.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Year of Code Project

• Year of Code: Kickoff
• January Project: Desktop Apps | Forum Discussion
• February Project: Database Apps | Forum Discussion
• March Project: Web Apps | Forum Discussion
• April Project: User Interface | Forum Discussion
• May Project: Mobile Apps | Forum Discussion
• June Project: Code Sharing | Forum Discussion
• July Project: Charting | Forum Discussion
• August Project: Console Apps | Forum Discussion
• September Project: Games | Forum Discussion
• October Project: Multi-Platform | Forum Discussion
• November Project: PDF | Forum Discussion

How to Play:

Each month we’ll announce a new theme and share an example project of our own. Share your projects to the Xojo Forum thread for that month via GitHub (all the links you need are posted above ↑ ). Learn how to use Xojo and GitHub.

The Prizes:

Monthly winners get $100 at the Xojo store. Every month you submit a project is another chance to win the grand prize. The grand prize is $250 cash plus a Xojo Pro license and a year of GraffitiSuite and will be announce in December. Learn more about the prizes.

Functions

There are a few new SQLite functions that can now be used in your SQL statements.

concat()

The concat() function takes an arbitrary number of string parameters and concatenates them all together. Previous versions of SQLite required you to instead use the concat operator, this is the double-pipe: ||. Concat() is a standard function on many other databases (PostgreSQL, MySQL and SQL Server) so it is nice to finally see it available on SQLite as it allow more consistent SQL code.

Using the Chinook sample database, this SQL concatenates the Name and Composer columns from the Track table:

SELECT concat(Name, ‘ by ‘, Composer) FROM Track

Here is the output:

concat_ws()

The concat_ws() method is concat but with a separator. Strange naming aside, it works the same except that the first parameter is used a separator that is inserted between each string. This SQL separates the Name, Composer and Milliseconds with “—“:

SELECT concat_ws(‘---‘, Name, Composer, Milliseconds) FROM Track

Here is the output:

timediff()

The timediff() function calculates the elapsed time between two dates and returns the result in a human-readable format.

This SQL displays the time difference between Dec 12, 2023 and March 26, 2024:

SELECT timediff('2023-12-12','2024-03-26')

Here is the output of 3 months and 14 days (note that it is negative because the earlier date is first in the parameter list):

Other Changes

Overall I didn’t notice many other other significant new features. However, many bugs have been fixed, especially around database integrity checks and the somewhat new JSON support.

You can find the full list of SQLite changes on their Release History page.

Paul learned to program in BASIC at age 13 and has programmed in more languages than he remembers, with Xojo being an obvious favorite. When not working on Xojo, you can find him talking about retrocomputing at Goto 10 and on Mastodon @lefebvre@hachyderm.io.

Database Support

Xojo works with a wide variety of databases. SQLite is bundled with your Xojo license and is a great beginner database for desktop, web and mobile apps. Xojo includes direct support for SQLite, PostgreSQL and MySQL. Plus, you can use ODBC to connect to just about anything else, such as Oracle, MS-SQL Server, Microsoft Access, Firebird or even IBM iSeries.

Examples

To help you get started, there are many examples in the Examples/Databases folder included with the Xojo Download, including examples that connect to each of the supported databases. You can find a breakdown of the examples included in the Examples folder in the Xojo Programming Language Documentation.

Additionally, you can check out the Eddie’s Electronics sample app (located in Examples/Sample Applications/EddiesElectronics) to see how to share database code between Xojo desktop and Xojo web apps.

DBKit is an example project designed to make it easier to build desktop and web applications that are front-ends to databases. Specifically, DBKit makes it easy to connect a database table to the user interface controls on a layout. DBKit also handles a lot of the interface for you. You can read more about DBKit in the Xojo Documentation.

Read: Documentation

After you have reviewed the examples, the Database Overview in the Xojo Documentation will help with next steps. Remember, Xojo comes bundled with SQLite which is an excellent database for desktop, web and mobile apps. Read more about using SQLite in the Xojo Documentation and check out this SQLite Tutorial for more detail.

Watch: Videos

The Xojo YouTube channel has hundreds of videos on all things Xojo. Here are the most recent Xojo Database videos and playlists:

• Video: Connecting to a Database from Xojo
• Video: Updating a Database from Xojo
• Video: Querying a Database from Xojo
• Video: Managing the UI when Updating a Database
• Video: Using DBKit to easily connect databases to Xojo applications
• Playlist: Using Databases with Xojo – A growing, catch-all playlist for videos related to Xojo and databases.
• Playlist: Xojo and SQLite – SQLite comes bundled with Xojo and is a great database for beginners building desktop, web and mobile apps with Xojo.

Vendor Documentation

Lastly, you should always refer to the vendor-specific documentation for the database you are using to learn the specifics about how that database works, including SQL syntax.

• SQLite
• PostgreSQL
• MySQL
• Oracle Database
• Microsoft SQL Server

Xojo simplifies the development process, reduces complexity and empowers developers to create efficient and functional database applications with relative ease. The Xojo IDE is free to use for development and testing – design, develop, run and debug your app all without a license. Purchase a license when you are ready to compile your apps, licenses start at $149. Visit the Xojo Store to find the license right for your project.

If you have questions after you have reviewed these materials, the Xojo Forum is an accessible and essential resource for Xojo users of all levels. You can also contact Xojo directly with your questions.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

• STRICT tables
• PRAGMA table_list
• RIGHT and FULL OUTER JOIN
• Built-in JSON support

More about each of these below.

STRICT Tables

One of SQLite’s most unusual capabilities is that it does not care about what data goes into a column. Although you could specify a type for a column, it was really more of a suggestion as other types of data could be put into the column. This behavior is different than most other relational databases and can sometimes be a source of confusion.

Now you can create your tables using the STRICT keyword to force them to require column types and to force the column types to always be checked when putting data into them.

You are still limited to INT, INTEGER, REAL, TEXT and BLOB. That means there is still no DATE or DATETIME type like you might find in other databases. Instead use TEXT with YYYY-MM-DD format.

However, an ANY type was added which essentially allows you to clearly state that the column can contain anything. This allows you to have a mixture of specific types and generic types in your STRICT tables.

Note that the STRICT keyword goes at the end of the CREATE TABLE command:

CREATE TABLE Team (ID INTEGER, Name TEXT, Coach TEXT, City TEXT, PRIMARY KEY(ID)) STRICT;

The SQLite docs have more information about the new STRICT table feature.

PRAGMA table_list

With Xojo you could always get the list of tables by using the Database.Tables() method. However if you wanted to get the list of table using SQL you had to directly query the sqlite_master table.

Now there is a simple PRAGMA that can do the same thing:

PRAGMA table_list

It returns a list of tables and some other details about the table (which may change over time according to the SQLite docs).

RIGHT and FULL OUTER JOIN

Joining tables is a common task with SQL. The most common type of join is an INNER JOIN where only the rows common to both tables are included in the result. Other less common types of joins include LEFT OUTER, RIGHT OUTER and FULL OUTER (sometimes OUTER is omitted when referring to these types of joins).

SQLite has had support for LEFT OUTER joins for a long time, but support for RIGHT OUTER and FULL OUTER were missing. But now they are here, giving your more complicated queries better compatibly with the “big name” databases.

Learn more about these types of joins at W3 schools.

JSON Support

I’ve saved the big one for last: your SQL databases can now work with JSON data within columns.

Here is a sample table to work with with some JSON data that is stored in the players column:

CREATE TABLE team(id INTEGER PRIMARY KEY, Name TEXT, players TEXT);

INSERT INTO TEAM VALUES (NULL, 'Seagulls', '[ {"Name":"Bob","position":"1B"}, {"Name":"Tom","position":"2B"} ]')

INSERT INTO TEAM VALUES (NULL, 'Pigeons', '[ {"Name":"Bill","position":"1B"}, {"Name":"Tim","position":"2B"} ]')

INSERT INTO TEAM VALUES (NULL, 'Crows', '[ {"Name":"Betty","position":"1B"}, {"Name":"Tina","position":"2B"} ]')

Let’s say you want to get the first player on each team. Without SQLite JSON support you would have to pull out the JSON column data and parse it out separately. But now you can do it with this SQL like this:

SELECT players -> 0 FROM team

The above SQL says: for each row fetch the first array element from the JSON data in players.

This is how you would list all the players on all the teams:

SELECT team.Name, json_each.value -> 'Name' FROM team, json_each(team.players)

And if you want to get the actual value without the quotes, you can use the ->> operator (and also rename the result):

SELECT team.Name, json_each.value ->> 'Name' As PlayerName FROM team, json_each(team.players)

The SQLite JSON support can do much, much more which you can read about on the SQLite JSON doc page.

Paul learned to program in BASIC at age 13 and has programmed in more languages than he remembers, with Xojo being an obvious favorite. When not working on Xojo, you can find him talking about retrocomputing at Goto 10 and on Mastodon @lefebvre@hachyderm.io.

• RETURNING on DELETE, INSERT and UPDATE commands
• ALTER TABLE DROP COLUMN
• EXPLAIN QUERY PLAN

RETURNING Clause

The RETURNING clause can be used on DELETE, INSERT and UPDATE commands to get a value back after the command has run without having to do a separate query.

For example, you could send an UPDATE command that recalculates a value and have it return the new value like this:

UPDATE sales SET amount = amount * 2 WHERE ID = 1 RETURNING amount

This would now return the newly calculated amount, where as you would previously have to issue a separate SELECT statement to get the amount.

This example would append ” the Great” to the end of all names in the Artist table and return the new name along with the ID:

UPDATE Artist SET Name = Name || + " the Great" RETURNING Name, ArtistId

To access the RETURNING value from Xojo, you’ll want to send the command using SelectSQL instead of ExecuteSQL so that you can use a RowSet to get the values.

DROP Column

SQLite has historically been pretty inflexible when it comes to modify a table’s structure after it has been created. Until recently you could only rename a table and add new columns to it. Back in SQLite 3.25, the ability to rename existing columns on a table was added. And now you can also remove (drop) columns from a table.

You can do this using the standard syntax like this:

ALTER TABLE MyTable DROP COLUMN OldColumn;

Query Plan

A query plan describes how SQLite processes your SQL query. It is really only useful for debugging purposes. If you have a slow-running query it can sometimes be useful to look at the query plan to see if it is pointing out an obvious problem with the query, which might be that the query is doing a table scan rather than using an index.

To see a query plan, you put EXPLAIN QUERY PLAN in front of the SQL query. This features has been in SQLite for a long time, but it has recently gotten some output improvements that might make it easier to use. Be sure to give it a try.

As an example, here is how to get the query plan for a simple query using the AlbumArtist view in the Chinook database:

EXPLAIN QUERY PLAN SELECT * FROM AlbumArtist

The query plan looks like this, with separate rows returned for each evaluation:

To learn more about using SQLite with Xojo, check out these additional resources: Xojo SQLite Database Documentation, Tutorial: SQLite Basics, Blog Post: 3 Steps to Seamlessly Deploy SQLite Projects on Desktop, Web & iOS and Blog Post: Backwards SQLite Backups.

1. Adding the Database File

You probably created your SQLite database file using an external editor; so first add that file to your Xojo project. You can do that in several ways, but usually it’s best to add a Build Step. This way, the file will be automatically added to the folder every time you compile your app. Bonus: Doing this allows you to decide to use different paths when debugging or deploying your app.

Adding a Build Step in Xojo is the same for Desktop and Web projects. Select the target in the Build Settings then from the contextual menu choose the “Add to Build Settings > Build Step > Copy Files” option.

This gives you access to the Inspector Panel for the just-added item where you can enter a name for the Build Step, choose if the copy file action will be executed both for debugging or deployment and, most importantly, choose the location where the file should be copied when the app compiles.

The Destination menu contains a number of typical paths (or most relevant folders). For example, a good destination option would be “Resources Folder”. Don’t forget to add the database file itself using the buttons on the Build Editor toolbar.

On iOS, adding a Build Step is nearly the same as for Desktop and Web. The only difference is that you have to choose the icon with an iPhone picture in it in order to access the Build Step contextual menu> In addition to that, every added resource needs to be signed with a certificate.

2. Copying the Database File to a “Working” Folder

You may think that adding a Build Step is all you need to do, because if the database file is already copied to a well known path then you only need to provide that path as the DatabaseFile property on a new SQLiteDatabase instance. But this is not the case.

They are many reasons you shouldn’t do that, notably because the database would be open in read/write mode and if you write to that database file inside an application bundle, then you’d be modifying a resource and that would invalidate any certificate signature on your app.

The best thing to do is to check every time you run the app to see if the database file has already been copied from the app bundle (or folder) into a target folder that doesn’t have an access problem when it is time to use the database. The Application Support folder is a good place for Desktop apps, while the Documents folder is fine for Web and iOS apps.

For example, if our database file is named “EddiesElectronics.sqlite” and our app name is “Xojotest”, then we can add the following code fragment into the Opening Event Handler of a Desktop app. Also, make sure to add the pDatabase property to the App object in the Navigator:

Var source As FolderItem = SpecialFolder.Resource("EddiesElectronics.sqlite")
Var name As String = app.ExecutableFile.name.NthField(".", 1)

// Check if there is a folder with the App name in special Application Data
// if not, create it and copy the database file from Resources bundle/directory
If Not (SpecialFolder.ApplicationData.Child(name).Exists And SpecialFolder.ApplicationData.Child(name).IsFolder) Then SpecialFolder.ApplicationData.Child(name).CreateFolder

If Not SpecialFolder.ApplicationData.child(name).child(source.name).exists Then source.CopyTo(SpecialFolder.ApplicationData.Child(name))

Try
  // Create a SQLiteDatabase instance and try to open our database file from
  // the path
  pDatabase = New SQLiteDatabase
  pDatabase.DatabaseFile = SpecialFolder.ApplicationData.Child(name).Child("EddiesElectronics.sqlite")
  pDatabase.Connect

Catch e As DatabaseException
  MessageBox(e.Message)
End Try

For an iOS app, the code would be:

Var source As FolderItem = SpecialFolder.Resource("EddiesElectronics.sqlite")
// Check if our database file already copied on the Documents Sandbox folder
// if not, copy the database file from Resources bundle/directory

If Not SpecialFolder.Documents.Child("EddiesElectronics.sqlite").Exists Then
  source.CopyTo(SpecialFolder.documents)
End If

Try
  // Create a SQLiteDatabase instance and try to open database file from
  // the path
  pDatabase = New SQLiteDatabase
  Var f As FolderItem = SpecialFolder.Documents
  pDatabase.DatabaseFile = f.Child("EddiesElectronics.sqlite")
  Call pDatabase.Connect
  
Catch e As RuntimeException
  MessageBox(e.Message)
End Try

If you’re working on Xojo Cloud, the code is even shorter. First, make sure that the Copy File Build Step has the following values in the Inspector Panel:

• Destination: Contents Folder
• Subdirectory: Documents

Then, the code will be:

Try
  pDatabase = New SQLiteDatabase
  pDatabase.DatabaseFile = SpecialFolder.Documents.Child("EddiesElectronics.sqlite")
  pDatabase.Connect
Catch e As RuntimeException
  MessageBox(e.Message)
End Try

What about a Web app that you host? That would mean you are in control of the folder/directory you want to use to store the app resources. Thus, it wouldn’t make much sense to automate this process (but it is certainly doable following the same principles).

3. Simplifying the Process

What we have just done works, but it means you need to change the database file name, probably for every app you build. It also means that you’ll be writing the same code snippet again and again in every new app. Wouldn’t it be great to be able to extend the SQLiteDatabase in order to simplify that?

Well, let’s do that! Start by adding a new Module to the example project (for example, one named “DatabaseExtensions”) with a couple of methods on it. The first method will be the one executed on our Desktop, Web and Console apps, because all of these targets use the SQLiteDatabase class.

Add a new method using the following signature in the just-created Module:

OpenDatabase(databaseName As String)

It extends the SQLiteDatabase class, adding a new method that takes as parameter the name of the file we want to copy on the “work” folder/directory.

The code you should type on this method is:

pDatabase = New SQLiteDatabase

#If TargetDesktop Or TargetConsole Or TargetWeb Then

  Var source As FolderItem = SpecialFolder.Resource(databaseName)
  Var name As String = app.ExecutableFile.name.NthField(".", 1)
  // Check if there is a folder with the App name in special Application Data
  // if not, create it and copy the database file from Resources bundle/directory
  If Not (SpecialFolder.ApplicationData.Child(name).Exists And SpecialFolder.ApplicationData.Child(name).IsFolder) Then
SpecialFolder.ApplicationData.Child(name).CreateFolder
If Not SpecialFolder.ApplicationData.Child(nam).Child(Source.name).Exists Then source.CopyTo(SpecialFolder.ApplicationData.Child(name))

  Try
    // Create a SQLiteDatabase instance and try to open database file from
    // the path
    pDatabase.DatabaseFile = SpecialFolder.ApplicationData.Child(name).Child(databaseName)
    pDatabase.Connect

  Catch e As DatabaseException
    MessageBox(e.Message)
  End Try

#ElseIf TargetXojoCloud
  Try
    pDatabase.DatabaseFile = SpecialFolder.Documents.Child(databaseName)
    pDatabase.Connect
  Catch e As RuntimeException
    MessageBox(e.Message)
  End Try
#EndIf

Of course, we need to add the “pDatabase” property to our Module too: pDatabase As SQLiteDatabase

Now, you’ll only need to use:

OpenDatabase("EddiesElectronics.sqlite")

With the method selected in the Project Browser, click on the Attributes section of the Inspector Panel (the Cog Wheel icon), and uncheck the “iOS 64” checkbox. This way, that method will not be included when compiling for iOS apps.

The second method is the one we will be using for iOS apps. The method signature would be:

OpenDatabase(databaseName As String)

Type the following fragment of code in the associated Code Editor:

pDatabase = New SQLiteDatabase

Var source As FolderItem = SpecialFolder.Resource(databaseName)

// Check if the database file is already copied on the Documents Sandbox folder
// if not, copy the database file from Resources bundle/directory

If Not SpecialFolder.Documents.Child(databaseName).Exists Then
  source.CopyTo(SpecialFolder.Documents)
End If

Try
  // Create a SQLiteDatabase instance and try to open database file from
  // the path
  
  Var f As FolderItem = SpecialFolder.Documents 
  pDatabase.DatabaseFile = f.Child(databaseName)
  pDatabase.Connect
  
Catch e As RuntimeException
  MessageBox(e.Message)
End Try

Lastly, and with the method item still selected in the Navigator, go to the Attributes section of the Inspector Panel and make sure that the “iOS 64” checkbox is the only one selected under the “Include In” section. This way, we make sure that the method will be compiled only on iOS targets.

To Summarize

The use of Modules in combination with OOP Class Extension is a good way to get more flexibility when developing your apps, no matter if you are working on Desktop, Web or iOS. And that leads to convenient reutilization of code and less code to maintain through all your projects!

(You can find this article in Spanish here)

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube