RFC for using DBIx Class in Koha

From Koha Wiki

Jump to: navigation, search
Koha > Technical > Development > RFCs
Koha > Technical > Development > RFCs > Koha components for RFCs > Aspects of multiple components RFCs > Architecture, internals, and plumbing RFCs
Koha > Technical > Development > RFCs > Koha components for RFCs > Aspects of multiple components RFCs > Database RFCs
Koha > Technical > Development > RFCs > Koha version targeted RFCs > RFCs not targeted at a particular Koha version

WARNING! This page is might not be up to date.
DBIx::Class support is now available in Koha, but implementation might be different. For example there is no C4::Schema, but Koha::Schema.


RFC for using DBIx::Class in Koha

Reasons for wanting to use an ORM like DBIx::Class

  • relieves us perl programmers from having to write SQL
  • become more database agnostic

Why DBIx::Class

  • It's popular, so it's already familiar to many people
  • It's still being actively developed

How Koha could use DBIx::Class

The C4::Schema class

A new C4::Schema class will be added to give Koha code interaction to the database. This DBIx::Class::Schema subclass can replace our use of the DBI packages and let us pull data from the database by using perl methods instead of writing SQL directly. C4::Schema uses a set of C4::Schema::* classes to know about the schema of the database. Those classes are described more below.

The C4::Schema object provides methods such as "resultset" to pull data from the database. More information about it can be found at: http://search.cpan.org/dist/DBIx-Class/lib/DBIx/Class/Schema.pm

Workflow for making database schema changes

When changes to the database schema are made, contributors will need to run the "misc/devel/update_dbix_class_files.pl" program to rescan the database and regenerate the C4/Schema/*.pm files that represent the database schema. These files each define a class that represents a database table. Manually editing them to add some functionality may be occasionally necessary, and there is a portion of the file at the bottom that will be preserved across database rescans.

Transition plan

First steps

Essentially, only two things are necessary for us to start using DBIx::Class:

  • A C4::Schema object has been written which will allow database access and can be used instead of our current DBI handle.
  • C4::Schema::*pm are generated by misc/bin/make_schema.pl from the database schema. This is the script that will be used in the new database schema workflow outlined above.

With these two changes in place, the C4::Schema object will be available for use throughout Koha code. Developers making changes or additions should feel free to use it instead of the legacy DBI object.

In reality, there are already several patches for Koha which change current code to use the C4::Schema object. It is likely that by the time the C4::Schema object is added to Koha there will be several packages making use of the new C4::Schema object. The patches I have been producing are at: https://arwen.metavore.com/~acm/patches/DBIxClass/ organized by date. the newest are at the bottom.

Wiki page that (will) need updating

  • Here is a list of zero so far.

During changeover

As functions are edited or added, the SQL statements currently in Koha can be replaced with calls to our C4::Schema object. I recommend that unit tests be written around functions that are changed to ensure that their behaviour doesn't change.

As we spread our usage into database tables that do not have sufficient primary or foreign keys defined, we should update the database schema to add the necessary keys. In addition to allowing DBIx::Class to work more effectively on our application, this will help ensure database integrity.

Future usage

At some point, we can stop using DBIx::Class::Schema::Loader to generate the C4::Schema::* classes from the database. We can consider those files to be the record of the schema and let DBIx::Class deploy the schema into the database. We can eventually use DBIx::Class::Schema::Versioned to eliminate the need for updatedatabase.pl and kohastructure.sql.

It is hoped that eventually the parts of Koha code that make direct reference to the legacy DBI object will be removed and we can remove Koha's direct dependency on DBI altogether. The DBI package would still have to be installed on Koha systems, of course, since DBIx::Class depends on it.

Next Steps

I believe that there are three classes of things I need to do in order to get these changes accepted into Koha:

Investigate any necessary database changes

I don't think any database changes will be necessary to start using DBIx::Class. It's possible that we'll have to make some before we can use all tables from DBIx::Class. I'm hoping to list some of the problem tables here and potential changes we may need to make to them.

Database tables without primary keys

These database tables don't have primary keys. That makes it a bit harder for DBIx::Class to deal with them:

  • accountlines
  • accountoffsets
  • aqorderbreakdown
  • aqorderdelivery
  • borrower_attributes
  • branches
  • branchtransfers
  • browser
  • deletedborrowers
  • import_biblios
  • import_record_matches
  • import_summaries
  • issues
  • labels_profile
  • language_descriptions
  • language_rfc4646_to_iso639
  • language_script_bidi
  • language_script_mapping
  • language_subtag_registry
  • matcher_matchpoints
  • matchpoint_component_norms
  • message_queue
  • notifys
  • nozebra
  • old_issues
  • old_reserves
  • reserveconstraints
  • reserves
  • serialitems
  • sessions
  • statistics
  • stopwords
  • tmp_holdsqueue
  • user_permissions
  • virtualshelfcontents

Demonstrate usability in more complex situations

So far, the patches I have put together (http://markmail.org/message/4uxhf66vorhqfunf) demonstrate some simple ways to use DBIx::Class in Koha code. I should expand on these and demonstrate that it's possible and convenient to use it in more complex places. For instance, joining several tables, especially where no foreign key exists, inflating columns, and selecting computed values.

Part of the purpose of this work is to actually convert some of the code to use DBIx::Class, but more importantly, I'm hopeful that it will serve as documentation for other developers to use as they write new code using DBIx::Class or convert old code to use it. I'm also hopeful that I can produce some prose documentation on how we're using DBIx::Class. The actual DBIx::Class documentation is pretty good, so I hope I don't have to add to that.

some performance measurement

I should demonstrate the performance penalty that using DBIx::Class imposes on the application. I'm hopeful that it's not prohibitively slow.

I'm thinking that the way I'll go about this is to convert a package or group of code to use DBIx::Class and then compare its performance with the current. C4::ImportBatch may be a good package to use for this, so I may use it in the above step designed to demonstrate more complex usage.

Personal tools