Press Release

SQLite Migrator Web Site

On-Target Reports: $200

The oldest and most mature of the reporting solutions. It is a set of encrypted REALbasic classes that you drop in your project. A report designer is also included.

Report Framework: Free

These open-source classes were originally developed by Keith DeLong of RedCort software. They do a good job of abstracting out the hard stuff, but there is not a lot of functionality. It might be useful for some simple reporting, however.

Valentina Reports: $400

Introduced in early 2009, this reporting tool only works the Valentina Database. It includes a very slick report designer.

RSReport: $86

Introduced in late 2008, this reporting tool is a set of encrypted REALbasic classes. It doesn’t include a report designer, so you’ll be creating all your reports in REALbasic code. It has a decent amount of features and is updated regularly, but documentation is only in German.

Einhugur Reports: $200

Included as part of the Einhugur tools suite, but pricing has not yet been finalized as it is still in early alpha stages.

TurboReport: $Price not set

Also still in development stages, but looks to have some nice features.

Update (Jun 5, 2009):

rbrw-core

A REALbasic report writer based on OOFILE.

And lastly, REAL Software announced in their June newsletter that they are working on a reporting component that will be part of the IDE itself.

It works great with Access, FoxPro, MySQL and just about any database you might be using.

Check it out here:

SQLite Migrator

REAL SQL Database (REALSQL) is the single-user database engine included with REALbasic. It is based on SQLite 3 (http://www.sqlite.org), a fast and powerful embedded open-source database engine.

REALSQL supports all the SQL commands that SQLite supports:

In order to start working with any of these exciting SQLite commands, you need to create a REALSQL database. This is not hard at all as we’ll see with some sample code. All access to REALSQL databases is coincidentally done through the REALSQLDatabase class. Once we have an instance of that class, we can assign it to a folder item and choose to create a new database. For example:

Dim testDb As New REALSQLDatabase
Dim testDbFile As New FolderItem("TestDb.rsd")
 
testDb.DatabaseFile = testDbFile
 
If testDb.CreateDatabaseFile Then
	// Database is now available for use
Else
	MessageBox("Unable to create the database.")
End If

We can now use testDb to execute SQLite commands. For example to create a simple table, we would use this command:

CREATE TABLE simple ( firstName TEXT, lastName TEXT, age INTEGER )

This REALbasic code will send the above command to our database:

Dim result As Integer
result = testDb.SQLExecute("CREATE TABLE simple ( firstName TEXT, lastName TEXT, age INTEGER );")

Now we are ready to start talking about the Table commands. The three table-related commands (ALTER TABLE, CREATE TABLE and DROP TABLE) do what their names suggest: create new tables, alter (or change) existing tables, and drop (delete) existing tables.

Creating Tables

As we briefly saw above, the CREATE TABLE command is the first one you would need to use after creating the database. After all, a database without any tables is not of much use! If you go to the official SQLite documentation page for CREATE TABLE (http://sqlite.org/lang_createtable.html), you’ll see great detail about what this command can do for you. We’ll try to focus on a few practical examples here.

All tables contain a unique primary key (_rowid), but you should really create your own unique key as well. Although these _rowid values are unique, they can change when rows are deleted. If you rely on them as your only key, you’ll be in big trouble if you try to use them as foreign keys! These primary keys are stored in 64-bit integers, so the sun will go cold before you would run out of key values. Use the type of INTEGER PRIMARY KEY to create your primary key.

Columns can be either NULL or NOT NULL. NOT NULL columns must have a value. Columns can also have defaults which are automatically assigned to the column when a row is created and no other value is specified.

Let’s create a table to store URLs for a fictional bookmark database (refer to the sidebar for information on SQLite data types):

CREATE TABLE bookmark (ID INTEGER PRIMARY KEY, URL TEXT NOT NULL, Description TEXT)

SQLite also has the ability to create temporary tables. As the name suggests, temporary tables are not permanent and will only be available for the while you are connected to the database; once the connection is closed, the table disappears.

Changing a Table

SQLite provides some basic ways to change a table after you have created it. Specifically, you are allowed to rename the table or to add new columns to the table. SQLite does not yet provide a way to remove a column from a table. Renaming a table is not something you will likely do often, but adding new columns is something that is quite useful.

Keep in mind that if you want to add a NOT NULL column to a table, then you’ll also need to provide a non-NULL default value.

// Rename the table

ALTER TABLE bookmark RENAME TO bookmarks

// Add a column to track how often the URL is visted, defaulting to 0

ALTER TABLE bookmarks ADD Visits INTEGER NOT NULL DEFAULT 0

Removing a Table

In SQL-speak, the word DROP is used as a synonymn for remove. The DROP TABLE command is not one you should use often or lightly. Dropping a table throws all the data in the table away. You will not be able to get the data back. The syntax is quite simple:

DROP TABLE bookmarks

Note that dropping a table does not actually reduce the size of your database file. SQLite retains the space so that it can be used later by other tables as they grow. Consider this a teaser for a future column: the VACUUM command can be used to reclaim unused space.

In our next column we’ll look at the commands for adding and manipulating data in tables.

A Note About Data Types

SQLite works with datatypes quite differently than you might expect. Enough so that it is worth taking a little time to explain it. To be brief, the datatypes in SQLite are really more like guidelines. The SQLite documentation refers to them as “affinities”. Regardless of the type that you specify, a column can store any type of information. If you have a column with an INTEGER type and you try to assign it ‘REALbasic’, SQLite will simply store ‘REALbasic’ in the column.

As far as I know, SQLite is the only database that works this way. None of this is a huge problem, it’s just a bit odd. This does mean you need to be careful when attempting to do math on columns that you think might contain numbers.

The types available to you are TEXT, NUMERIC, INTEGER, and BLOB. For more information, visit the SQLite web site.

Now that we know what stored procedures are, let’s take a look at a few more examples. The accompanying Code Listing shows a simple stored procedure for MySQL, PostgreSQL, OpenBase, FrontBase, SQL Server and Oracle. As mentioned last time, the various syntax is similar but also just different enough to be annoying.

How is this related to REALbasic?

REALbasic does not provide a built-in way to call stored procedures, and it provides a nice set of database classes that work with a wide variety of databases. I guess you could say that REALbasic is encouraging you not to use stored procedures at all. That’s not entirely true, but most languages do make it a bit easier to work with them. For example, with VB.NET and ADO.NET you can use the ExecuteNonQuery method to call a stored procedure. Java with JDBC also provides a way to call stored procedures.

In the case of REALbasic, you’ll need to use the appropriate syntax for your database server to call the stored procedure using SQL.

For example, with Microsoft SQL Server (on Windows, connected via ODBC) you would use this code to run a stored procedure called INSERT_TEST:

mySQLServerODBCDatabase.SQLExecute("exec INSERT_TEST")

For Oracle you should enclose the stored procedure call in a block:

Dim spString As String
spString = "BEGIN" + EndOfLine + "INSERT_TEST" + EndOfLine + "END"
myOracleServerDatabase.SQLExecute(spString)

Of course, this technique provides no way for you to easily pass parameters to the procedure and certainly no easy way to get results or parameters back. A workaround for sending parameters would be to insert them directly into the string, which will work for simple datatypes. You could also insert your parameters into a special parameter table and then have the stored procedure look for them there. For return values and results, you could also insert the information into a table and then have your app get it with a SQL SELECT.

Obviously this doesn’t help you a whole lot of you are trying to hook up a REALbasic application to an existing database with stored procedures, which you may not be able to modify. One solution to this dilema is to create new wrapper procedures for the existing stored procedures. Your REALbasic code calls the wrapper which either puts or retrieves the data in the parameter tables and then can call the original stored procedure.

Using JDBC and MonkeyBread

Another option that has recently become available is to use the JDBC classes that are part of the Java plugin included in the MonkeyBread Plugin Suite. It contains a class, JavaCallableStatementMBS, specifically for calling stored procedures. Unfortunately the documentation and examples do not cover this feature well. It looks like you have to set up your parameters individually and then call the procedure using executeQuery.

OpenBase SQL 10

I should note that OpenBase SQL 10 has the ability to create stored procedures using REALbasic. This is not well documented, but apparently REALbasic console applications can be run as stored procedures on the database server.

Stored Procedure Code Samples

Oracle PL/SQL

CREATE PROCEDURE INSERT_TEST AS
BEGIN
INSERT INTO testlog (name, connectTime, status)
VALUES ('Bob Roberts', SYSDATE, 'Active');

COMMIT;

END;

SQL Server T-SQL

CREATE PROCEDURE INSERT_TEST AS
INSERT INTO TestLog (name, connectTime, status)
VALUES ('Bob Roberts', GetDate(), 'Active')

RETURN

GO

PostgreSQL PL/pgSQL

:

CREATE PROCEDURE INSERT_TEST AS
BEGIN
INSERT INTO testlog (name, connectTime, status)
VALUES ('Bob Roberts', now(), 'Active');

COMMIT;

END;

MySQL

CREATE PROCEDURE INSERT_TEST()
BEGIN
INSERT INTO TestLog (name, connectTime, status)
VALUES ('Bob Roberts', CURRDATE(), 'Active');
END

OpenBase OpenScript

START TRANSACTION TRY
REQUIRE EXECUTE SQL "INSERT INTO TestLog (name, connectTime, status) VALUES ('Bob Roberts', CURRDATE(), 'Active')"
REQUIRE COMMIT
CATCH
ROLLBACK
END TRY

FrontBase Stored Procedure

create procedure INSERT_TEST()
BEGIN
INSERT INTO TestLog (name, connectTime, status)
VALUES ('Bob Roberts', CURRDATE(), 'Active');
END;

If you find yourself working with database servers, you may be wondering about stored procedures. Depending on who you talk to, stored procedures are either something you should definitely be using or something you should avoid like the plague. As with most things in life, the answer is not quite so simple.

What is a Stored Procedure?

A stored procedure (SP) is code that runs on the database server. Generally this code is written in a language that is proprietary to the database server you are working with. Some database servers may support more than one store procedure language. Figure 1 is a table of some common database servers and their corresponding stored procedure languages.

I’ll be focusing on the SQL-type programming languages as they are much more commonly used.

Code Listing 1 shows you how a very simple stored procedure looks with PostgreSQL. This is a very simple example that justs inserts a row of data into a log table. The syntax across the various databases is similar, but different enough to be annoying when you work with more than one. They become much less similar when you start working with variable declarations, datatypes and control structures.

As their name implies, stored procedures are procedure-oriented, not object-oriented. They’re not called stored objects, after all. This means there is no support for things like inheritance. Oracle has a little support for data encapsulation with its Stored Packages, but we won’t go into those now. Also note that if you did choose to work with other stored procedure languages, you would get to use object-oriented features, but as I mention above these are not widely used.

Why Should You Use Them?

Stored procedures use a language you probably don’t know and are usually not object-oriented, so why would you consider using them? Well, stored procedures can be quite fast and therefore are frequently used to improve the performance of a database application. Since the code lives right alongside the database, you eliminate almost all network traffic and can allow the database server to work to its fullest.

Another benefit of stored procedures is that they can provide a nice way to encapsulate business logic near the data it is modifying. This can be useful if you expect to have several ways to access data (perhaps both a desktop and web application) and want to ensure a consistent API. It is easier and less error-prone to update this business logic once on the server rather than by updating multiple applications.

Lastly, if you’ve paid a lot of money for expensive database server software, it seems silly to not use all the features it can provide.

Why Should You Avoid Them?

The primary reason to not use stored procedures is that they are not portable. Using stored procedures effectively locks you into using a single database vendor. If you need your application to run on a different vendor’s server, then you’ll need to recreate all your stored procedures. This can be a huge amount of work or can be completely impractical depending on the database servers you use.

Wrapping Up

I’ve worked on projects and products with hundreds of stored procedures, just a few stored procedures, and no stored procedures. The rule I generally follow now is to not rely on stored procedures during initial design and development. I design my applications so that they could work with any database backend. As the product is nearing completion, I review areas that may need performance improvements to see if a stored procedure would make sense . If so, I’ll add the ability to use a stored procedure while at the same time retaining the ability to work without the stored procedure.

Next time we’ll look at more examples of stored procedures using syntax for several different database servers. We’ll also look at how stored procedures can be used with REALbasic.

Simple PostgreSQL PL/pgSQL Stored Procedure

CREATE PROCEDURE INSERT_TEST AS
BEGIN
INSERT INTO testlog (name, connectTime, status)
VALUES ('Bob Roberts', now(), 'Active');

COMMIT;

END;

Figure 1: Databases and Stored Procedure Languages

FrontBase is a full-featured database server that is available for Mac OS X, Linux and Windows. It was created by a Denmark company and was initially release just for Mac OS X. But in 2004, it went cross-platform with releases for Windows, Linux (and Unix). And as of April 15, 2006 FrontBase is available for free, with no usage restrictions. You can purchase support services from them, however.

Currently at version 4.2.9, FrontBase has many features you’d associate with a professional database server, including:

• SQL 92 support
• Stored procedures
• EncryptionREALbasic native plug-in
• Terabyte databases
• Backups
• Indexing
• Migration from MySQL and FileMaker

Installation

The FrontBase download is quite small (only 4.5MB for Windows, 14.6MB for OS X) and installation was straightforward and fast although I did get an error about a missing web component from the Windows installer. Even though FrontBase is free, you do have to go to the trouble of creating an account on the FrontBase web site to get a free license key. You have to request a separate key for each platform and also need to specify either the IP address or MAC address of the computer it will be installed on. Unless your server has a static IP address, it looks like the MAC address is the way to go. Of course obtaining your MAC address could be tricky. On Windows, type IPCONFIG /all and look for the line that says “Physical Address”. On Mac OS X, it is in your Network Preference panel. If you use Linux, I’m sure you can find it on your own.

Once you have this license you need to apply it to FrontBase by cutting and pasting it into a text file and putting this file in the FrontBase folder (\usr\FrontBase). Although this was not the most complicated database installation I’ve had to do, it certainly wasn’t the easiest either.

Database Administration

To access FrontBase, you use either the included SQL92 command line or the Java-based FrontBase JManager, but I had trouble getting that to connect (at least on Windows). The SQL92 command line gives you full control over the database server and the databases it is server, but you’ll obviously need to learn the commands (and there are plenty).

The JManager tool looks decent enough, although it suffers from its odd Java UI. They should really create a version of this in REALbasic.

Documentation

No documentation is installed to your machine, but you can download the 230 page user’s guide (in PDF format) from their web site. Since FrontBase uses SQL 92, you can find some books about that on Amazon. I didn’t find any FrontBase-specific books on Amazon, however. There also was not much information about FrontBase that I could find using Google.

Connecting to REALbasic

I created a sample database by starting the FrontBase SQL92 command line and entering these commands, one on each line:

create database firstdb;
connect to firstdb user _system;
create user test;
commit;
disconnect current;

This gives us a new database, called firstdb, with a user, called test. Now let’s see how easily we can connect to FrontBase using REALbasic. After downloading version 1.92 of the plugin (which, I’m am pleased to see, supports Mac OS X (including Universal Binaries), Windows and Linux), I copied it to the REALbasic plugins folder and started REALbasic (Professional 2008 Release 5). Keep in mind that in order to use databases besides REAL SQL Database, you need to have REALbasic Professional.

In a new blank project, add a PushButton to the default window and switch to its Action event. Add this code:

Dim firstDb As New FBDatabase
 
firstDb.Host = "localhost"
firstDb.DatabaseName = "firstdb"
firstDb.UserName = "test"
 
If firstDb.Connect Then
    MsgBox "Connected!"
Else
    MsgBox "Could not connect."
End If

Run the app and click the button. If everything is set up correctly, then you should get the “Connected!” message.

Now it works just like any other database. You can use firstDb.SQLSelect to process SELECT statements on database tables and you can use SQLExecute to run commands on the database.

Summary

If you can get past the slightly annoying installation, FrontBase seems like it would be worth a look. You’ll probably have to use the command-line, at least for some things, even if you can get the JManager tool to work. The only other database server that is also cross-platform, works with REALbasic and is completely free is PostgreSQL.

Scott Keith of OpenBase was kind enough to pass along the license information for this edition and has given me permission to publish it here:

Serial Number: OBEMBREALBASIC-639
Authorization Code: P-10-10.0-528-67E-A7C

This license works with either the Mac OS X or Windows versions, but not the Linux version.

Download OpenBase SQL

Mapping entities to tables is fairly straightforward. Typically each entity becomes a table and each attribute becomes a column. You may have to do a few adjustments of table and column names to meet any restrictions of the specific database you are using. Also keep in mind that not every database has the exact same datatypes so some changes may be necessary there as well.

Creating the SQL

Refer to the entities we created last time:

There’s nothing fancy in the team entity (except that we’ll use varchar instead of string), so it’s table create statement looks like this:

CREATE TABLE team (KEY INTEGER PRIMARY KEY NOT NULL, name TEXT NOT NULL, coach TEXT)

The key column is what is called an artificial primary key. It is used in place of the team name so that we can more easily allow for changes to the team name after it has been used in other relationships.

The location entity is also simple, here is its create table statement:

CREATE TABLE location (KEY INTEGER PRIMARY KEY NOT NULL, 
FIELD TEXT NOT NULL, lights TEXT, address TEXT)

The game table is a bit more complicated because of the relationships. Each of the relationships translates to a column in the game table. These columns are referred to as a foreign keys.

CREATE TABLE game (KEY INTEGER PRIMARY KEY NOT NULL, 
hometeam INTEGER, awayteam INTEGER, location INTEGER, gamedate DATE, gametime TIME)

I have used gamedate and gametime in place of date and time because most database systems do not like it when you use a reserved word as a column name.

Creating the Database

You have the option of creating the actual database and the tables using the REALbasic IDE, but we’re here to learn SQL so we’ll going to actually use the CREATE TABLE commands from above. Unfortunately, REALbasic’s built in database tool only allows for interactive SELECT statements and not CREATE TABLE or any of the other SQL commands. So for these examples we will use the free SQLite Database Browser, an open-source browser that works on Windows, Mac OS X and Linux.

Once you have started SQLite Database Browser, click on the leftmost icon to create a new database file and enter a name for the database. For this example we’ll use Softball.rsd. Click Cancel on the Create Table window that appears. We’ll be creating our tables using SQL.

Now click the Execute SQL tab. You can enter the CREATE TABLE commands from above (one at a time) and press the Execute query button. Each time you successfully create a table it will appear in the table list on the left.

After you have created the 3 tables, it’s time to add some sample data to them. We’ll use the SQL INSERT command to do this. These commands add data to the team table. Enter one at a time into the Execute SQL tab:

INSERT INTO team (name, coach) VALUES ("Ducks", "Paul" ) 
INSERT INTO team (name, coach) VALUES ("Bears", "David" ) 
INSERT INTO team (name, coach) VALUES ("Lions", "Vin" ) 
INSERT INTO team (name, coach) VALUES ("Tigers", "Julie" ) 
INSERT INTO team (name, coach) VALUES ("Dogs", "Laura" ) 
INSERT INTO team (name, coach) VALUES ("Cats", "Jim" )

We are not inserting any key values because we are letting SQLite handle that for us automatically. Now let’s add some data to the location table:

INSERT INTO location (FIELD, lights, address) VALUES ("Hadlock Field", "Yes", "Downtown" ) 
INSERT INTO location (FIELD, lights, address) VALUES ("Payson Park", "No", "Back Cove" )

And finally let’s add some games. This first command creates a game between the Ducks (Key = 1) and the Bears (Key = 2) at Hadlock Field (Key = 1):

INSERT INTO game (hometeam, awayteam, location, gamedate, gametime) 
VALUES (1, 2, 1, "2003-06-01", "05:00:00" )

This command creates a game between the Tigers (Key = 4) and the Dogs (Key = 5) at Payson Park (Key = 2):

INSERT INTO game (hometeam, awayteam, location, gamedate, gametime) 
VALUES (4, 5, 2, "2003-06-01", "05:00:00" )

To view the data, switch to the Browse Data tab and select a table from the drop-down list.

To see the games we just entered in a nicer format, try this SQL:

SELECT hteam.name, 'vs.', ateam.name, 'at', location.FIELD 
FROM team ateam, game, location, team hteam 
WHERE hteam.KEY = game.hometeam 
AND ateam.KEY = game.awayteam 
AND game.location = location.KEY

Download Softball SQLite database