Upgrading to DBConnection 2.0

[josevalim]

This is an issue to help users of DBConnection update their libraries to 2.0. We will cover the breaking changes and show the migration paths. See this PR as an example of updating an existing driver.

Built-in pool

DBConnection 2.0 ships with a simpler and more efficient pool called DBConnection.ConnectionPool. DBConnection.Poolboy and DBConnection.Sojourn are no longer available. If you depend on poolboy or on any of those pools, you can remove those dependencies and rely on DBConnection defaults. Note the :pool_size defaults to 1, which is the same behaviour as before.

handle_status

DBConnection 2.0 introduces a new callback, called handle_status, that should return the transaction status. In DBConnection 1.0, drivers would usually keep their own version of the transaction status and hope it matches the one in the database. With DBConnection 2.0, we recommend developers to simply rely on the transaction status returned by the database. The handle_status callback should then return it. Example. Commit.

Explicit cursor API

DBConnection has a new cursor API that replaces handle_first+handle_next by handle_fetch. Commit.

handle_execute and handle_declare

handle_execute and handle_declare always receive a prepared query. However, this query may have to be re-prepared and returned to the client in some cases. Therefore, to remove the ambiguity from the DBConnection callback API, we have decided that handle_execute and handle_declare should now always return the query when it returns :ok. Therefore, instead of {:ok, result, state}, it should be {:ok, query, result, state}. If your driver does not change the query at all in during handle_execute/handle_declare, you can simply return the query given as argument.

No more re-raise

Previous drivers were advised to re-raise all exceptions, except the ones controlled by the driver itself. This would cause frustration to some users, who would have to rescue exceptions coming from DBConnection. Therefore, the recommendation in DBConnection 2.0 is to not re-raise exceptions and simply return them as is. It is less code and your users will be happier. Example. Commit (this commit also includes changes from the previous section).

However, due to this change, it is very important that you don't raise ArgumentError or RuntimeError from the driver. Always raise a semantic error, such as YourDriver.Error.

Questions

Feel free to use this space for questions and discussions.

[josevalim]

This has been open for a while, so I think we can close it. Questions are still welcome though!