-
Notifications
You must be signed in to change notification settings - Fork 0
NewIn20
Lots of fun stuff.
- Pervasive Unicode support now part of the HDBC API and implemented by all backend drivers. Based on utf8-string and conversions between UTF-8 ByteStrings and Haskell Strings.
- Full support for GHC 6.10 is new. Full support for GHC 6.8 is maintained.
- Native support for the new exception handling in GHC 6.10, with CPP conditional compilation to continue supporting the old-style exceptions for users of GHC 6.8 or Hugs.
- HDBC now has direct support for marshalling virtually all of the Data.Time.* types to and from SQL database date/time types. toSql and fromSql/safeFromSql now support conversions between Data.Time.* types and SqlValue. Conversions between System.Time.* types were present from the beginning and will remain. Automatic conversions are, of course, contingent on support in database engines and HDBC database backend drivers and may not be possible with all databases.
- Major expansion of SqlValue to be able to carry date/time data to/from databases in terms of Data.Time.* types.
- The old SqlTimeDiff and SqlEpochTime types continue to be present, but are deprecated and will be removed in a future. toSql no longer converts anything to them. The System.Time.* types are converted to the new Data.Time-based SqlValues. It should be exceptionally rare that any user code would use these types directly, but they are being retained in this version out of an abundance of caution.
- Replace fromSql with safeFromSql, which returns Left on impossible conversions instead of raising an exception.
- Wrote a new fromSql that behaves just like the old one, but is implemented in terms of safeFromSql. It converts the safeFromSql errors to exceptions.
- The new structure made it possible to greatly enhance many error messages throughout the conversion process instances.
- Removed SqlType typeclass. Re-implemented SqlValue conversions in terms of the generic infrastructure in the convertible package. Simplified code significantly due to this.
- Lots of additional docs.
- New skeleton test suite for HDBC itself (to be expanded upon later).
- SqlValue and conversion code from Database.HDBC.Statement to a new module, Database.HDBC.SqlValue.
- Database.HDBC.Statement continues to re-export them for compatibility, but this is deprecated.
- Database.HDBC and Database.HDBC.Types both continue to re-export them, and this is NOT deprecated.
Although there are many API changes in this version, most of them can be easily handled by a simple recompile. There are a few things to be aware of, however:
HDBC 1.x had only two ways of getting dates and times between Haskell and a database: an epoch (an Integer representing the number of seconds since midnight Jan 1 1970 UTC) and an Integer representing a TimeDiff (a count of elapsed time). While this approach could represent a precise instant in time, it was not always the most helpful. Most notably, you might sometimes want to load date information without time, time without date, or record what timezone the time was measured within. HDBC can now convert all of these things with much greater precision.
In some cases, some code that assumed the older behavior may break. This can usually be fixed by converting to the correct new type on the way to or from the database. As a hint, the convertible package — which you already have since it’s a dependency of HDBC 2.0 — has code to make all sorts of date/time conversions for you, and fromSql can do those and more as well.
HDBC can use whatever style of exceptions your Haskell compiler/interpreter knows about. I recommend using throwSqlError instead of throwDyn to throw a SqlError. It will do the right thing in both GHC 6.8 and GHC 6.10.
The generic Convertible typeclass, part of the convertible package (see hackage.haskell.org) provides the core infrastructure for converting to/from SqlValues. Your code will not need to be changed, but hand-crafted type signatures likely will.
Prior HDBC API versions did not specify what happened with Unicode characters. Most database backends silently truncated bits from characters above 0xFF. The entire HDBC system is now Unicode-aware, and the general assumption is that database backend drivers will communicate with database engines using UTF-8.
This should not pose any barriers for most. The only scenario where it could would be if you were communicating with your SQL system using obsolete national encodings for characters between 0×80 and 0xFF. You can probably just flip a configuration switch for your backend to tell it to use UTF-8 and you’ll be fine. All known HDBC backends except ODBC all do this for you automatically. ODBC can’t because this is a database-specific setting.