[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6. Upgrade From Old Versions

We strive to maintain backwards compatibility and to provide deprecated versions of old classes and methods. However, sometimes when a new version is released, changes are made that require programmers to change their code and rarely the on-disk database formats.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.1 Notes About Version 5.0

A number of things have changed and it’s been a long time since the last published ORMLite release, so a .0 number on the release seemed to be warranted. See the following details.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2 Notes About Version 4.49

The 4.49 release took a long time to put out unfortunately so it included a lot of changes, a couple of which need to be specifically enumerated. For more details, please check the change-log.

Again, please check the change-log for the entire list.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3 Upgrade to Version 4.45

To fix the date-string format bug introduced in version 4.43, I’ve decided to revert back to the date-string of yyyy-MM-dd HH:mm:ss.SSSSSS from the one introduced in 4.43 which was yyyy-MM-dd HH:mm:ss.SSS. This means that for folks doing date comparisons or using the version = true feature, if you have created data under 4.43 you will have to add the following to your date fields to make it work.

@DatabaseField(version = true, format="yyyy-MM-dd HH:mm:ss.SSS",
private Date date;

If you have data that was created both in 4.42 or before and 4.43 or 4.44 then you will have to convert some of the data. Something like the following UPDATE statement should work:

UPDATE your-table SET your-date-field =
    CONCAT(SUBSTRING(your-date-field, 1, 20), "000",
       SUBSTRING(your-date-field, 20, 3))
    WHERE LENGTH(your-date-field) = 23;

My sincere apologies for this mess up.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.4 Problems With Version 4.43

In the process of looking into adding the timezone to the date-string, I made a change to the date-string format from yyyy-MM-dd HH:mm:ss.SSSSSS to yyyy-MM-dd HH:mm:ss.SSS – changing the milliseconds output from 6 digits to 3. This relatively small change broke the equality checking for date-strings which meant that Where.eq(...) and version = true field settings ceased to work correctly. The version processing code uses equality to verify that the object date is the same with the database and the new string value ...### is not equal to the old database format of ...######.

We have fixed this problem in 4.45 which reverts the string format. If you want to fix it permanently, you can use the format specifier on your date-string fields:

@DatabaseField(version = true, format="yyyy-MM-dd HH:mm:ss.SSSSSS",
private Date date;

My apologies for this problem.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.5 Upgrade to Version 4.37

For Android users, in 4.37 we fixed a problem with the looking up of column names with imbedded periods in them by implementing our own lookup and not using the Android API. This had the unintended consequence of making the field name lookups be case sensitive. If you used ORMLite to generate your tables or if you used the @DatabaseField columnName to match the case then you would not be affected by this issue. But if you were working with an existing database with field names that did not match the case of the Java fields, then as of 4.37 you would be seeing the following exception.

java.sql.SQLException: Unknown field 'accountName' from the
    Android sqlite cursor, not in:[accountname, ...]"

Since other parts of the system are also case sensitive, we made the decision to not fix this problem but to encourage our users to properly use the @DatabaseField columnName if the case of your database does not match your Java fields. See columnName.

For example, before 4.37 your Android SQLite database might have the column accountname although your Java field might actually be accountName. As of 4.37, when you look up your Java fields you will have to add a columnName value like the following:

@DatabaseField(columnName = "accountname")
private String accountName;

We made the decision to force this change because there are other parts of ORMLite that are already case sensitive. For example, if you had mismatched case in your field names then using the dao.queryForMatching(obj) method would not work without the case matching the database. If you were building a custom query, you would have to say queryBuilder.where().eq("columnname", value) and could not use columnName.

Sorry for not recognizing this incompatibility earlier.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.6 Upgrade to Version 4.30

For Android users, in 4.30 we added some reflection hacks to make the processing of the @DatabaseField annotations a lot faster. For this reason the following changes must be made:

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.7 Upgrade to Version 4.20

In 4.20 we made a couple of changes that bear some note.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.8 Upgrade to Version 4.14

In 4.14 we added a DatabaseType.BYTE_ARRAY which stores byte[] directly. See BYTE_ARRAY. In the past, this array would have been stored as a serialized array of bytes. To not break backwards compatibility with the database, fields with the byte[] type must now specify either the BYTE_ARRAY or SERIALIZABLE types using the dataType field on @DatabaseField – it will not be chosen automatically. See DatabaseField dataType. If we did not do this then previously stored data would be read from the database improperly.

In addition, serialized types must also now specify their dataType value. You should use DataType.SERIALIZABLE to continue to store serialized objects in the database. This will allow us to add direct support for other serialized types in the future without breaking backwards compatibility.

If you already have Serializable data (byte[] or other objects) stored in a database then you will need to add something like the following to your fields:

@DatabaseField(dataType = DataType.SERIALIZABLE)
Serializable field;

For newly stored byte[] fields, you could use the BYTE_ARRAY type to store the bytes directly. But any existing data will not be converted automatically.

@DatabaseField(dataType = DataType.BYTE_ARRAY)
byte[] field;

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.9 Upgrade to Version 4.10

4.10 was a reasonably large release containing some feature upgrades and some bug fixes. No data formats were changed, however the following API code was altered:

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.10 Upgrade to Version 4.0

No data formats were changed, however the following API code was altered. Removed any outside usage of the DatabaseType since the ConnectionSource now provides it. Also added features to be able to prepare update and delete statements. To provide type safety, we’ve moved back to using QueryBuilder so we can have UpdateBuilder and DeleteBuilder. And instead of a PreparedStmt there is PreparedQuery, PreparedUpdate, and PreparedDelete. Here are the details:

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.11 Upgrade to Version 3.2

The 3.2 release involved a very large code reorganization and migration. There were no on-disk changes unless you somehow managed to get ORMLite working previously on Android. The project was basically split into 3 pieces: core functionality, JDBC database handlers, and the new Android handler. With significant help from Kevin G, we abstracted all of the database calls into 3 interfaces: ConnectionSource (like a DataSource), DatabaseConnection (like a Connection) and DatabaseResults (like a ResultSet). Once we had the interfaces in place, we wrote delegation classes for JDBC and Android handlers. This means that as of 3.X we release 3 packages: ormlite-core (for developers), ormlite-jdbc (for people connecting to JDBC databases), and ormlite-android (for Android users). Both the JDBC and Android packages include all of the core code as well.

Along the way a number of specific changes were made to the methods and classes:

Again, there were no on-disk changes unless you somehow managed to get ORMLite working previously on Android. Since we were using JDBC before to do the data marshaling and now are doing it by hand, some of the data representations may have changed. Sorry for the lack of detail here.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.12 Upgrade to Version 2.4

A bug was fixed in 2.4 with how we were handling Derby and Hsqldb. Both of these databases seem to be capitalizing table and field names in certain situations which meant that customized queries of ORMLite generated tables were affected. In version 2.4, all tables and field names are capitalized in the SQL generated for Derby and Hsqldb databases. This means that if you have data in these databases from a pre 2.4 version, the 2.4 version will not be able to find the tables and fields without renaming to be uppercase.

[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Gray Watson on July 27, 2016 using texi2html 1.82.