When developing applications with Xojo, choosing the right backend is crucial for managing data efficiently. Traditionally, Xojo developers rely on SQL databases such as SQLite, MySQL, or PostgreSQL for their desktop, web, and mobile applications. However, there is an alternative that provides a more flexible and modern approach to backend development: PocketBase.

PocketBase is an open-source backend perfect for your multi-platform Xojo application. It offers a simple-to-use API and a built-in admin panel to manage the data from any web browser. No other tool such as MySQL, Workbench, or SQL Studio is needed. In this post, I will explain how it compares to traditional SQL databases and demonstrate how to integrate it into a Xojo project.

Why Choose PocketBase for Your Xojo App Backend?

PocketBase is a lightweight, self-hosted backend designed for simplicity and flexibility. Unlike traditional SQL databases that require a separate backend service or API layer, PocketBase is an all-in-one solution that combines the database and API.

Key Features:

Embedded Database – Powered by SQLite, eliminating the need for a separate database server.

Built-in User Authentication – Supports email/password logins, OAuth2 sign-ups, and one-time password (OTP) with minimal setup.

File Storage – Store and retrieve files locally or via S3.

Cross-Platform Compatibility – Runs on macOS, Windows, and Linux. Can communicate via URLConnection making it ideal for Xojo’s desktop, web, and mobile platforms.

Easy Deployment – A single binary file that can be self-hosted or deployed anywhere with minimal configuration.

Setting Up PocketBase for a Xojo App

To get started, I have simplified some steps below. If you get stuck or want more in-depth instructions take a look at the documentation.

• Download PocketBase
  • Visit PocketBase and download the latest release for your operating system.
  • Extract the files to your project directory.
• Run PocketBase
  • Start the PocketBase server by navigating to the extracted folder in the command prompt/terminal.
  • Run the command: ./pocketbase serve to start the server.
• Access the Admin Panel
  • Open http://127.0.0.1:8090/_/ in a web browser and set up an admin account.
• Add a User
  • In the PocketBase admin panel, create a new record in the users collection. (Collections are the equivalent of a table in SQL.)

Connect Xojo to PocketBase

Now that your PocketBase server is running, integrate authentication into your Xojo desktop app. In this example, we will handle authentication in the open event of the main window. This will demonstrate how Xojo interacts with PocketBase’s authentication API.

Implement the Login Request

Add the following code to the open event of your main window:

Var userEmail As String = "email@email.com"
Var userPassword As String = "MyPassword!"
Var loginURL As String = "http://127.0.0.1:8090" + "/api/collections/users/auth-with-password"
Var conn As New URLConnection
conn.RequestHeader("Content-Type") = "application/json"
 
Var loginPayload As New JSONItem
loginPayload.Value("identity" ) = userEmail
loginPayload.Value("password") = userPassword
conn.SetRequestContent(loginPayload.ToString, "application/json")
 
Var loginResponse As String = conn.SendSync("POST", loginURL)
Var jsonResponse As New JSONItem(loginResponse)
Var userInfo As JSONItem = jsonResponse.Lookup("record", New JSONItem)
Var userID As String = userInfo.Lookup("id", "")
Var authToken As String = jsonResponse.Lookup("token", "")
 
If authToken.Length > 0 Then
  MessageBox("Login successful! Welcome, User ID: " + userID)
Else
  MessageBox("Login failed. Please check your credentials.")
End If

Update Your Credentials and URL

Replace userEmail and userPassword with the credentials you used to create a user in PocketBase. Also, ensure the loginURL matches your PocketBase instance (without /_/ at the end).

Run The App

Launch your Xojo app. If authentication is successful, a message box will display the user’s ID. Otherwise, you will see an error message indicating that the credentials are incorrect.

Wrapping Up

In this article, you have successfully set up a PocketBase server, created a record, and integrated authentication into your Xojo app. PocketBase simplifies backend development by handling authentication and data storage—all without the need for a traditional SQL database.

With PocketBase, there is no need to set up complex user tables, hash passwords, or build a custom API. Collections can be easily managed directly from the web via the admin panel. This means you can spend less time managing infrastructure and more time focusing on bringing your app to market.

To help you get started, I’ve created a collection of example projects, which you can find here:

Xojo-Pocketbase-Examples

If you’d like to discuss how Iron Elephant Solutions has used Xojo and PocketBase in real-world applications, feel free to reach out through our website or add me on LinkedIn.

Ezekiel Burke is the founder of Iron Elephant Solutions. He focuses on building custom, scalable, and affordable software that helps businesses work smarter. With 15+ years of experience, he specializes in full-stack development, process automation and systems integration, creating solutions that simplify complex workflows.

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.

This article will show you how to automatically record queries and commands in any Xojo database class to help you debug and improve database operations by using method overriding. This will help you:

• Debug SQL operations faster by seeing exactly what’s being executed.
• Spot errors in your SQL queries or parameters before they become runtime issues.
• Gain transparency into your app’s database behavior.

By the end of this tutorial, you’ll have a clear understanding of:

• Method overriding: What it is and how you can use it to extend built-in Xojo classes.
• Subclassing database classes: Learn how to develop a custom database class with added logging functionality to improve database management and tracking.
• Logging SQL commands and parameters: Discover how to effectively capture and log database operations such as SELECT, INSERT, and DELETE to enhance visibility and improve database performance.

What is Method Overriding?

Method overriding, a fundamental concept in object-oriented programming (OOP), lets you customize how a subclass implements its superclass’s methods. In Xojo, this powerful feature allows you to enhance built-in classes without modifying their original code, ensuring you preserve core functionality while adding your own features.

How Method Overriding Works in Xojo

Let’s break it down step by step with a simple example. Imagine you’re working with the SQLiteDatabase class, and you want to modify the behavior of the ExecuteSQL method to log every SQL command executed.

1. Create a Subclass:
   • Create a new class in Xojo and set its Super to SQLiteDatabase. This means your new class inherits all the properties and methods of SQLiteDatabase.
2. Override the Method:
   • In your new subclass, define a method and from the Method Name picker, select ExecuteSQL.
   • Add your custom logic, like logging the SQL command to the Xojo debugger.
3. Call the Original Method:
   • Use the Super keyword to call the original ExecuteSQL method in the superclass. This ensures the original behavior is preserved alongside your custom logic.

Extending Xojo’s SQLiteDatabase with Method Overriding

Let’s enhance Xojo’s SQLiteDatabase class by creating a subclass that automatically logs SELECT queries and their parameters. To make this process easier, use the built-in “Full-Text Searching 5” example project, which already includes various database operations.

1. Create the MySQLiteDatabase Subclass

1. From the Insert menu, select Class.
2. Name the new class MySQLiteDatabase.
3. In the Inspector, set the Super field to SQLiteDatabase.

This tells Xojo that MySQLiteDatabase will inherit all the behavior of SQLiteDatabase, allowing you to override its methods.

2. Override the SelectSQL Method

Now, you’ll override the SelectSQL method in your MySQLiteDatabase class. This method is used for SELECT queries, so you’ll add logging to display the query and its parameters in the debugger.

Public Function SelectSQL(query As String, ParamArray values() As Variant) As RowSet
  // Log the SELECT query
  System.DebugLog("[DEBUG] SelectSQL called: " + query)
  
  // Log the parameters (if any)
  If values.LastIndex >= 0 Then
    Var stringValues() As String
    For Each v As Variant In values
      stringValues.Add(v.StringValue) // Convert Variant to String
    Next
    System.DebugLog("[DEBUG] Parameters: " + String.FromArray(stringValues, ", "))
  End If

  // Call the original SelectSQL method
  Try
    Return Super.SelectSQL(query, values)
  Catch error As DatabaseException
    // Log any errors
    System.DebugLog("[ERROR] DatabaseException: " + error.Message)
    Raise error // Re-raise the exception so the app can handle it
  End Try
End Function

3. Replace the Database Property

Now that you’ve created the MySQLiteDatabase subclass, you need to update the example project to use it.

1. Open Window1 in the Project Browser.
2. Locate the DB property in Window1. It is currently defined as DB As SQLiteDatabase:
3. Change the type of DB from SQLiteDatabase to MySQLiteDatabase. To do this:
   • Select the DB property.
   • In the Inspector, update the Type field to MySQLiteDatabase.

Additionally, under the Opening event of Window1, change DB = New SQLiteDatabase to DB = New MySQLiteDatabase.

This replaces the original SQLiteDatabase with your custom subclass, ensuring all database operations now use your overridden SelectSQL method.

4. Test the Logging

With the subclass in place, run the project and test the logging functionality.

1. Run the project.
2. Perform a search in the app’s UI. Each search generates a SELECT query using the SelectSQL method.
3. Check Xojo’s Messages Panel for output. You should see the SQL query and its parameters logged.

Example Output:

[DEBUG] SelectSQL called: SELECT highlight(ftstest, 0, '<', '>') FROM ftstest WHERE ftstest MATCH 'know' ORDER BY rank;

Additional Enhancements

Now that you’ve created a foundation for extending Xojo’s database classes by logging queries with your custom subclass, it’s time to think about how you can take this further. Below are several ideas for additional enhancements that will make your subclass more robust, versatile, and useful for debugging and performance monitoring.

Log Additional Methods

While you’ve started with the SelectSQL method, your app likely performs other database operations, such as INSERT, UPDATE, DELETE, or even transactions. You can override methods like ExecuteSQL to log these operations along with their parameters. Extending the logging functionality to these key methods ensures a complete picture of all database activity.

Additionally, logging transactional methods like BeginTransaction, CommitTransaction, and RollbackTransaction can help you trace when database changes are grouped together and ensure data integrity.

Tip: You can incorporate the Log4Xojo project.

Support for Multiple Database Classes

If your app uses different database types, such as MySQLCommunityServer or PostgreSQLDatabase, you can generalize your logging functionality to work with all of them. This can be achieved by creating a base class for logging that inherits from Database and then extending it for specific database types. This approach ensures consistency and reusability across different database systems.

Monitor Query Performance

Tracking the time it takes for queries to execute can give you valuable insights into your application’s performance. By measuring the duration of each query, you can identify slow queries and optimize them for better efficiency. Additionally, you could log a warning if a query takes longer than a specified threshold, helping you catch performance issues early.

Automatically Retry Failed Queries

Sometimes, database operations fail due to transient errors, such as network interruptions or locked tables. Implementing retry logic for failed queries can make your app more resilient. For example, you could attempt a query up to three times before logging it as a failure. This is particularly useful for apps that rely on remote database servers, where connectivity issues are more likely.

Add Context-Specific Metadata

Including additional context in your logs can make them more meaningful. For example, you might log:

• The name of the method or function that triggered the query.
• The user ID or session ID (if applicable) for tracking user-specific database activity.
• Tags or labels to group related queries or transactions.

This kind of metadata makes it easier to understand the “why” behind a query, not just the “what.”

Wrapping It All Up

Congratulations! You’ve taken a deep dive into one of the most powerful techniques in Xojo development: extending built-in classes, like SQLiteDatabase, to meet your specific needs. By following the steps in this tutorial, you’ve learned how to override methods, create a custom database subclass, and log SQL queries for better debugging and transparency.

What’s Next?

If you enjoyed this tutorial, we’d love to hear from you! Share your thoughts, your customizations, or any challenges you faced in the Xojo forums. If you’ve built something amazing using this technique, let us know—we’d love to feature your work in our community showcase.

Keep coding, keep innovating, and as always, happy developing!

Gabriel is a digital marketing enthusiast who loves coding with Xojo to create cool software tools for any platform. He is always eager to learn and share new ideas!

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Like 4D, Xojo has a drag and drop user interface builder, a Code Editor, a Debugger and a Compiler as well as a cross-platform framework. While 4D now has an object-oriented language as an option, Xojo has always been object-oriented. The language is a dot syntax not unlike Javascript. You do not have to become an experienced object-oriented programmer to use Xojo. One of its strengths is that you can learn incrementally.

Xojo supports database application development but there are differences between how it and 4D handles that. 4D has its own database engine and query syntax. Xojo supports SQLite, PostgreSQL, MySQL and ODBC for accessing databases. Unsurprisingly it uses SQL as its query syntax. Because 4D is solely designed for database application development, it ties the user interface you create to tables in the database. Xojo does not. 4D’s model prevents you from having to write code to get data from database records in and out of your user interface. While by default Xojo does not provide this, it provides an add-on called DBKit which assists you in connecting to and interacting with databases.

Xojo supports desktop development for Linux, macOS, Windows and Raspberry Pi (Linux on ARM). It supports web development as well and mobile development for iOS and Android. You can also build console apps which can be handy when you need an app with no user interface to run on a server. Xojo uses native controls and compiles to native machine code for x86 and ARM. Whether you come to Xojo to build desktop, web or mobile apps, you’ll find that 95% of what you learn and the code you write will be applicable to all targets. With the exception of iOS (which because of Apple’s requirements must be built from a Mac) you can build your apps from any platform to any platform. Xojo also includes a Remote Debugger which allows you to build from one operating system and run on another. For example, you might do your development on macOS but want to debug on Windows to track down a Windows-specific issue. With the Remote Debugger, this is quite easy.

Xojo is free to use for development. You only purchase a license when you need to deploy. This is a developer license, not a deployment license. That means that you can deploy as many applications as you like to as many users as you like, without any additional cost. Each developer purchases their own license. A Xojo license comes with 12 months of updates. The new Xojo releases available during your license period continue to be available to you even after your license expires. Renewing your license gets you another 12 months of updates. If you only need to deploy cross-platform desktop applications, the Xojo Desktop license is $399USD. Yearly updates are also $399USD. If you wish to build for any platform we support, the Pro license is $799USD. Yearly updates are also $799USD. Compare licenses and find more pricing details at our webstore.

If you’d like to give Xojo a spin, I recommend starting with the QuickStart and then the full tutorial. After that, check out DBKit, the video and its tutorial which will make it easier to build database-oriented applications. These are the desktop tutorials but there are also tutorials for mobile and web application development. Because Xojo is a general, cross-platform development tool rather than one specifically for database applications, what you build with it is truly limited only by your imagination. If you have any further questions, please reach out to us. Our user forum is also filled with experienced and enthusiastic Xojo users that answer and have answered hundreds of questions. And the Xojo Blog has many posts on database development with Xojo.

Geoff Perlman is the Founder and CEO of Xojo. When he’s not leading the Xojo team he can be found playing drums in Austin, Texas and spending time with his family.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

What is SOUNDEX?

SOUNDEX is a core function in SQLite that encodes a string into a 4-byte sequence, enabling indexing based on pronunciation. While the technical details of the algorithm are available on Wikipedia, the gist is that SOUNDEX(“Smith”) will match SOUNDEX(“Smythe”), making it useful for large searches to identify different spellings of the same term.

How is it used?

For the curious, you can see how words are indexed by simply invoking a select on a SOUNDEX term:

Var db As New SQLiteDatabase
db.Connect

Var rs As RowSet
rs = db.SelectSQL("SELECT SOUNDEX('Smith')")
Var smith As String = rs.ColumnAt(0).StringValue
rs = db.SelectSQL("SELECT SOUNDEX('Smythe')")
Var smythe As String = rs.ColumnAt(0).StringValue

Running this you’ll notice that ‘Smith’ and ‘Smythe’ both return the same SOUNDEX 4-byte sequence of “S530” — Here’s a quick breakdown of how this was generated:

1. First Letter (S): The first letter of the name stays the same, so “S” from the name “Smith” or “Smythe” becomes the first character in the code.
2. Numbers (530): The remaining characters in the code represent the sounds of the next letters in the name. Each number is based on a group of similar-sounding consonants:
   • 5 = “M” (because M sounds like “M” in “Smith” or “Smythe”)
   • 3 = “T” (because T sounds like “T” in “Smith” or “Smythe”)
   • 0 = No sound match or a vowel, so it acts as a filler to complete the 4-character code.

Practical Use Case

With a better understanding of the algorithm, we can put it to practical use by searching our database for names that sound similar to “Smith.”

db.ExecuteSQL("CREATE TABLE contacts(id INTEGER PRIMARY KEY, name TEXT)")
db.ExecuteSQL("INSERT INTO contacts (name) VALUES ('Smith'), ('Smythe'), ('Simith'), ('John')")

rs = db.SelectSQL("SELECT name FROM contacts WHERE SOUNDEX(name) = SOUNDEX('Smith')")

// Expected to find 3 names: Smith, Smythe, and Simith
Var namesFound As Integer = rs.RowCount

The Fuzzy Conclusion

Because the SOUNDEX algorithm is designed around English pronunciation patterns, it may not work as well for languages with different sound structures or alphabets, so results may vary depending on the language. It’s also worth noting that this feature is available for all targets, except Android at this time.

William Yu grew up in Canada learning to program BASIC on a Vic-20. He is Xojo’s resident Windows and Linux engineer, among his many other skills. Some may say he has joined the dark side here in the USA, but he will always be a Canadian at heart.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

iOS Notifications

Xojo Cloud can function as an Apple Push Notification system (APNs) for handling iOS push notifications. This works with Xojo and non-Xojo iOS apps. All Xojo Cloud servers are pre-configured to send remote notifications. Unlike many other cloud hosts, there is no extra charge for this feature nor is there any limit as to how many notifications you can send.

To send remote notifications from your iOS app you’ll need to go to the Apple Developer website to do these tasks:

1. Add the Push Notifications feature to the App ID.
2. Generate an Apple Push Services certificate.

In Xojo you need to enable the Remote Notifications entitlement for your app in the Capabilities section of the iOS Build Settings Advanced tab.

The final step is to upload your Push Services certificate using the Xojo Cloud control panel.

With super-easy access and no limits for notifications, Xojo Cloud can serve as a great APNs for handling your iOS notification needs.

Database Servers

Most desktop apps use a database of some kind and many are client/server database apps that talk directly to the database server. With Xojo Cloud you can host PostgreSQL or MariaDB/MySQL database servers and connect to them using an SSH tunnel for security purposes.

Setting up a database server on your Xojo Cloud is as easy as checking a box in the control panel.

You can turn on PostgreSQL or MySQL/MariaDB. If your Xojo Cloud server is large enough you could even do both.

If you want to access a database on Xojo Cloud from a desktop app, you will have to enable the SSH Tunnel and then connect to the tunnel from the computer. An SSH tunnel is a secure connection between your computer and another (in this case your Xojo Cloud server) which is used for transmitting data on a specific port. In essence, it creates a private connection through the internet which allows you to see into your server on the other end and connect to a particular service there.

To create a tunnel between a computer and your Xojo Cloud server, you first need to turn on the tunnel capability on your Xojo Cloud server. Go to your control panel and click the “SSH Tunnel” checkbox. You will be presented with a generated username and a password which you will use later for establishing the connection.

On macOS and Linux, you can use a terminal command to access the tunnel (replace username and ipaddress as appropriate; you’ll be prompted for the password).

Use this command to tunnel to PostgreSQL:

ssh -L 5432:localhost:5432 username@ipaddress -N

Use this command to tunnel to MySQL:

ssh -L 3306:localhost:3306 username@ipaddress -N

If you are using Windows, you will need to use an external app such as PuTTY. There are a number of tutorials available on the internet, just put “putty ssh tunnel” into your favorite search engine.

With the tunnel in place you connect to the database as if it were local to the computer. This works with anything, not just Xojo apps.

SFTP

Xojo Cloud offers SFTP (Secure File Transfer Protocol) for file transfer. SFTP is a secure variant of FTP which transmits files over the internet using strong encryption. That way you don’t have to worry about anyone intercepting your username and password or your files as they’re sent to or from your server.

When choosing a client, keep in mind that SFTP is different than FTPS or FTP w/ SSL. They are not interchangeable with one another.

Once you enable SFTP in the Control Panel, you’ll be presented with a dialog showing a generated username and password.

You can now connect using your favorite SFTP client. If you don’t have one, there are a number of free and paid options available including:

• ForkLift
• Transmit
• FileZilla
• CyberDuck

Having a place to store files online is always handy and can be useful when needing to share files with others without having to rely on services such as DropBox.

Web Services

OK, a web service is technically a Xojo web app but it is really an API that is meant to be used by other apps, often desktop or mobile apps. Since a web service doesn’t have any actual UI, you don’t really need to learn how to use the majority of the Xojo Web framework.

Instead you basically add code to the App.HandleURL event to route web service API calls to do specific tasks and then return the results, usually as JSON for the client app to handle.

A web service can be a great way to consolidate code that will be used by desktop and mobile apps, for example.

For example, you could create a Web Service that talks to a database server (such as one of the ones available in Xojo Cloud itself). Your Desktop and Mobile apps can use the same web service to work with the database. All your database-specific code lives in the web service and the client apps make requests and display results.

This is a very common design pattern these days and is a necessary one if you want a mobile app to talk to a database server.

If you want to learn more about web services, here’s a fun webinar to check out:

Learn more about Xojo Cloud today. Xojo Cloud servers start at $49/month, custom servers with more RAM, storage, and virtual CPUs are available. The best way to host your Xojo web apps is so much more than just hosting web apps!

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

Why would you need a WebDataSource, isn’t AddRow enough?

If you are making a quick prototype, or for small data sets that won’t grow too much, yes, you can absolutely place a WebListBox into your WebPage and fill it using AddRow. If your WebListBox displays a fixed, small amount of data, say around 500~1000 rows, WebDataSource can be overkill.

However, for data that comes from a large database, it’s a different story. You could waste precious server resources duplicating the same data you have in your database into your app’s memory. And even worse, the data would be duplicated in every Session seeing that WebListBox.

In this tutorial, this is the WebListBox we are going to build:

Let’s prepare a million records database to play with.

In this example we will use a humble SQLite database, but keep in mind a WebDataSource can be anything. For example you could display the result of calling an external API, or your hard drive filesystem.

The following SQL creates a table called “things”, with three columns: “foo”, “bar” and “baz” with one million rows:

CREATE TABLE things (
  id    INTEGER PRIMARY KEY AUTOINCREMENT,
  foo TEXT,
  bar TEXT,
  baz TEXT
);

-- Time to populate that table
WITH RECURSIVE cnt(x) AS 
(
   SELECT
      1 
   UNION ALL
   SELECT
      x + 1 
   FROM
      cnt LIMIT 1000000
)
INSERT INTO things (foo, bar, baz)
SELECT
    'foo_' || x AS foo,
    'bar_' || x  AS bar,
    'baz_' || x AS baz
FROM cnt;

-- Finally, let's create some indexes, so we can sort the columns quickly
CREATE INDEX "idx_foo" ON things (
    foo, id, bar, baz
);

CREATE INDEX "idx_bar" ON things (
    bar, id, foo, baz
);

CREATE INDEX "idx_baz" ON things (
    baz, id, foo, bar
);

VACUUM;

We just need to store this SQL as a string constant, for convenience. Let’s create one, called kDatabaseSetupSQLite in your Application class, and paste it above the SQL code.

First Time Setup

The first time we launch the application, we need to make sure our database file has been created and populated. It won’t take too much to generate the database, but we’ll try to do it just once anyway.

Create a new method in your App class, called DBFile, that returns a FolderItem, pointing to the place we want to store the DataBase. Make it Public, as we will use this method later from the Session. The contents:

Return SpecialFolder.Desktop.Child("test-db.sqlite")

Nothing fancy. Use another path if you want. It will be around ~200MB, just remember to delete it when you don’t need it anymore.

Let’s create another App method, called SetupDatabase. It will be in charge of creating and populating the database just once, so if you restart the server, the data will still be there:

Var db As New SQLiteDatabase
db.DatabaseFile = DBFile
db.WriteAheadLogging = True

// The file is already there, no need to build it again
If db.DatabaseFile.Exists Then
  Return
End If

db.CreateDatabase
db.Connect
db.ExecuteSQL(kDatabaseSetupSQLite)

Lastly, implement the App.Opening event and add a method call to SetupDatabase:

SetupDatabase

That should do the trick.

Preparing the Session

It’s recommended to have a Database instance for each Session. Add a new public Property to your Session class called Database of type SQLiteDatabase.

Then, add a handler for the Opening event with the following code:

Database = New SQLiteDatabase
Database.DatabaseFile = App.DBFile
Database.WriteAheadLogging = True
Database.Connect

Every time a user arrives to the web application, a new isolated SQLiteDatabase connection will be created.

Implementing the WebDataSource Interface

Since Xojo 2024r2, the amount of methods you need in order to implement WebDataSource has been reduced.

Create a new class called DatabaseDataSource. Then, in the inspector panel, select the WebDataSource interface:

This includes the three required methods: ColumnData, RowCount and RowData.

ColumnData
In this method, you need to return an array of WebListBoxColumnData. We have four columns in this example, here is the code:

Var result() As WebListBoxColumnData
result.Add(New WebListBoxColumnData("ID", "id"))
result.Add(New WebListBoxColumnData("Foo", "foo"))
result.Add(New WebListBoxColumnData("Bar", "bar"))
result.Add(New WebListBoxColumnData("Baz", "baz"))

Return result

RowCount
Xojo needs to know the amount of data your data source has. Returning an Integer is enough, but we will query our database.

Try
  Var rows As RowSet = Session.Database.SelectSQL("SELECT COUNT(*) AS counter FROM things")
  Return rows.Column("counter").IntegerValue
Catch DatabaseException
  Return 0
End Try

RowData
This is the place where you need to return the row contents. As you can see, there is a rowCount and a rowOffset parameter, meaning that we won’t need to return 1 million records. The control just loads a subset. The amount is dynamically calculated, and varies depending on the height of your WebListBox and the height of the rows.

A sortColumns parameter is also provided. If you allow your users to sort the columns, you need to use it to know the column and direction. Fortunately, this example has sortable columns. Here is the code to comply with the WebDataSource Interface:

Var sql As String = "SELECT id, foo, bar, baz FROM things"
If sortColumns <> "" Then
  sql = sql + " ORDER BY " + sortColumns
End If
sql = sql + " LIMIT " + rowOffset.ToString + ", " + rowCount.ToString

Var result() As WebListBoxRowData
Var rows As RowSet = Session.Database.SelectSQL(sql)

// This isn't needed, it's just to demonstrate how to use cell renderers
Var style As New WebStyle
style.Bold = True
style.BackgroundColor = Color.Teal
style.ForegroundColor = Color.White

For Each row As DatabaseRow In rows
  Var newRowData As New WebListBoxRowData
  newRowData.PrimaryKey = row.Column("id").IntegerValue
  newRowData.Value("id") = row.Column("id")
  newRowData.Value("foo") = row.Column("foo")
  newRowData.Value("bar") = New WebListBoxStyleRenderer(style, row.Column("bar"))
  newRowData.Value("baz") = row.Column("baz")
  result.Add(newRowData)
Next

Return result

Preparing the User Interface

You’ve reached the easiest part, building the interface takes less than a minute.

1. Drop a DatabaseDataSource control into your WebPage
2. Drop a WebListBox control into your WebPage
3. In the WebListBox Opening event, configure the DataSource

If you name your DataSource instance “MyDataSource”, this is the line of code required in the WebListBox Opening event:

Me.DataSource = MyDataSource

Here is a short video:

That’s It!

The WebListBox control, when combined with a WebDataSource, is a very robust and performant solution for displaying a large set of data.

Download the project:

Happy coding!

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Out With The Old

The old database connections were quite limiting, requiring you to create a new connection and re-enter all the parameters whenever one changed. With our new Database Connection items, you can now easily update specific connection parameters directly in the inspector.

Additionally, you can now choose whether the item will auto-connect or if you prefer to connect to it later in your code.

Connecting to a Specific Database

There are times when you need to connect to a database for debugging and testing, but for the final builds, you want to connect to your production database/server. Setting this up correctly with the old database connection method required creating two separate connection items—one for debug and one for release. With the new Database Connection items, this process is much simpler and fits more easily into the build process. You now have several new Database Connection subitems that can be customized based on the stage of your build. These subitems are linked to the Stage Code in your Shared Build Settings, ensuring that when you build a final release, your database connection uses the correct settings automatically.

Additional Database Features

In addition to this change, there are two new database APIs that may be useful to you:

1. A new method, IsConnected, has been added to the SQLiteDatabase, ODBCDatabase, PostgreSQLDatabase, and MySQLCommunityServer classes. This method returns true if the connection is still active, and false if it is not.
2. We’ve enhanced Database.AddRow with a new signature that returns the unique ID of the newly inserted row. This feature is supported for SQLiteDatabase, ODBCDatabase, PostgreSQLDatabase, and MySQLCommunityServer classes. It is recommended to use this new API instead of the deprecated SQLiteDatabase.LastRowID and MySQLCommunityServer.LastInsertedRowID

Let’s explore how the new Database.AddRow feature can assist you. Previously, only SQLiteDatabase and MySQLCommunityServer had APIs to retrieve the unique ID of the last inserted row. Now, PostgreSQLDatabase and ODBCDatabase also have this capability by using the new Database.AddRow(tableName As String, row As DatabaseRow, idColumnName As String = "") As Integer

The new aspect of this signature is the idColumnName parameter and the return value. For databases that support the SQL RETURNING clause, the idColumnName specifies the column whose value will be returned. For databases that do not support the RETURNING clause, we will use the suitable method for each specific database to return a unique value.

We recognize the significance of databases in your Xojo apps. So with these updates to database connectivity for your desktop, web and console apps, and the addition of new features, we aim to make your database programming easier and more efficient.

William Yu grew up in Canada learning to program BASIC on a Vic-20. He is Xojo’s resident Windows and Linux engineer, among his many other skills. Some may say he has joined the dark side here in the USA, but he will always be a Canadian at heart.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

What are Transactions?

A transaction is a sequence of SQL commands executed as a single unit, adhering to the ACID properties:

• Atomicity: All or none of the changes are applied.
• Consistency: The database remains in a valid state.
• Isolation: Concurrent transactions do not interfere with each other.
• Durability: Once committed, changes are permanent.

Basic Transaction Commands

SQLite supports three main commands for transactions:

• BEGIN TRANSACTION: Starts a new transaction.
• COMMIT: Finalizes changes and makes them permanent.
• ROLLBACK: Reverts changes made since the last BEGIN TRANSACTION.

Sample in Xojo

Let’s consider a banking application where money is transferred between accounts. Without transactions, inconsistencies might occur. For example, if the first update (deducting money from one account) succeeds but the second update (adding money to another account) fails, the database will be left in an inconsistent state, reflecting a transfer that didn’t fully happen. Using transactions ensures that both updates either succeed or fail together, maintaining consistency.

Var db As New SQLiteDatabase
db.DatabaseFile = FolderItem.ShowOpenFileDialog("bank.db")
If db.Connect Then
  Try
    db.BeginTransaction
    db.ExecuteSQL("UPDATE accounts SET balance=balance-100 WHERE account_number=123")
    db.ExecuteSQL("UPDATE accounts SET balance=balance+100 WHERE account_number=456")
    db.CommitTransaction
  Catch e As DatabaseException
    db.RollbackTransaction
    MessageBox("Transaction failed: " + e.Message)
  End Try
Else
  MessageBox("Failed to connect to the database")
End If

In this example, BeginTransaction starts the transaction. The UPDATE commands perform the transfer. If successful, CommitTransaction finalizes the changes. If an error occurs, RollbackTransaction reverts all changes.

Advanced Transaction Control

SQLite also offers advanced transaction modes: DEFERRED, IMMEDIATE, and EXCLUSIVE.

• DEFERRED: Default mode, acquires a write lock only when the first write operation occurs.
• IMMEDIATE: Acquires a write lock immediately upon transaction start.
• EXCLUSIVE: Prevents all other read and write operations during the transaction.

Choosing the transaction type depends on the application’s specific requirements. DEFERRED balances concurrency and consistency, while IMMEDIATE and EXCLUSIVE provide higher isolation at the cost of concurrency.

Example of Advanced Transaction

If db.Connect Then
  Try
    db.ExecuteSQL("BEGIN IMMEDIATE TRANSACTION")

    ' Perform read and write operations here

    db.CommitTransaction
  Catch e As DatabaseException
    db.RollbackTransaction
    MessageBox("Transaction failed: " + e.Message)
  End Try
Else
  MessageBox("Failed to connect to the database")
End If

In this example, an IMMEDIATE transaction ensures exclusive access from the start.

Transaction Speed Considerations

The speed of transactions in SQLite can be influenced by various factors:

• Batching Operations: Grouping multiple operations in a single transaction can significantly improve performance.
• Disk I/O: The underlying storage medium and its I/O performance impact transaction speed.
• Transaction Type: IMMEDIATE and EXCLUSIVE transactions might be slower due to locking mechanisms but provide higher isolation.

Batching multiple operations into a single transaction reduces the overhead of repeatedly acquiring and releasing locks, leading to faster execution.

Benefits of Using Transactions

Using transactions offers numerous benefits:

1. Atomicity: Prevents the database from being left in an inconsistent state due to partial updates.
2. Consistency: Ensures the integrity of the database by transitioning only to valid states.
3. Isolation: Prevents interference between concurrent transactions.
4. Durability: Ensures that committed changes are permanent, even in the event of a system failure.

By understanding and applying transactions, developers can create robust applications that handle data modifications seamlessly, minimizing the risk of errors and inconsistencies.

Based on the Ducklet Blog article. Happy coding!

Martin T. is a Xojo MVP and has been very involved in testing Android support.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

There are many ways to develop with Xojo and use database servers. You might be working on a multi-user desktop application that stores data in a database. Or you’re creating a multi-user Xojo Web application that needed to be scaled up to a couple of running instances – and use a database for data storage. Or maybe you’ve written a mobile application that connects to a Backend REST API – again possibly written in Xojo (e.g. with the open source Express, or with Xojo Web).

As a Developer

When working on such projects, you’re facing quite some challenges with the various database servers available.

• You need to have a local development environment running the database server(s).
• You want to test your application against a newer version of a database server.
• A customer reports an issue occurring with a database server version that you don’t have installed.

Developer Machine

I like to have a development machine that’s as cleaned up as possible. So I don’t like the idea of installing various servers just for some tests. It’s so tedious to clean up, update to other versions, and remove all remnants of an installation when no longer required. And I don’t want to have various services running on my machine that I don’t need all the time, as they’re just eating precious memory and slowing down the machine.

Wouldn’t it be cool if there was an easy way to spin up various database servers when needed without all the hassle? Well there is – let’s have a look at Docker and Docker Compose.

Docker Compose and Database Servers

With Docker, it’s a breeze to develop with and for various database servers.

What is Docker?

If you haven’t heard of Docker, go ahead and read their excellent Documentation: Docker – Overview. Or read my previous Guest Blog Post: Running Xojo Web Applications in Docker. I’m just going to repeat and quote some basics from the Overview to get a very brief introduction:

Docker is an open platform for developing, shipping, and running applications. It provides the ability to package and run an application in a loosely isolated environment called a container. The isolation and security allow you to run many containers simultaneously on a given host. Containers are lightweight and contain everything needed to run the application, so you do not need to rely on what is currently installed on the host.

A Docker Container is a runnable instance of an image. You can create, start, stop, move, or delete a container. By default, a container is relatively well-isolated from other containers and its host machine. You can control how isolated a container’s network, storage, or other underlying subsystems are from other containers or from the host machine. A container is defined by its image as well as any configuration options you provide to it when you create or start it.

Docker Compose is a tool for defining and running multi-container applications. It is the key to unlocking a streamlined and efficient development and deployment experience. Compose simplifies the control of your entire application stack, making it easy to manage services, networks, and volumes in a single, comprehensible YAML configuration file. Then, with a single command, you create and start all the services from your configuration file.

Docker Compose for Database Server and Administration

This sounds great. Just write a YAML configuration file, and run a database server on the host (meaning: your developer machine). And be able to start, stop, delete at any time – without messing with Preferences, Launch Daemons.

But why Docker Compose for “multi container applications”? Well, the database server is one part: one application, one running docker container. And as a developer you most likely want to have some database administration tool running, too – which again is running as an own isolated container. And in order to have both available with a single command (or by simply pressing “run” or “stop”) we’re going to “compose” these two parts so that they fit and work together.

How to Run a Database Server and Administration Tool with Docker Compose

Let’s do that and install and configure three database servers which we then can use to develop an application in Xojo to connect to:

• PostgreSQL & pgAdmin
• cubeSQL & cubeSQL Web Admin
• MariaDB & phpMyAdmin

Note: All the following configuration files are available on GitHub: jo-tools/docker.

Requirements

Obviously we need to have Docker installed. And since we’re talking about being a Developer and doing this on our own development machine we’re going to install Docker Desktop. With Docker Desktop you can later easily start, stop and delete the Containers we’re going to create. When it’s empty (no containers installed), it looks like this:

We’re now ready to get started…! But wait – there is one thing we should talk about before.

Data Storage

Where are the database servers going to store their data(bases)?

If you want to know all the details, head over to the Docker Documentation: Manage data in Docker. What we need to know is this:

Docker has two options for containers to store files on the host machine, so that the files are persisted even after the container stops: Volumes, and Bind Mounts.

Why is this important to know? Well, let’s assume we create and start a Container “PostgreSQL Server”. Think of that Container as a “virtual machine” or a bag. It can save data in there just fine. But once we delete that container or throw away that bag, then all it’s data is gone, too.

That might well be intended…! For example if you just wish to play with some tool and don’t care to keep the data you’re creating with it. However, if you’d like to easily back up that data, or update a Container from “v.15” to “v.16” and keep the previous data – then that’s when Volumes and Bind Mounts are needed.

Quoted from the docs:

Volumes
Volumes are the preferred mechanism for persisting data generated by and used by Docker containers. They are completely managed by Docker.

Bind Mounts
Data is stored in a directory on the host machine, which is mounted into the container.

Okay – two options, so what’s the difference?

The Bind Mounts are a folder on the host (your developer machine). So you can easily see them, view/edit/backup the data. It might be an option if you need easy access to these files.

The Volumes are the preferred way, since they are managed within Docker. Using Docker Desktop you can view the contents – but it’s not that simple to view/edit files in there as you can’t mount it as a volume or folder on your developer machine. Of course there are some more advanced ways, which I’m not going to explain here. So definitely the best option when you don’t need to work with and open these files with other tools, too. The other reason we don’t need Bind Mounts for our database servers is that we can just use their administration tools to import/export data such as database dumps.

Alright – now let’s start and set up some database servers.

PostgreSQL Server & pgAdmin

Let’s use the example setup with Volumes for Data Storage from here: GitHub: jo-tools/docker – local-postgres-volumes.

Download the docker-compose.yml file from my GitHub Repository and place it in a folder on your machine.

I’m going to save it in: ~/Docker/local-postgres-volumes

YAML file: docker-compose.yml
A word of precaution when writing and editing YAML files:

• Indentation is done by spaces (not by tabs!)
• Indentation has to be exact (use always 2 spaces), or expect to get syntax errors

Let’s look at the content of this docker-compose.yml.

x-common-timezone: &services-timezone Etc/UTC

name: local_postgresql
services:
  postgres-server:
    container_name: postgresql
    hostname: postgresql
    image: postgres:16-alpine
    volumes:
      - postgresql_data:/var/lib/postgresql/data
    environment:
      TZ: *services-timezone
      PGTZ: *services-timezone
      POSTGRES_PASSWORD: postgres
      POSTGRES_USER: postgres
      POSTGRES_DB: postgres
    networks:
      - local_postgresql_net
    ports:
      - 5432:5432
    restart: unless-stopped

  pgadmin:
    container_name: pgadmin4
    hostname: pgadmin4
    image: dpage/pgadmin4:8
    environment:
      TZ: *services-timezone
      PGADMIN_DEFAULT_EMAIL: admin@postgres.sql
      PGADMIN_DEFAULT_PASSWORD: admin
      PGADMIN_CONFIG_UPGRADE_CHECK_ENABLED: "False"
      PGADMIN_CONFIG_SERVER_MODE: "False"
      PGADMIN_CONFIG_MASTER_PASSWORD_REQUIRED: "False"
    networks:
      - local_postgresql_net
    volumes:
      - pgadmin4_data:/var/lib/pgadmin
    ports:
      - 5433:80
    restart: unless-stopped
    depends_on:
      - postgres-server

volumes:
  postgresql_data:
    driver: local
    name: postgresql_data
  pgadmin4_data:
    driver: local
    name: pgadmin4_data

networks:
  local_postgresql_net:
    name: local_postgresql

In the first hierarchy there are:

• x-common-timezone: &services-timezone Etc/UTC

In this extension we define a scalar value for the timezone, which will be used for the environment variables in both services. The template uses UTC (which is also the default for Docker). You can change it to your timezone, e.g.: Europe/Zurich. This might be desired if you’re going to select the current date/time from the database server later.
• name: local_postgresql

That’s the name of this “setup”. We’ll later see this in Docker Desktop’s Containers. There we can also start/stop/delete this setup at any time.
• services:

There are two services in this setup: postgres-server and pgadmin
• volumes:
And two volumes: one for the database server, and one for the administration tool.
• networks:

Both these two containers will be in the same network.

When we look at the two services postgres-server and pgadmin4:
• container_name:
The name of the Container. We’ll later see this as a sub-element of this docker-compose setup named local_postgresql
• hostname:
Think of a container as a virtual machine. Every one has its hostname. And the two containers in this setup we have placed in the same network. So they can talk to each other via hostname.
•image:
That’s basically the content of the container. We’re going to install:
• postgres:16-alpine
PostgreSQL Server in Version 16.x, running on Linux Alpine (a very lightweight one).
• dpage/pgadmin4:8
pgAdmin 4 in Version 8.x as the administration tool.
• environment:
Here the environment variables of the containers are being defined. TZ defines the Timezone, and uses the value we have defined in the extension on the very top. The other Environment Variables contain the defaults and standards – here used when the containers are being started the first time to define the default logins, users and passwords. Our PostgreSQL server will have a default login with both username and password: postgres. pgAdmin we have configured to auto-login without authentication required, and disabled update checks.
• networks:
Remember – both in the same one (defined below)
• volumes:
The format here is: volume_name:/mount/in/folder
We’re going to see these volumes later in Docker Desktop. They’ll contain the data. Usually the documentation of the Docker Images explain which folders are being used to save data, so they can be mounted here to either a Volume (or a Bind Mount).
• ports:
The format here is: host-port:container-port
For PostgreSQL Server we’re using 5432:5432, meaning that we can connect on our developer machine to Port 5432 (and this will be forwarded to the container running PostgreSQL Server, listening on Port 5432 inside the Container). pgAdmin is running on Port 80 within the Container, but we connect to it from our developer machine via Port 5433.
• restart: unless-stopped
This basically means: if you have this setup running and reboot your host (developer machine), then this setup gets restarted automatically. If you’re going to stop this setup (because you don’t need it at the time), then it’ll be stopped after a reboot, too.

Start Docker Compose Setup

As we can’t use Docker Desktop to start a Docker Compose setup (maybe this feature will be added in the future) we have to use Terminal. Change Directory to where the docker-compose.yml file is and type: docker-compose up -d

The referenced Images will be pulled, the defined network created and the Containers started.

Open the Dashboard in Docker Desktop and look at the Containers – you’ll find our setup named local_postgresql with the two Containers postgresql and pgadmin4:

They are currently up and running.
If you want to stop this setup simply press the button under “Actions”. It then will be stopped even after a reboot. And should you need to run the setup again later, just hit the button “Run” here.

Under Volumes we see the created ones:

You can click on one to see it’s contents – here the data of postgresql:

Connect With PGADMIN4
Either switch again to “Containers” and click the link “5433:80” in the column “Port” of the Container “pgadmin4” in Docker Desktop, or open a browser and go to 
http://localhost:5433.

Since this is the first launch of pgAdmin4 we need to add a server – I have given it the name “Docker”:

In the register “Connection” we have to enter the connection data:

Username and password are the default ones (remember the environment variables?). And for this local developer setup I have chosen to save the password.

The most interesting part is the hostname.

• You can’t use localhost here!

  The reason is simple: pgAdmin is running in a Container (think of it again as a virtual machine), so it’s “localhost” is the Container running pgadmin4. Not your developer machine, and not the Container where postgres is running.
• I have entered: host.docker.internal

  This is explained in the Docker Documentation: networking:
The host has a changing IP address, or none if you have no network access. We recommend that you connect to the special DNS name host.docker.internal, which resolves to the internal IP address used by the host.
• Another option would be to just use the hostname: postgresql

  And why does this work? Well – we have configured these two containers to be in the same network, and the server is running in the host named “postgresql”.

And here we go: Let’s expand the entries of the just added server “Docker”, click on the main database “postgres” and execute a query: SELECT version();

Connect with Xojo
We’re ready to use Xojo now and work on applications using our local PostgreSQL Server.
Let’s connect to our local development server running in Docker. As a simple test I have placed the following code in the Opening event of a Label:

Var db As New PostgreSQLDatabase
db.Host = "localhost"
db.UserName = "postgres"
db.Password = "postgres"
db.Port = 5432

Call db.Connect

Var rs As RowSet = db.SelectSQL("SELECT version();")
Me.Text = rs.Column("version").StringValue

Additional Information

You’ve seen how to easily spin up PostgreSQL with Docker Compose and connect to it with pgAdmin4 and Xojo. What else do we need to know?

Images
You’ll find available Images on Docker Hub. In the above setup we have used postgres and pgAdmin4. If you look at them on Docker Hub you’ll see that they provides many images. One can select them by Tag. The used Tag “postgres:16-alpine” here means that we get the latest version 16 (e.g. 16.2, and some month later maybe 16.3 or 16.4). If for some reason we want to get exactly version 16.1, then we can use the corresponding Tag, e.g. “postgres:16.1-alpine”.

A Setup using Bind Mounts
If you’re going to try the docker-compose.yml with Bind Mounts from here: GitHub: jo-tools/docker – local-postgres-bindmounts, then you’ll notice the difference in the configuration here:

volumes:
  - ./postgresql_data:/var/lib/postgresql/data

You won’t get a Volume in Docker, but instead this will create a folder named postgresql_data in the folder where you’ve placed docker-compose.yml and launched the setup with docker-compose up -d.

Docker Compose Commands
We’ve already mentioned that the first launch of a Docker Compose setup will require Terminal. The following commands are to be executed in the same directory containing the yaml file, too:

docker-compose up -d
This looks for the file docker-compose.yml, pull the images, do all the setup and launch the containers. You can also use this command to restart this setup, should you have stopped it.

docker-compose stop
Stops all services in this setup. Or do it using the buttons in Register “Containers” in Docker Desktop.

docker-compose down -v
This removes all services and volumes from this setup. Use this to get rid of all Containers, Volumes AND data. Haven’t we mentioned that – it’s super easy to clean up
You could also click the Delete buttons in Docker Desktop in both “Containers” and “Volumes” (and optionally “Images”).
If you omit the option “-v”, it will leave the Volumes in place. This might be of interest if you intend to keep the data, in case you’re going to spin up this setup again some time later.

docker-compose down
docker-compose pull
docker-compose up -d
These 3 commands will first tear down the existing containers (leaving volumes and data in place), then pull the latest versions from Docker Hub and set everything up again. Remember that we have used the Image “postgres:16-alpine”, and currently got PostgreSQL 16.2? Once PostgreSQL 16.3 is available we can execute these commands and get the latest version. Again super easy to update, isn’t it?

cubeSQL & cubeSQL Web Admin

Another popular database server for Xojo is cubeSQL. It basically adds multi-user handling (including groups, privileges, und much more) on top of SQLite.

cubeSQL is a fully-featured and high-performance relational database management system built on top of the SQLite database engine.

It is the ideal database server for both developers who want to convert a single user database solution to a multi-user project and for companies looking for an affordable, easy to use and easy to maintain database management system.

You’ll find an example setup for Docker Compose here: GitHub: jo-tools/docker – local-cubesql-volumes. To connect with Xojo you need a plugin, which can be downloaded from GitHub: cubesql/cubeSQLAdmin

cubeSQL Web Admin – Written with Xojo Web

cubeSQL has a desktop application for administration, which you’ll find in the above GitHub Repository, too. As you can guess a desktop based application is not quite convenient when it comes to an easy docker compose setup.

While I’m using Xojo for desktop and console applications for quite some time, I’ve never really used Xojo Web before. That’s why I took this opportunity and gave it a try. And behold – in very short time (most functionality in just a weekend’s leisure time) I’ve written “Xojo Web Admin“. It’s been a pleasure to create something more than just some simple examples – I like the idea of creating something useful even while learning something new. And I’ll be honest – I’ve found a couple of bugs in Xojo’s Web Framework while writing cubeSQL Web Admin, but most of them are already fixed and implemented for the next Xojo version. And finishing and polishing the project to make it available to the public also took an additional couple of evenings.

cubeSQL Web Admin is Open Source – so go ahead and have a look at the source (or even better: contribute to it by adding more features, find bugs and fix them). There might be some things of interest, such as:

• How to use Xojo Web to build an app that runs in a Docker container.
 See also this Guest Blog Post: Running Xojo Web Applications in Docker
  • A new feature added while developing GitHub: cubeSQL Web Admin: The Post Build Script builds a “Multi Architecture” Docker Image (linux/amd64 & linux/arm64v8) by building the Xojo Web App for BuildTargets Linux x86 64-bit and Linux ARM 64-bit. This allows to support running the Docker Image natively on Macs with both Intel and Apple processors.
• How to use Launch Arguments and Environment Variables for configuration. This allowed us to configure the Environment Variables in our Docker setup to preconfigure the connection data.
• The approach with subclassed WebContainer’s that implement the WebDataSource Interface. The quite generic base class cntDatasourceBase can be configured to:
  • be searchable (Main Window shows/hides the WebSearchField if the subclassed Container defines to (not) be searchable).
  • define which Fields of a RowSet should be displayed (cubeSQL uses special custom commands for administration, so we can’t select distinct columns ourselves, and there’s no paging within these custom commands).
  • define virtual Fields, which will be shown in the WebListbox, but aren’t part of a RowSet. Internally the base class uses a Dictionary Array which gets built from the RowSet, so one could use it with other external DataSources, too.
  • show the Fields in the WebListBox, while allowing each Container to override the default behaviour (see for example the Databases, which use a WebListboxImageRenderer for a virtual field – depending on a couple of Columns in the RowSet an appropriate Status Icon is being displayed).

To connect to this cubeSQL setup with Xojo I have placed the following code in the Opening event of a Label:

Var db As New CubeSQLServer
db.Host = "localhost"
db.UserName = "admin"
db.Password = "admin"
db.Port = 4430

Call db.Connect

Var rs As RowSet = db.SelectSQL("SHOW INFO FOR KEY server_version")
Me.Text = rs.Column("value").StringValue

MariaDB & phpMyAdmin

MariaDB Server is a high performing open source relational database, forked from MySQL.

You’ll find an example setup for Docker Compose here: GitHub: jo-tools/docker – local-mariadb-volumes.

I’m not going to explain much more here about MariaDB (MySQL) or phpMyAdmin here – I think you should figure out easily how to launch the Administration tool and connect to the server when looking at the contents of this docker-compose.yml. But, since it’s a widely used and well-known database server, I wanted to provide a setup for this combo, too.

As a simple test for this setup I have placed the following code in the Opening event of a Label:

Var db As New MySQLCommunityServer
db.Host = "127.0.0.1"
db.UserName = "root"
db.Password = "mariadb"
db.Port = 3306

Call db.Connect

Var rs As RowSet = db.SelectSQL("SELECT version() AS version;")
Me.Text = rs.Column("version").StringValue

For some reason the connection needs an IP Address or a Hostname (and doesn’t work with localhost).

A Word of Caution

The above setups are only intended as a local test setup – don’t use them like this for production. Even on a local developer machine you shouldn’t run the services with these simple initial login credentials, so go ahead and change them.

The purpose is to explain how Docker Compose works, and how it can help developers to easily setup up local environments to work on database applications. And of course these examples might well be a head start to those that haven’t used Docker before.

That’s All Folks!

I hope this brief introduction of how to use Docker and Database servers for and with Xojo has been helpful to some, food for thought to others.

Jürg Otter is a long term user of Xojo and working for CM Informatik AG. Their Application CMI LehrerOffice is a Xojo Design Award Winner 2018. In his leisure time Jürg provides some bits and pieces for Xojo Developers.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

This paper probably explains the biggest issue regarding SQL that persists to this day: its pronunciation.

I always flip between saying “sequel” and “ess cue ell” depending on context. The authors used SEQUEL as an acronym of Structured English QUEry Language. Over time this was referred to as Structured Query Language and the initialism of SQL took hold. Still, the pronunciation of sequel seems to have also stuck. Anyway, pronounce it how you want — I won’t judge.

I’ve sometimes seen people claim that SQL stands for Standard Query Language. As the above clearly shows, that is not true. And if you’ve used SQL at all with more than one database, you also have empirical evidence that there is not much standard about it beyond the main keywords.

The paper itself is only about 15 pages, so not long at all. I found this surprising as I expected it to be some lengthy and detailed specification written for academics.

But it’s not.

It starts by talking about the relational model of data, a somewhat new concept at the time (first described in 1969), and the predicate calculus, introducing a sublanguage called SQUARE, which strikes me a somewhat functional way of querying relational data. Math nerds do love their functional languages.

The authors then go on to introduce SEQUEL as a substitute for SQUARE and it’s here where we see the first syntax that you might recognize:

SELECT NAME
FROM   EMP
WHERE  DEPT = ’TOY’

Boolean expressions in the WHERE clause are also covered along with functions in the SELECT clause. These are all things still being used to this day.

The main justification the authors use for SEQUEL is that the concepts of predicate calculus and SQUARE require “too much sophistication for the ordinary user”. I won’t argue with that!

They drive that point home by showing how to get data results using some example queries, first by using SQUARE and then comparing to the SEQUEL equivalents. Their first query is this:

Find the names of managers who manage more than ten employees.

Note that for this example, there is a previously defined database with one of the tables as follows:

EMP (NAME, DEPT, MGR, SAL, COMM)

The SQUARE example looks like this:

I’m not going to even try to explain this. Read the paper if you’re curious.

Here’s the SEQUEL version:

SELECT   MGR
FROM     EMP
GROUP BY MGR
WHERE    COUNT (NAME) > 10

Well, now. That certainly makes more sense to me. I’ll bet that everyone reading this knows exactly how to parse out the SEQUEL command. It would actually work as-is in a database such as SQLite today!

There are other examples in the paper as well. Like I said, it’s somewhat short so you might find it to be an interesting read.

Happy 50th Birthday, SEQUEL (SQL)!!

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.

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

But before we dive into the code, this example project requires the “EddiesElectronics.sqlite” SQLite database file. You can find the Eddie’s Electronics example, along with the other example projects provided with Xojo, in the Examples section of the Project Chooser. Because I am such a kind person, you can also download it directly from this link.

And, if you want, it is also possible to download the resulting Xojo Project file (for Desktop) from this link.

I’m pretty sure you will be able to adapt the example project so it works for you with other databases too!

Helper class to the rescue!

All the work of drawing the table in the PDF document will be done by a helper class. That is, a class that we are going to use to “delegate” the work. With Xojo open and a new Desktop project created, the first thing we are going to do is add a new Class to the project (Insert > Class).

With the added Class selected in the Navigator, go to the associated Inspector Panel and use the following values:

• Name: PDFRenderer
• Interfaces: Click on the “Choose” button and select the PDFTableDataSource class interface

The just added Class will be populated with all the methods defined by the PDFTableDataSource class interface. Do not worry about them now.

Next, let’s add a few properties to our PDFRenderer class:

• Name: data
• Type: RowSet
• Scope: Protected

• Name: document
• Type: PDFDocument
• Scope: Protected

• Name: DrawingFromRowSet
• Type: Boolean
• Scope: Protected

• Name: Headers()
• Type: String
• Scope: Protected

We are going to use the DrawingFromRowSet as a flag, so the PDFRenderer knows when the table is going to be created from a RowSet. You could use any other data source, you are limited to RowSet. That’s just something you will need to implement yourself! Take it as an exercise.

Next, add a new Method to the PDFRenderer class (while still selected in the Navigator) using the following values in the associated Inspector Panel:

• Name: Constructor
• Parameters: document As PDFDocument
• Scope: Public

And type the following line of code in the associated Code Editor:

Self.Document = document

Yep, it is truly that simple. Assign the received PDFDocument object to the “Document” property of the object created from the PDFRenderer class.

Add a second method using the following values:

• Name: DrawTable
• Parameters: rs As RowSet, headers() As String
• Scope: Public

And type the following code in the associated Code Editor:

// This is the method we call on the Class to draw
// a table on a PDFDocument based on a RowSet

If document <> Nil And rs <> Nil Then

  // Assign the received RowSet to the "Data" property
  Self.data = rs

  // Assign the received headers to the "Headers" property
  Self.Headers = Headers

  // Hey! We are going to create a table from a RowSet
  // so we use a Boolean property as a flag for that
  // (Yeah, we can do it using other techniques, but this
  // is easy enough for this purpose… while leave this
  // helper class "open" enough for drawing tables based on other
  // data sources).
  Self.DrawingFromRowSet = True

  // How many columns are we going to draw?
  // Well… as many as columns in the RowSet.
  Var totalColumns As Integer = rs.ColumnCount

  // This is going to be the "drawable area" on the page
  // for the table = total page width less the left and right margins
  Var totalWidth As Double = document.Graphics.Width - 40 // 40 = 20 points left/right margins

  // Creating the PDFTable object here!
  Var table As New PDFTable

  // We want to repeat the headers on every page
  table.HasRepeatingHeader = True

  // Setting the column count for the table
  table.ColumnCount = totalColumns

  // …and the width for every column.
  table.ColumnWidths = CalculateColumnWidths(TotalWidth, totalColumns)

  // The object from this class will be the responsible
  // for handling all the methods associated with the
  // PDFTableDataSouce Class Interface
  table.DataSource = Self

  // Setting the Top and Bottom margins for the drawing
  // of the table on every PDF page
  table.TopMargin = 20
  table.BottomMargin = 20

  // …and finally we instruct the PDFDocument object
  // to draw the table!
  document.AddTable(table, 20, 0)

  // Lastly, clearing the flag
  Self.DrawingFromRowSet = False

End If

As you can see here, we are calling the “CalculateColumnWidths” method in order to get the expected string for the column widths for the PDFTable.ColumnWidths property; so add a new method to the PDFRenderer class using the following values:

• Name: CalculateColumnWidths
• Parameters: TotalWidth As Double, NumberOfColumns As Double
• Return Type: String
• Scope: Protected

And type the following snippet of code in the associated Code Editor:

Var ColumnWidth As Integer = TotalWidth / NumberOfColumns
Var s() As String

For n As Integer = 0 To NumberOfColumns-1
  s.Add(Str(ColumnWidth))
Next

Return String.FromArray(s, ",")

PDFTableDataSource Methods with RowSet data!

Let’s fill the required methods from the PDFTableDataSource class interface so they work in combination with the received RowSet.

AddNewRow Method

Add this snippet of code for the “AddNewRow” method:

If DrawingFromRowSet And data <> Nil Then

  // We are going to draw as many rows as rows are in the
  // "data" rowset
  Return rowCount <> data.RowCount

End If

As you can see, that fragment of code will only run when both conditions are meet. That is, when the “DrawingFromRowSet” is set to True and the “data” property is set to a not niled RowSet. If this is the case, we then instruct our PDFTable to set the number of rows to be drawn to the same number of rows in the RowSet.

Completed Method

This is the method that will be called once the drawing of the PDFTable has been completed. We will use it to draw the page numbers at the bottom of every page in the PDFDocument. As you probably already know, it is really easy to change the active graphic context to a given page of the PDF document using the CurrentPage property, so we will use that to iterate every one of our PDF document pages, adding the page number to it as a footer.

This is the snippet of code responsible for doing just that:

// This method is called once the table has been drawn
// so let's "print" the page number on every page
// of the PDF Document

Static pageNumber As String = "Page: "

If document <> Nil Then
  Var g As Graphics = document.Graphics

  For n As Integer = 1 To document.PageCount
    document.CurrentPage = n
    g.DrawText(pageNumber + Str(n), g.Width - g.TextWidth(pageNumber+Str(n))-20, g.Height-g.FontAscent)
  Next

End If

HeaderHeight Method

This is the method called so we can set the PDFTable the desired height for the drawing of the Header. In this case we are going to use a fixed value: 20 points. The code for that method is:

// Fixed header height
Return 20

PaintCell Method

This is the method responsible for drawing every cell of the PDFTable. It receives as parameters the Graphic context for a particular cell (so its origin is at 0,0) and the row and column values corresponding for such cell.

In this case, draw the outline of a rectangle for the cell plus the text itself retrieved from the RowSet based on the received Column value. The text will be draw vertically centered in the cell:

If DrawingFromRowSet And data <> Nil Then
  // Drawing the outer rectangle for the cell
  g.DrawRectangle(0, 0, g.Width, g.Height)

  // retrieving the text to be drawn from the RowSet,
  // using the column parameter for that.
  Var s As String = data.ColumnAt(column)

  // Centering vertically the text on the table cell
  // while the X offset is fixed at 5 points.
  g.DrawText(s, 5, g.Height / 2 + g.FontAscent / 2)

  // Have we drawn all the columns for this row?
  If column = data.ColumnCount - 1 Then

    // if that is the case, then move to the next row
    // in the RowSet!
    data.MoveToNextRow
  End If

End If

PaintHeaderContent Method

This is the method called in order to draw the Header of the table itself. It is a more simple version of the previous method. In this case, the text will be centered both vertically and horizontally on every header cell:

If column <= Self.Headers.LastIndex Then

  Var s As String = headers(column)
  g.DrawingColor = Color.Black
  g.FillRectangle(0, 0, g.Width, g.Height)
  g.DrawingColor = Color.White
  g.DrawText(s, g.Width / 2 - g.TextWidth(headers(column)) / 2, g.Height / 2 + g.FontAscent / 2)

End If

RowHeight Method

As it happen with the HeaderHeight method, this is the method called to set the height for a given row. As we did for the HeaderHeight method we are going to use a fixed value of 20 points, so type the following line of code in the associated Code Editor:

Return 20

Testing The PDFRenderer class

In order to test our PDFRenderer class in combination with a RowSet object, we need to do some additional work. First, select the Window1 window in the project Navigator and add a property using the following values:

• Name: db
• Type: SQLiteDatabase
• Scope: Private

Next, click the Window1 window in the Navigator so it is displayed in the Layout Editor. Then, drag a DesktopLabel from the Library and drop it on the left/top edge of the layout observing the aligning guides so it leaves the expected margin over the left and top edges of the Window. Use the dragging handlers of the DesktopLabel on the layout to resize it to the maximum width (once again, less the expected margins). Use the following values in the associated Inspector Panel:

• Locking: Left, Top and Right locked. Bottom, unlocked.
• Multiline: on.
• Text: This example project needs to use the EddiesElectronics.sqlite database file. Click on the button in order to select it!

The layout at this point should look like this:

Now, drag a DesktopButton from the Library and drop it below the previous Label so it is horizontally centered, using the following values in the associated Inspector Panel:

• Caption: Select EddiesElectronics database file

The finished layout should look like this:

Double click the button to add the “Pressed” Event Handler. Then, add the following code in the associated Code Editor:

Try

  // Assigning SQLite object to property
  db = New SQLiteDatabase

  // Setting the database file to the SQLite object
  db.DatabaseFile = FolderItem.ShowOpenFileDialog(".sqlite")

  // Just a simple check to see if this is the expected
  // file based on the name = "EddiesElectronics.sqlite"

  If db.DatabaseFile = Nil Or db.DatabaseFile.Name <> "EddiesElectronics.sqlite" Then Return

  //…and "connecting" to it!
  db.Connect

  // Let's select all the rows from the Customers table
  Var rs As RowSet = db.SelectSQL("SELECT FirstName,LastName,Address FROM Customers")

  // Creating a new PDFDocument Instance
  Var d As New PDFDocument

  // Creating the PDFTable renderer helper object (we pass the PDFDocument object to it in the Constructor)
  Var PDFRender As New PDFRenderer(d)

  // These will be the headers drawn in the Table
  Var headers() As String = Array("Name", "Surname", "Address")

  // And let's instruct the PDFTable renderer helper to draw the table
  // based in the SQLite database rowset we got in the previous step
  PDFRender.DrawTable(rs, headers)

  // …and save the resulting PDF File to the Desktop
  Var f As FolderItem = SpecialFolder.Desktop.Child("TableFromRowSet.pdf")

  If f <> Nil Then
    d.Save(f)
    f.Open
  End If

Catch e As DatabaseException
  System.DebugLog(e.Message)
Catch e As NilObjectException
  System.DebugLog(e.Message)
End Try

As you can see, all this does is create a new SQLiteDatabase object and assign it to the “db” property. Then, we set the “DataBaseFile” property of that object to the file selected by the user. The code will do a simple check to see if the selected file is the expected “EddiesElectronics” database file. If that is the case, then it will connect to the database, getting a RowSet from a simple query that retrieves the “name”, “surname” and “address” columns from the “Customers” database table.

After creating the PDFDocument instance, the code creates a new instance from our PDFRenderer class and calls the “DrawTable” method on that object passing along both the RowSet and the Headers we want to use for drawing the table.

Lastly, the PDFDocument will be saved to disk and opened in the by default PDF viewer app.

Run the app, select the “EddiesElectronics” SQLite database file and the resulting PDF file will be opened after a few seconds. It will display the table generated from a RowSet data source!

In Summary

It is quite possible to draw tables in a PDFDocument when the data to render comes from a RowSet. Nearly everything was done through the use of a helper class. As always, this can be improved in several ways! For example, we are using a fixed height for every row of the table, but in a more realistic scenario may be using variable heights for the table rows based in the height / amount of data to be drawn. That is something that is doable too!

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

There are four parts to this article: Part 1 prepares the server for reverse proxy, Part 2 installs the Web Application and create a Windows Service for that app, Part 3 configures the Web Site and, finally, Part 4 looks at setting up the DNS record.

These instructions have been tested on Windows 2016, 2019 and 2022 servers.  

Part 1: Preparing the Server for Reverse Proxy

1. Add the Web Server Role to your server.  This is done through the Server Manager application.  Default selections have been used.

2. Download the URL Rewrite component from https://www.iis.net/downloads/microsoft/url-rewrite and install it.
3. Download the Application Request Routing (ARR) component from https://www.iis.net/downloads/microsoft/application-request-routing and install it.

Your server is now ready to host Web Applications behind IIS.

Part 2: Installing the Web Application and Configuring the Windows Service

As Xojo built applications are stand-alone, it is simply a matter of copying the application to the server. Typically, the location will be C:\Program Files\<Your Company Name>\<Your Application Name>.

To create the Windows Service, you’ll need to run CMD As Administrator and enter the following commands.  I have used Demo Company and Demo Application.

SC Create Demo binpath= “C:\Program Files\Demo Company\Demo Application\Demo Application.exe –port=8080” Start= auto
SC Description Demo “Demo Web Application”
SC Failure Demo actions=restart/2000/restart/2000/restart/2000 reset=10
SC FailureFlag Demo 1
SC Start Demo

SC Create creates the service setting the path to the binary (executable file) specifying Port 8080 and configuring the service to start with the server.

SC Description sets the long description for the service and is optional

SC Failure configures how the controller will handle service crashes.  In this case the service will be restarted after 2seconds for the first, second and subsequent failures.  The failure count will be reset after 10 seconds.

SC FailureFlag configures the service to treat app crashes as service crashes.  Without this the controller won’t execute the failure actions set previously

SC Start simply starts the service.

Part 3: Configuring the Web Site

First, you’ll need to create the website using Internet Information Server Manager:

Next, you’ll add a reverse proxy rule using the URL Rewrite function:

Select Add Rule:

Select Reverse Proxy:

And finally configure the rule:

127.0.0.1 is the local machine and 8080 is the port configured in the service.

Part 4: DNS

For the client browsers to find the site you need to add a record to your Domain Name Server.

You can see here I’m adding a CNAME record to the DNS Manager.  The fully qualified domain name matches the website name, and the site is hosted on a machine called WebServer.  We use a CNAME record which is an alias of the WebServer A record so that if the WebServer ip address was changed all the sites would automatically follow.

Wayne Golding has been a Xojo developer since 2005 and is a Xojo MVP. He operates the IT Company Axis Direct Ltd which primarily develops applications using Xojo that integrate with Xero www.xero.com. Wayne’s hobby is robotics where he uses Xojo to build applications for his Raspberry Pi, often implementing IoT for remote control.

While our debugger is a powerful tool in helping you track down bugs in your program, there are times when tricky problems arise that go beyond the scope of what our debugger can handle. It’s times like these that PDBs can potentially come to the rescue.

So what is a PDB file? In short, PDBs are a file format developed by Microsoft for storing debugging information about a program. The most important part is how it maps each function address to its equivalent function name. Let’s take a simple example to see how this looks when we don’t have a PDB to help us.

The Offending Code

Var mb As New MemoryBlock(8)
mb.Int64Value(0) = 1
mb = mb.Ptr(0)

// At this point the MemoryBlock is pointing to memory location
// 0x1 which should not be accessible.
mb.StringValue(0, 4) = "Test"

In this example, we’re purposely causing a hard crash here by accessing memory that is not ours to access. Add the offending code somewhere in your program, i.e. in the Opening event or in the Pressed event of a PushButton. If you run this in the debugger you’ll notice that the app just quits, along with our debugger. Since our debugger has failed us here, let’s try Microsoft’s WinDbg and see if we can get any more information from it.

WinDbg

If you don’t already have WinDbg installed, you can now download this from the Microsoft Store:
https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/debugger-download-tools
For many Windows developers this is a great (and free) addition to help you track down those annoying crashes. To use this, build the Xojo app with the offending code. Run WinDbg and point it to the executable to launch. Once the process is loaded in WinDbg, hit their Go button to cause the crash.

With the app crashed, you can see the most recent stack trace where some of the last functions that were called before it crashed. This is what the stack trace looks like when no PDB exists.

Since the debugger doesn’t have the information it needs to map the address to a particular function, it’ll just report this random address which isn’t very helpful.

Generate the PDB File

Now build the app again but this time generate the PDB file. This option can be found in the Advanced build settings in Xojo 2022r2 and later.

Run the app again under WinDbg. When you cause the app to crash again, WinDbg will look for a PDB file (note: it can be tuned to look in several different places, but by default it will look at the same directory as the executable). This time when the app crashes, you should get a more readable stack trace.

PDBs in the Real World

While the scenario that we just went through isn’t the most common one in the real world, it should provide you an idea of how a PDB file can help with debugging. In a real world scenario, you as the developer, will likely store PDBs internally, maybe on a server somewhere. Each time you build your app for deployment (i.e. when your app is released to the public) you would keep this PDB somewhere. Whenever your clients/users experience crashes in your app, you can ask them to send over a minidump. The same principle applies to executables and minidumps, just load it up and run it. However, the only difference is that the minidump may need more help in locating the right PDB file.

For more information on this topic please refer to: https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/symbol-path

William Yu grew up in Canada learning to program BASIC on a Vic-20. He is Xojo’s resident Windows and Linux engineer, among his many other skills. Some may say he has joined the dark side here in the USA, but he will always be a Canadian at heart.

Xojo Pro includes support for every platform:

• Desktop – Cross-compile for Windows, macOS X & Linux.
• Web – Deploy web apps as standalone apps or to Xojo Cloud.
• Mobile – Make apps for iPhone and iPads (iOS) and Android.
• Pi – Make apps for Raspberry Pi and other single-board computers.
• Console – Make apps with no graphical user interface that run from the terminal, command line or as background processes.

In addition, Xojo Pro developers enjoy the following benefits:

• Technical Email & Phone Support
• Access to Xojo pre-releases
• License activation on 3 machines
• First access to Consulting Leads

Xojo Pro is $799 and a new license includes build access to new Xojo releases for 12 months. Your Xojo license is perpetual, but access to building apps with new Xojo releases is limited. After 12 months you can renew your access to build apps with new releases or continue building apps with the older releases, indefinitely. You are never required to renew and can do so anytime to access new features and supported platforms. Your apps built with Xojo are yours forever.

Already have a Xojo license? Upgrading it to Xojo Pro will earn you a discount. We’ve made it easy to Upgrade to Xojo Pro, just log in to your account, go to your licenses page and select the license(s) you wish to upgrade. The more licenses you select, the greater your discount. After you have selected the licenses to upgrade, choose “Upgrade to Xojo Pro” to see your personal upgrade discount in the store.

Questions about Xojo Pro or upgrading your existing Xojo licenses to Xojo Pro? Email me anytime at hello@xojo.com.

Think you need more? Look into Xojo Pro Plus, developed for businesses that depend on Xojo.

First, in order to deploy a web app you’ll need a way to access the remote server using the Terminal (macOS) or through the Command line, also a way to create and/or modify several files, and to copy files from your local computer to the remote server using (S)FTP.

Note: While we are using the “root” user for all the operations to keep the tutorial as short as possible, including files/folders/directories creation/edition and also for launching the web app, you’ll probably want to create a specific user with the proper privileges/group configuration for this. As we all know, you don’t usually want to run anything as the root user!

Though this tutorial is focused on the deployment aspects of a web app, we’ll first create a very simple web app in Xojo. Feel free to use a web app of your own. At the end of this tutorial, you’ll find deployment of more complex web apps can follow the same basic principles.

1. The Web App

This very simple app will display a message when the button is clicked.  Start the Xojo IDE and choose Web from the Project Selector window:

Click on the WebPage1 item displayed in the Navigator to access the webpage Layout Editor.

Next, drag a button from the Library panel and drop it anywhere on the Layout Editor.

With the button still selected, add the Pressed Event Handler and type this line of code in the Code Editor:

MessageBox "Hola Mundo"

The classic “Hello World” en español, this is everything the web app will do.

2. Setting the Deployment Options

Click on the Shared option found under the Build Settings section in the Navigator. Next, enter 9000 as the port under the Build Settings section in the Inspector Panel.

Note: Adding the port is not required at this time because the port can be assigned when running the app once it is deployed to the server.

3. Compile the Web App

Make sure to choose the Linux checkbox in Build Settings. Then, select X86 64 bit from the Build popup menu in the Inspector Panel.

Next, click on the Build button in Xojo’s IDE toolbar. Once the app is compiled, you’ll get a Folder/Directory with the following items inside:

This is the folder you will copy to the server. I’m using the Cyberduck app on macOS but you can choose any method you like.

4. Copying the App Folder to the Server

Make sure to copy the folder with the compiled app to the /var/XojoApps path on the server (you’ll need to create that folder/directory first). Once all the files have been copied, make sure to set 750 as the privileges value for the folder and files (choose the option to apply these recursively to all of them).

5. Installing Nginx

If the server doesn’t have Nginx already installed, install it now. Nginx is a light web server which provides more performance when compared with Apache (that is, it is able to serve more requests per second, among other improvements).

To install Nginx, access the remote server using SSH:

> SSH root@xxx.xxx.xxx.xxx

Once the new session is open, type the following commands to install Nginx:

$ sudo apt update
$ sudo apt install nginx

6. (Really) Basic Firewall Configuration

Let’s tackle the firewall. It will need to accept incoming connections from Nginx. Nginx registers itself as a ufw service during its installation. In order to simplify the deployment example, use the most restrictive option allowing only web traffic from port 80:

$ sudo ufw allow 'Nginx HTTP'

Type the following command to verify the changes:

$ sudo ufw status

The output should be similar to this (in my case access from SSH and 8080 ports are also enabled).

Note: This tutorial does not discuss web security which in the overwhelming majority of cases should be a paramount issue and not ignored. Securing a server is a very complicated process which is why we take care of the for you with Xojo Cloud.

7. Creating a New Nginx “block”

Once Nginx is installed, Ubuntu automatically starts this process, so the web server should be active already. Test this by typing:

$ systemctl status nginx

The output  should be similar to this:

Once the server is running, create a new server block. Think about this block like the virtual hosts on Apache. They will encapsulate the configuration details and will allow hosting of more than one domain on the same server.

Nginx loads these configuration files from the /etc/nginx/sites-available path. Create a new file using the nano editor:

$ sudo nano /etc/nginx/sites-available/XojoDemo

Next type the following block in the resulting new document:

server	{
listen 80;
listen [::]:80;
root /var/XojoApps/XojoDemo;
index index.html index.htm index.nginx-debian.html;

server_name xxx.xxx.xxx.xxx;

location / {
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header Host $http_host;
proxy_pass http://127.0.0.1:9000;
}
}

Replace xxx.xxx.xxx.xxx with your server IP address or the server domain (DNS record, if you have one pointing to it). We are instructing Nginx to redirect the traffic from port 80 to 9000 where our web app will be listening.

Save the file and exit nano. Next, enable the file by creating a link from the file to the sites-enabled directory where Nginx reads the configuration files:

$ sudo ln -s /etc/nginx/sites-available/XojoDemo /etc/nginx/sites-enabled/

Finally, check for syntax errors in the Nginx configuration files:

$ sudo nginx -t

If everything is Ok, then reload Nginx so it reads the configuration files again and applies the changes:

$ sudo systemctl restart nginx

8. Executing the Xojo Web App

It’s time to start our Xojo web app and test the access from the web browser of your choice. Change the current path to the one where you copied the web app. In this example:

$ cd /var/XojoApps/XojoDemo

Next, start the app by issuing the following command:

$ ./XojoDemo --port=9000

Open a new window/tab in the web browser and enter the IP address/web domain pointing to the web server. There is the web app up and running:

Congrats! Now for the harsh truth. This way of executing web apps is not ideal. Because it started from the SSH session on the server, if we exit or interrupt the SSH connection, the web app will exit and won’t be accessible anymore for anyone. This problem also results in a 504 Gateway Time-Out page served by Nginx:

In order to fix this problem, create a Service.  A service will allow the app to run without any intervention, even if there is a server interruption, for example, if the server is restarted or the app crashes.

9. Creating a Service

Type the following in the current SSH session:

$ sudo nano /lib/systemd/XojoDemoApp.service

Next, type the following snippet of text in the new, opened document (make sure to save the changes once you exit nano).

[Service]
Type=simple
Restart=always
RestartSec=3
User=root
ExecStart=/var/XojoApps/XojoDemo/XojoDemo --port=9000
[Install]
WantedBy=multi-user.target

Now that you have exited nano, and with the new service created, activate it with the following commands:

$ sudo systemctl enable /lib/systemd/XojoDemoApp.service
$ sudo systemctl start XojoDemoApp.service

Get the service status by typing the following command:

$ sudo systemctl status XojoDemoApp.service

You should get an output similar to this:

Now, you can be confident that the Xojo web app will be running even if you close the current SSH connection with the remote server and that it will restart even if the remote server is restarted or the app crashes.

If all of this seems more complex than you care to manage, Xojo Cloud is the easy, powerful and secure way to deploy web apps. Xojo does not provide support for configuring your web server for use with Xojo web apps. To read more about deploying Xojo web apps, visit the Xojo Docs Web Deployment Overview and the Web Deployment Details pages.

Developer Tools

piDog DataView is a fast and flexible list viewer and includes one year of updates.

Markdown Parser for Xojo is a class that allows you to implement the ability to parse Markdown source text into HTML + the provided CSS styles, so it can be presented on the fly over an HTML control for its use “as-is”, as a starting point for invoices, reports, templates or document conversion.

If you don’t have anything from Monkeybread Software, then this is a great deal for you! Everything is 20% off from the Complete Plugin Set, which includes 54,000+ functions, to DynaPDF for creating and editing PDF documents and more.

Mime Parser is a class for parsing emails.

The OMP Plugin allows you to easily parse Microsoft Outlook Structured Storage (.MSG) files cross-platform from Xojo.

Also offered is a Spell Checker Class to easily spell check text.

User Interface

ARWaitingView is a class to prevent the user from navigating the interface while something is downloading or doing a long process.

AXControlGrid is a complete and powerful Xojo desktop UI component for macOS and Windows that it makes possible to put Canvas-based controls in a Page or a series of Pages of a given size and, optionally, their associated captions.

AXImageCanvas greatly simplifies the task of displaying a Picture with the ability to correctly display the image maintaining its original aspect ratio, and keeping the full resolution of the picture and reference to the original FolderItem.

AXNumValidatedTF is a Xojo TextField subclass (32/64 bits) for Windows and macOS allowing the input validation of a defined numeric range, using the system Locale settings for decimal and grouping text formatting.

Antonio Rinaldi offers Doughnut, which is an extension for iOSGraphics to draw circular graphs. Additionally, iOSTableViewExtended is a subclass that adds useful features including: swipe to reload, table header and footer, customer section header and footer, contextual menus, side index, TextEdit fix and more.

GraffitiSuite All Access, Desktop and Web are on sale! They are a collection of custom components for Xojo Desktop and Web.

MBS ChartDirector lets you create professional charts in Xojo, with 30 chart and gauge types.

RubberViews from Match Software maintains the place and relative size of every control when a Window or Container Control is resized. They also offer Window Placement and Screen Extensions that are modules that let you manage windows with greater control.

Database

DataViewer Component is a collection of objects for Xojo that can easily incorporate into your own projects to give SQL Query and DML functionality for SQLite and MySQL databases along with Data Export facilities. Full source code edition also available.

The MBS SQL Plugin is an alternative database interface to Xojo that gives access to SQL databases including Oracle, Microsoft SQL Server, DB2, Sybase, Informix, InterBase/Firebird, SQLBase, MySQL, PostgreSQL, ODBC and SQLite. Also available is the MBS SQLite Extension is a plug-in for cubeSQL Server, a plug-in for SQLite Manager (sqlabs) and an extension for SQLite that you can use in all SQLite-based database engines, including the SQLiteDatabase class in Xojo.

SQLVue is the fast and easy way to manage your SQLite databases.

Distribution

App Wrapper from Ohanaware simplified the process of preparing applications for submission to the Mac App Store and deploying on websites. Get a 30-day or a 1 year single user or team update plan during this limited time offer.

BoxedApp Packer helps Xojo developers prepare a single executable file that contains all required files a Xojo application needs.

The GuancheMOS plug-in is a serial number creation and validation Engine. Also available is GuancheID, the easiest way to get a unique ID for macOS and Windows based computers, so you can use it in combination with GuancheMOS or your own software licensing scheme to make sure your software only runs on the computer the license has been generated for.

Quick License Manager protects your Xojo Windows application with licensing for trials, perpetual or subscription-based licenses.

Learning

AprendeXojo has 2 Spanish-language ebooks in the store available for $20 each during the sale: Programación Multiplataforma Xojo and SQLite.

xDev Magazine is an independent bimonthly publication focused on educating Xojo users through instruction, tutorials and programming. Score a 1 year subscription during the sale for just $40!

Shop Now

The Xojo Extras store has something for every kind of Xojo developer, whether you are learning something new or looking to save some time implementing something tricky. Take a look now to see what can help make your development life easier! The Xojo May Sale runs until midnight (CT) Friday, May 7th.

First, the performance of WAL mode (write-ahead logging) is improved when there are lots of connections all accessing the same database file. This ought to provide noticeable improvements for web apps that use SQLite databases.

If you use full text searching with FTS5, you can now enable trigram indexing to allow search terms to better match within text blocks.

A minor change is that the “substr()” SQL function can now also be called “substring()” for compatibility with SQL Server.

There are a few other performance improvements as well. Visit the SQLite site to read the official release notes.

Find more SQLite tips

memoryDB.Backup(fileDB, Nil, -1) 

Something that’s often overlooked is that you can use the Backup method to go the other way… that is, it can be used to load a disk-based database back into memory by simply swapping the parameters:

// Connect to the database file on disk
Var fileDB as New SQLiteDatabase
fileDB.DatabaseFile = SpecialFolder.Resources.Child("template.db")
fileDB.Connect

// Create the database in memory
Var memoryDB as New SQLiteDatabase
memoryDB.Connect

// "Backup" the file database into memory
fileDB.Backup(memoryDB, Nil, -1)

// Close the file database
fileDB.Close

And voila! You’ve restored the database back into memory!

For more information about this command, please see SQLiteDatabase.Backup on https://documentation.xojo.com.

First, expand the SSH tree in the categories list and select tunnels.

Add a new forwarded port, here we are using port 5432 for Postgres, but you could also use 3306 for mySQL.

Press the “Add” button to save the forward and tick the “Local ports accept connections from other hosts” checkbox.

Select the SSH tree and tick the “Don’t start a shell or command at all” checkbox. This is the bit missing from the Windows native SSH client.

Select “Session” at the very top of the categories list and enter your Xojo Cloud IP address along with a session name and Save so you’ll have this configuration available to you next time.

Now you can open the connection where you will be prompted for your SSH Username (dbadmin) & password.  If this is successful, you will be left with a terminal window that appears to do nothing – leave it open until you want to disconnect.

Once the tunnel is established you can use localhost as the host address of your Postgres or MySQL database. 

Wayne Golding has been a Xojo developer since 2005 and is a Xojo MVP. He operates the IT Company Axis Direct Ltd which primarily develops applications using Xojo that integrate with Xero www.xero.com. Wayne’s hobby is robotics where he uses Xojo to build applications for his Raspberry Pi, often implementing IoT for remote control.

When I’m working with a project that will use a database the first thing I do is create my own database class. I do this by inserting a class, giving it a name and setting its super to the engine I am going to use, for example MSSQLServerDatabase. Next, I will add a method called Constructor and make it private – I only want to be able to create an instance of this class by passing the connection parameters required by the engine. Then, I will add a second constructor that will have the connection parameters for the chosen engine. For MSSQLServerDatabases a Host, DatabaseName and optionally a Username and Password.

Public Sub Constructor(Host As String, DatabaseName As String, Optional Username As String, Optional Password As String)
  Me.Host = Host
  Me.DatabaseName = DatabaseName
  Me.UserName = Username
  Me.Password = Password
  
  Connect()
  EddiesDatabase.VersionControl(me)
End Sub

Username and Password are optional for MSSQLServerDatabases because when they are empty, Network Credentials are used.

Then I will add a Shared Method VersionControl that takes a parameter db.

Public Shared Sub VersionControl(db As Database)
  Const SelectVersion = "SELECT version FROM versioncontrol WHERE id = 1;"
  
  Var VersionRow As RowSet
  
  #Pragma BreakOnExceptions Off
  Try
    VersionRow = db.SelectSQL(SelectVersion)
  Catch DatabaseException
    // This will be because the versioncontrol table doesn't exist
    // So Create & Populate the table
    db.ExecuteSQL("CREATE TABLE versioncontrol (id INTEGER NOT NULL PRIMARY KEY, version INTEGER NOT NULL);")
    db.ExecuteSQL("INSERT INTO versioncontrol (id, version) VALUES (1, 0);")
    // And get the newly inserted row
    VersionRow = db.SelectSQL(SelectVersion)
  End Try
  #Pragma BreakOnExceptions Default
  
  Do
    Select Case VersionRow.Column("version").IntegerValue
    Case 0
      db.BeginTransaction
      db.ExecuteSQL("CREATE TABLE Customers (" _
      + "ID INTEGER NOT NULL, " _
      + "FirstName VARCHAR(30), " _
      + "LastName VARCHAR(30), " _
      + "Address VARCHAR(200), " _
      + "City VARCHAR(30), " _
      + "State VARCHAR(2), " _
      + "Zip VARCHAR(30), " _
      + "Phone VARCHAR(30), " _
      + "Email VARCHAR(100), " _
      + "Photo IMAGE, " _
      + "Taxable INTEGER, " _
      + "PRIMARY KEY(ID)" _
      + ");")
      db.ExecuteSQL("CREATE TABLE InvoiceItems (" _
      + "ID INTEGER NOT NULL, " _
      + "InvoiceNo INTEGER, " _
      + "ProductCode VARCHAR(10), " _
      + "Quantity INTEGER, " _
      + "PRIMARY KEY(ID)" _
      + ");")
      db.ExecuteSQL("CREATE TABLE Invoices (" _
      + "InvoiceNo INTEGER NOT NULL, " _
      + "CustomerID INTEGER, " _
      + "InvoiceDate DATE, " _
      + "InvoiceAmount FLOAT, " _
      + "PRIMARY KEY(InvoiceNo)" _
      + ");")
      db.ExecuteSQL("CREATE TABLE Products (" _
      + "Code VARCHAR(10) NOT NULL, " _
      + "Name VARCHAR(30), " _
      + "Price FLOAT, " _
      + "PRIMARY KEY(Code)" _
      + ");")
      db.CommitTransaction
    Case 1
      // Insert Schema Updates & SQL Commands before this line and add a New Case statement below this line
      Exit Do
    Case Else
      Var err As New RuntimeException
      err.Message = "Please upgrade your application to use this database"
      Raise err
      Quit()
    End Select
    db.ExecuteSQL("UPDATE versioncontrol SET version = version + 1 WHERE id = 1;")
    VersionRow = db.SelectSQL(SelectVersion)
  Loop
End Sub

This code creates Eddie’s Electronics tables in the Database and maintains the database schema or structure. This method is shared so it can be called from other objects.

Let us say, for example, I want to add the ability to use SQLite as the database engine. I would create the class the same way but name it EddiesSQLiteDatabase, setting its super to SQLiteDatabase, add the empty constructor making it private and add the second constructor passing the folder item for the database file and optionally the encryption key. This code will either connect to the existing database file or create a new file.

Public Sub Constructor(DatabaseFile As FolderItem, Optional EncryptionKey As String)
  // Calling the overridden superclass constructor.
  Super.Constructor()
  
  Me.DatabaseFile = DatabaseFile
  
  If DatabaseFile.Exists Then
    If EncryptionKey > "" Then
      Me.EncryptionKey = EncryptionKey
    End If
    Connect()
  Else
    CreateDatabase()
    If EncryptionKey > "" Then
      Encrypt(EncryptionKey)
    End If
  End If
  
  EddiesDatabase.VersionControl(me)
  
End Sub

You will notice I am calling the shared method EddiesDatabase.VersionControl on the EddiesDatabase class for this engine too.

The big issue with doing this in the classic framework was the use of prepared statements. I would need to update every bind type for every prepared statement in the code to allow for both engines. Of course while the Xojo code remains 100% compatible, I still need to test to ensure all the SQL statements work with the new engine and make adjustments where necessary, but that is an awful lot less work.

Wayne Golding has been a Xojo developer since 2005 and is a Xojo MVP. He operates the IT Company Axis Direct Ltd which primarily develops applications using Xojo that integrate with Xero www.xero.com. Wayne’s hobby is robotics where he uses Xojo to build applications for his Raspberry Pi, often implementing IoT for remote control.

In API 2.0, SQLSelect became SelectSQL and SQLExecute became ExecuteSQL. Additionally API 2.0 automatically uses prepared statements. Now, while they perform much the same actions, there are enhancements which make code much simpler to create and read. This is because they implement Prepared Statements under the hood.

For Example, this API 1.0 code:

Dim ps As PreparedSQLStatement
Dim rs As RecordSet

ps = Session.db.Prepare("SELECT * FROM users WHERE emailaddress = ?;")
ps.BindType(0, MSSQLServerPreparedStatement.MSSQLSERVER_TYPE_STRING)
ps.Bind(0, "wayne@axisdirect.co.nz")

rs = ps.SQLSelect()

Session.UserID = rs.Field("id").IntegerValue

Becomes:

Var rs As RowSet

rs = Session.db.SelectSQL("SELECT * FROM users WHERE emailaddress = ?;" _
 ,"wayne@axisdirect.co.nz")

Session.UserID = rs.Column("id").IntegerValue

Seven lines of code become just four and in my opinion the second is much easier to follow. A prepared statement is not required (as it is implemented under the hood), and the bind type is automatic.

That SELECT statement does not have many bindings, but here is an INSERT statement that does – API 1.0 code

Dim ps As PreparedSQLStatement
ps = Session.db.Prepare("INSERT INTO reports (title, scheduletype, dayofmonth, dayofweek, sunday, monday, tuesday, wednesday, thursday, friday, saturday, nextrun, reportfile, deliverymethod, suspended) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")

ps.BindType(0, MSSQLServerPreparedStatement.MSSQLSERVER_TYPE_STRING)
ps.BindType(1, MSSQLServerPreparedStatement.MSSQLSERVER_TYPE_INT)
ps.BindType(2, MSSQLServerPreparedStatement.MSSQLSERVER_TYPE_INT)
ps.BindType(3, MSSQLServerPreparedStatement.MSSQLSERVER_TYPE_INT)
ps.BindType(4, MSSQLServerPreparedStatement.MSSQLSERVER_TYPE_TINYINT)
ps.BindType(5, MSSQLServerPreparedStatement.MSSQLSERVER_TYPE_TINYINT)
ps.BindType(6, MSSQLServerPreparedStatement.MSSQLSERVER_TYPE_TINYINT)
ps.BindType(7, MSSQLServerPreparedStatement.MSSQLSERVER_TYPE_TINYINT)
ps.BindType(8, MSSQLServerPreparedStatement.MSSQLSERVER_TYPE_TINYINT)
ps.BindType(9, MSSQLServerPreparedStatement.MSSQLSERVER_TYPE_TINYINT)
ps.BindType(10, MSSQLServerPreparedStatement.MSSQLSERVER_TYPE_TINYINT)
ps.BindType(11, MSSQLServerPreparedStatement.MSSQLSERVER_TYPE_STRING) ' This is a datetime value, but we're going to bind a SQLDateTime String
ps.BindType(12, MSSQLServerPreparedStatement.MSSQLSERVER_TYPE_STRING)
ps.BindType(13, MSSQLServerPreparedStatement.MSSQLSERVER_TYPE_INT)
ps.BindType(14, MSSQLServerPreparedStatement.MSSQLSERVER_TYPE_TINYINT)

ps.Bind(0, TitleField.Text)
ps.Bind(1, ScheduleTypeMenu. ListIndex)
ps.Bind(2, If(ScheduleTypeMenu. ListIndex = 2, Val(DayOfMonthField.Text), 0)
ps.Bind(3, If(ScheduleTypeMenu. ListIndex = 1, Val(DayOfWeekField.Text), 0)
ps.Bind(4, If(WeekDay(0).Value, 1, 0)
ps.Bind(5, If(WeekDay(1).Value, 1, 0)

ps.Bind(6, If(WeekDay(2).Value, 1, 0)
ps.Bind(7, If(WeekDay(3).Value, 1, 0)
ps.Bind(8, If(WeekDay(4).Value, 1, 0)
ps.Bind(9, If(WeekDay(5).Value, 1, 0)
ps.Bind(10, If(WeekDay(6).Value, 1, 0)
ps.Bind(11, NextRunField.DateValue.SQLDateTime)
ps.Bind(12, ReportFileField.Text)
ps.Bind(13, DeliveryMethodMenu.SelectedIndex)
ps.Bind(14, 1)

ps.SQLExecute()

If Session.db.Error Then
  Break ' The insert statement failed for some reason - this should only happen during debugging.
End If

Becomes:

Var sql As String

sql = "INSERT INTO reports (title, scheduletype, dayofmonth, dayofweek, sunday, monday, tuesday, wednesday, thursday, friday, saturday, nextrun, reportfile, deliverymethod, suspended) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"

Try
  Session.db.ExecuteSQL(sql, _
   TitleField.Value, _
   ScheduleTypeMenu.ListIndex, _
   If(ScheduleTypeMenu.ListIndex = 2, Val(DayOfMonthField.Text), 0), _
   If(ScheduleTypeMenu.ListIndex = 1, Val(DayOfWeekField.Text), 0), _
   If(WeekDay(0).Value, 1, 0), _
   If(WeekDay(1).Value, 1, 0), _
   If(WeekDay(2).Value, 1, 0), _
   If(WeekDay(3).Value, 1, 0), _
   If(WeekDay(4).Value, 1, 0), _
   If(WeekDay(5).Value, 1, 0), _
   If(WeekDay(6).Value, 1, 0), _
   NextRunField.DateValue.SQLDateTime, _
   ReportFileField.Value, _
   DeliveryMethodMenu.ListIndex, _
   1)

Catch Err As DatabaseException
  Break ' The insert statement failed for some reason - this should only happen during debugging.
End Try

Again, a huge reduction in coding and a more readable result. You will also notice the use of a try/catch block. API 2.0 methods raise exceptions and during debugging these are invaluable as they break on the exception rather than later when your logic bug bites

The API 2.0 SelectSQL method also returns a RowSet rather than a RecordSet. The RowSet is iterable unlike the RecordSet and that makes it much more user friendly. I can’t tell you how many times I’ve run a project only to find it just sits there using all the CPU cycles it can because I forgot to call the MoveNext method.

I understand that many people using Xojo on Windows probably aren’t targeting MS SQL Server, but I believe this is changing. And as more developers target Windows and MS SQL Server, the fixes and improvements that come with API 2.0 will make this easier for them. I know they are making my life a lot easier.

Oh, and by the way, before this update this application would start with a memory usage of about 100MB and grow to >500MB over the week and then I would restart the service. Updating this project to API 2.0 resulted in ongoing memory usage of between 7.5 and 8.5MB for the running application. I suspect this is a combination of my improved coding and improvements under the hood by Xojo.

Wayne Golding has been a Xojo developer since 2005 and is a Xojo MVP. He operates the IT Company Axis Direct Ltd which primarily develops applications using Xojo that integrate with Xero www.xero.com. Wayne’s hobby is robotics where he uses Xojo to build applications for his Raspberry Pi, often implementing IoT for remote control.

If you aren’t already familiar with Xojo Cloud, it’s simple, secure, maintenance-free hosting for your Xojo web apps. 

SQLite Database Tip

For the first tip, which involves SQLite databases, this is the scenario: Let’s say you added a SQLite database to the project using a Build step and set the proper Folder/Subfolder, and then you connect to it from the Session.Opening event (or any other, for this case) in order to access its tables.

Even if you are running your Web app in local or debug mode (from the IDE) the connection to the SQLite database works, no matter if you’re typing the database file name in either upper or lowercase. Remember, when you are deploying the database to Xojo Cloud, you need to pass along the database name using the proper lowercase and uppercase characters in its original name.

Let’s suposse that the original database name on disk is “MyPrettyDatabase.sqlite”, then you’re using the following code in order to connect to it:

#if DebugBuild then
    f=SpecialFolder.Desktop.Child("myprettydatabase.sqlite")
#else
    f=specialfolder.documents.child("myprettydatabase.sqlite")
#EndIf

BBDD.DatabaseFile=f

Try

    BBDD.Connect

catch e as IODatabaseException

End Try

In this case, when running the web app from your computer everything will work fine (because most desktop operating systems use a case-insensitive file system, although Linux is often case-sensitive); but if you deploy the web app to Xojo Cloud you’ll find yourself with a database that does not connect. Fixing this is as simple as typing the string representing the database filename observing the uppercase characters existing in its original name:

#if DebugBuild then
    f=SpecialFolder.Desktop.Child("myprettydatabase.sqlite")
#else
    f=specialfolder.documents.child("MyPrettyDatabase.sqlite")
#EndIf

    BBDD.DatabaseFile=f

Try

    BBDD.Connect

catch e as DatabaseException

End Try

SQLite Tip: Xojo 2020r1 updated to SQLite 3.31.1, which adds some cool new features!

MySQL/MariaDB Database Tip

The second problem we’re solving involves the connection with MySQL/MariaDB databases hosted on a remote server from your Xojo Cloud app.

Although connecting to a remote MySQL database is well documented here, let’s review. If you need to establish this kind of connection, remember to open the Xojo Cloud firewall port first.

For example, something like this code snippet will let the web app work when deployed on Xojo Cloud and when you are doing a local test running it from the IDE (debug mode):

#If TargetXojoCloud
    Var fwp As New XojoCloud.FirewallPort(3306, XojoCloud.FirewallPort.Direction.Outgoing)
    fwp.Open
    If fwp.isOpen Then
        connectDatabase
    End If
#Else
    ConnectDatabase
#EndIf

Where, in this case, ConnectDatabase is the method in charge of doing the real connection setting the usual parameters agains the MySQLCommunityServer instance.