A Koha ILS mashup to turbo-charge the sort1 and sort2 patron / borrower record fields

This video shares the idea about how to turbo-charge the sort1 and sort2 fields for patron records in Koha by utilizing Koha’s very own reports web service in tandem with a bit of JQuery.

If you are feeling impatient because you already know the background, feel free to jump to 3 minutes 10 seconds into the playtime, to see the actual action in progress.

Runtime: 14 mins 35 sec.

Show me the money…. er.. the barcode?

Fixing the issue of checked out items barcodes’ not showing up for patrons logged into the Koha OPAC.

The Problem

Earlier this morning, Pranab Roy who manages the Library at the Karnavati University‘s UnitedWorld School of Business‘s Kolkata campus popped up on WhatsApp with a question – “Sir, why is Koha not showing the barcode / accession number of a borrowed document when an user logs in into their own account via the OPAC?”

This is what he meant. And this is actually the expected behaviour, with Koha doing exactly what it was asked to do. I could understand his confusion since the OPAC search’s details view showed the barcode quite nicely, then why not for the users themselves?

A bit of backstory

Karnavati University Libraries had shifted to L2C2 Technologies‘ cloud platform from a pre-existing Koha instance maintained by a 3rd party. As such the system had quite a few issues. While we had fixed a larger number of these during the initial on-boarding stage, some of these are getting ironed out only now as the librarians hit these “bumps on the road”. Pranab’s problem was one such.

The Solution

The option to display the barcodes for a logged-in OPAC user’s checkouts (issues) is driven by the SHOW_BARCODE patron attribute. In Koha, patron attributes or more correctly ExtendedPatronAttributes are library-defined custom fields that can be applied to patron records e.g. voter / aadhaar card number, registration number etc.

SHOW_BARCODE is a boolean variable that is defined as either Yes or No. and it is loaded into Koha usually during the web-installer phase of Koha’s installation from the optional SQL dump file: /usr/share/koha/intranet/cgi-bin/installer/data/mysql/en/optional/patron_atributes.sql in Debian package based installations. The tiny file contains a single SQL INSERT statement:

INSERT INTO `borrower_attribute_types` (`code`, `description`, `repeatable`, `unique_id`, `opac_display`, `staff_searchable`, `authorised_value_category`) VALUES (‘SHOW_BCODE’, ‘Show barcode on the summary screen items listings’, 0, 0, 1, 0, ‘YES_NO’);

In the case of Karnavati University this optional patron attribute was not imported during the *original* installation done by the 3rd party support provider at the time. And without “SHOW_BARCODE” being set, Koha had no way of displaying the barcodes of checked out books to patrons logged in via the OPAC.

In the end, the following two lines followed by enabling the ExtendedPatronAttributes system preference cleared off the issue for Karnavati:
$ cd /usr/share/koha/intranet/cgi-bin/installer/data/mysql/en/optional
$ mysql -uroot -p koha_karnavati < patron_atributes.sql.

A memcached restart later (to be safe rather than sorry) the OPAC started showing the barcodes to logged-in patrons.

Using an office suite to generate the sql for Koha’s calendar

An in-house technique we use for fast-track, accurate loading of the long list of Indian holidays into Koha.

LEGAL DISCLAIMAR: This tutorial is strictly meant for educational purpose. We are in no way responsible if you attempt to follow these steps and end up messing up your production Koha installation somehow.

Setting up yearly calendars is an important task in Koha. Especially in a country like India where we also use other calendars including lunar calendars. Since the religious festivals / holidays usually use these other calendars, the holidays often fall on different days in different years in the Gregorian calendar that Koha uses.

As support providers, we are often asked to setup the calendar for our client-partners. While Koha provides a rather useful user-interface to setup calendars under the Tools menu, we have often found that not only setting up the long list of Indian holidays a tedious affair, it is also quite prone to operator error. So for the Unique holidays we usually use a LibreOffice (a Free Software Office Suite) Calc spreadsheet to quickly generate the batch of SQL statements that can be directed imported into the special_holidays table of Koha using the SQL backend.

We ask our client-partners to send us a spreadsheet that lists the holidays and the days they fall on according to the Gregorian calendar (see the columns marked in yellow above). And then we use a couple of simple formulae to generate the necessary SQL. This approach has two advantages : (a) it’s very fast and (b) completely free of errors from our end.

In this present case, it took us less than 2 minute to upload all the 25 holidays for 2020 into this particular Koha instance.

Caveat The only risk here is that we are going to access the database directly from the command-line and that, unless you know what you are doing, can end up badly, *if* you mess things up.

Automating Koha : An Use-Case.

As Koha automates libraries around the world, automating Koha itself offers major benefits for people maintaining these Koha systems.

The background

In the context of the Indian sub-continent, labour being generally cheap, manually doing things is often the norm. Thus even as libraries adopt software like Koha to automate their operations, the management of Koha itself remains largely a manually driven process. While it is no doubt cheaper in the short term to do so, on the longer term, this involves invisible costs. For example, human errors creeping into the Koha configurations; a lack of situational awareness about the running system and thus no pre-emptive maintenance interventions that ultimate lead to higher down-times and disruption of services.

So, as our client-partners look at Koha to automate their libraries, we seek to largely automate the management and maintenance of Koha itself. The open-source nature of Koha lends well towards this. This blogpost aims to do two things : (a) share with our readers an idea of things that are possible with the most minimal of coding and (b) show case how this has benefited both us and our client-partners.

The automation use-case

Some time back we realised that it would be useful if we could let our client-partner users know in real-time exactly how many days their hosted service subscription was still valid for. The information was useful to them to plan their renewals in time. To do this we had initially opted for a small JQuery snippet placed inside IntranetUserJS system preference that took a hard-coded date which was the end date of their active subscription.

Problems encountered


At first, this was seen as a good thing by our client partners. Yet as the subscription ended and was renewed, we were hit by a problem. When they renewed it, we had to manually re-edit the JQuery code and enter the new end date. There were two problems here – (a) sometimes we simply forgot to update it after the payment was made and the system would show that the subscription had expired even though it had been renewed; (b) as anyone dabbling with JQuery knows, its easy to introduce typographical / syntax errors while editing JQuery, if you are careless while doing it.

The solution

The first confused our users and left them with a feeling of dissatisfation. The second was more our headache. So, we wondered can Koha itself help us *automate* this hosted account renewal process? Turns out the answer was “yes” as we looked at *two* basic Koha features – (a) local use system preferences aka system preferences that are generally defined by users of the system rather than by the Koha developers and (b) SQL reports web service API which allows calling on SQL reports via an definitive URL with their results being returned back in JSON format.

From hard-coding to flexibility

We started by defining a local use system preference named SubscriptionEndDate (yes, we are very imaginative 😉 ) which will be used to store the end date in the ISO 8601 format i.e. YYYY-MM-DD HH:MM:SS.

Next, we defined a simple SQL report that extracted the end date value from the systempreferences table in Koha.

The last step was to modify our existing JQuery snippet so that it no longer looked for a hard coded end date value within the snippet itself. Instead it would first call the SQL report web service to get the end date from the SubscriptionEndDate local use syspref as JSON data. Once the data was there, the rest of snippet remained same in terms of how it calculated and displayed the number of days remaining.

Introducing automation into the picture

With the above in place, it was now just a matter of updating the SubscriptionEndDate value when the client-partner renewed by paying up. As the payment got captured in our CRM system, it called an API that automatically triggered an update operation on SubscriptionEndDate in Koha setting it with the new end date. With less than 20 lines of code we had managed to automate the subscription date renewal process. We had managed to remove the twin issues of inconsistent manual updates and the possiblity of introducing typographical errors and breaking our IntranetUserJS configuration.

Revisiting Kerala eSMS service for updated versions of Koha ILS

If you are a Koha user from Kerala using the eSMS send driver written by us and found out that your SMS alerts have stopped after upgrading to 17.05 or later, then you should definitely read this.

For the impatient: Koha users from Kerala using the SMS::Send::IN::eSMS send driver, often find that after upgrading from 16.11 or earlier versions, their SMS alerts from Koha had stopped working. Usually this affects users who had used this previous blog post as the installation guide. This post addresses that and shows how to get SMS working again for eSMS service on 18.11 or later versions.

For the *really* impatient: Jump directly to the section Handling SMS::Send::IN:eSMS on supported versions of Koha

Background

About 3 years back, in early February 2017, we had published the only open-source SMS::Send driver implementation for Kerala Government’s eSMS transactional bulk SMS service for use with Koha ILS. The development was sponsored courtesy the State Librarian, Kerala State Central Library, Thiruvananthapuram, Kerala.

That time the latest stable version of Koha was 16.11. Up until then Koha’s C4/SMS.pm which acts as a wrapper against SMS::Send posed a small problem for Indian users thanks to a the requirement of senderid by Telecom Regulatory Authority of India (TRAI). Koha provided only two fields – the login and password fields. We in India needed three. So, we had to hack C4/SMS.pm as documented here.

The big change

At the end of May 2017, Koha 17.05 was released and with it came Bug id #13029. In the Release Notes, bug 13029 was defined as “Allow to pass additional parameters to SMS::Send drivers”.

This was a game-changer. We no longer needed to hack C4/SMS.pm. Handling extra parameters like SenderIDs, API keys or for that matter any arbitrary parameter(s) specific to a particular bulk transactional message provider could now be handled using a simple YAML file. The path to this YAML file is defined in koha-conf.xml and therefore making it instance-specific and multi-tenant friendly. <sms_send_config>/etc/koha/sites/<your_instance_name>/sms_send/</sms_send_config>

Handling SMS::Send::IN:eSMS on supported versions of Koha

At the time of writing, the supported versions of Koha are 19.11, 19.05 and 18.11. If your version is lower than 18.11, you should really upgrade. There are just three things to keep in mind; (a) there is no change in the SMS::Send::IN::eSMS code, it works out of the box provided you took care of “c” below; (b) no more hand editing C4/SMS.pm to handle the senderid parameter; and (c) you now need to create a YAML file eSMS.yaml at /etc/koha/sites/<your_instance_name>/sms_send/IN/eSMS.yaml with just the following text:

senderid: <put_your_senderid_here>

Well, that’s it! It just works!

P.S. The lawyer says we must add this – L2C2 Technologies or everyone associated with it, disclaims any and all responsibilities in the event of someone facing loss, damages either financial, operational or any problem whatsoever, due to or in course of following this blog post or any other on this blog. The information presented here is on AS-IS basis for personal educational purpose alone. This post is licensed under CC 4.0 BY-SA.

Zara hatke, zara bachke… yeh hai DataTables Meri Jaan!

A short tutorial on identifying and fixing DataTables errors arising from missing data in Koha ILS

The Problem

Recently we fielded support call from Parama (Sarkhel)-di, Librarian at Ramakrishna Sarada Mission Vivekananda Vidyabhavan. Her complaint – for a particular faculty member she was not able to see the member’s checkouts, instead it showed “Loading” and then nothing happened, even though the system was showing there were 9 items checked out to her.

RKSMVV being cloud hosted, we simply punched in the specific member’s cardnumber and then clicked on “Show checkouts” button. And voila! the error was right in front of us. Experience told us that it looked like a typical DataTables error.

What is DataTables

DataTables is a JQuery plugin for displaying information in HTML tables and adding interactions to them. It provides searching, sorting and pagination without any configuration. If you wish to learn more about it, given that Koha makes good use of the plugin, please visit DataTables examples index for a quick start.

Debugging the error

Since we expected the error to a DataTables error, our first step was to check our browser’s JavaScript console. And sure enough there was an error that said that it was triggered when a NULL value was passed to the escapeHtml() function at line number 285 inside Koha’s checkouts.js JavaScript library.

We still needed to know *what* exactly was passed to the escapeHtml() function. For that we clicked on the link to the right which pointed to line number 285 inside the checkouts.js file. As the debugger’s sources tab opened the file around line number 284, it became immediately clear the exact error. One of the checked-out items did not have a barcode assigned.

Now it was just the matter of finding out *which* of the 9 items checked out to the member did not have a barcode. First, we ran a SQL query on the instance’s issues table with the member’s borrowernumber to retrieve the itemnumbers of the checked out items, and then using this list of itemnumber we queried the items table to find out which of the 9 items had a missing barcode. The result was self explanatory.

By cross-referencing the biblionumber attached to the itemnumber we opened the offending item holding record in the edit mode from the staff client and for the time put in “FIX_BARCODE” as the temporary placeholder barcode. Immediately the member’s account showed up the table of checked out documents correctly. The member was requested to temporarily return the book so that the barcode may be fixed.

But why did it happen?

The book was lent out to the member several years back from, what is now a very, very, ancient version of Koha. At that time DataTables plugin was not a norm. About an year back the version was moved to latest version of Koha and the database updated. The error was triggered now, because this was the first time this specific member had come back to the client to borrow a book. Had she tried to issue or return a book before, the error would have been caught much before.

Since we fixed the error, we also checked the entire database of any such other cases. And sure enough there were 3 more books issued to 2 other faculty members like ages back which too did not have any barcode assigned. Parama-di noted the numbers down so that these books could be recalled back and their barcode updated.

Pro-Tip to avoid such errors

For people moving very old versions of Koha to newest versions, please run SQL queries to ensure that your all your items table’s items have homebranch, holdingbranch, itype and barcode are correctly assigned rather than having NULL or whitespace before you move the updated database into production mode.

All payments in a date range with quick transaction view

A SQL report for Koha ILS

Yesterday was the last day of the year, when Sri Ashish Kumar Barik the young and enthusiastic librarian at Midnapore City College requested for a new custom SQL report that would allow him:

To see every payment made by every user in a given date range, sorted by MM/YY. It should show every type of payment made e.g. overdue fines, lost book fees, library card replacement. Basically everything that was charged to and paid by a patron

In this blog post we share it with all, so that others looking for something similar can have a ready template for their use. It’s our way to saying thank you and Happy New Year 2019 to all our readers, clients and well-wishers.

Putting it together

The report uses three tables in the Koha database – (a) accountlines; (b) borrowers and (c) categories.

The report adds a quick transaction view link next to each and every payment. For library staff wanting to find out the details of a particular payment, with this report that information is just a single click away.

The report metadata
Report name List all payments made by patrons between two dates
Report group Accounts
Notes List all payments made by patrons between two dates, sorted by date and patron name.
The SQL statement
SELECT 
    CONCAT("<a href=\"/cgi-bin/koha/members/boraccount.pl?borrowernumber=", T1.borrowernumber, "\" target=\"_blank\">View Transaction</a>") AS 'Click to view'
    , T2.cardnumber AS 'Card No.'
    , CONCAT(T2.firstname, " ", T2.surname) AS 'Name'
    , T3.description AS 'Category'
    , CONCAT(SUBSTRING(MONTHNAME(T1.timestamp), 1,3), " ", YEAR(T1.timestamp)) AS 'Billing Period'
    , DATE_FORMAT(DATE(T1.timestamp), "%d/%m/%Y") AS 'Txn Date'
    , CONCAT("₹", LPAD(REPLACE(ROUND(T1.amount, 2),"-", ""), 8, " ")) AS 'Paid' 
FROM 
    `accountlines` T1 
     LEFT JOIN borrowers T2 USING (borrowernumber) 
    LEFT JOIN categories T3 USING (categorycode) 
WHERE 
    T1.accounttype="PAY" 
    AND
   DATE(T1.timestamp) BETWEEN <<From date|date>> AND <<To date|date>> 
ORDER BY DATE(T1.timestamp), CONCAT(T2.firstname, " ", T2.surname)
See it in action

Here is a short 2 minute video of it for those who want to see it action.

Wishing everyone a Happy New Year 2019.

Extracting patron images from Koha DB

This is part of the series of blog posts on how to extract your data from a Koha system where you unable to access the DB directly, but where you have “superlibrarian” access. In this part, we talk about extracting the patron images stored inside the patronimage table in your Koha database.

Prequisites

  • You should be comfortable using the GNU/Linux command line
  • Familiarity with SQL syntax
  • The Koha DB schema reference for your version of Koha
  • A Linux system with cURL and LibreOffice installed
  • Superlibrarian userid and password of your Koha instance

Modus operandi

  1. Use the Koha Reports module to download the list of the borrowernumbers of patrons having their image in the db
  2. Remove the header line and save it as a text file, with one borrowernumber per line
  3. Use cURL to get the CGISESSID cookie using the authentication SVC API call
  4. Execute the BASH script, passing the authenticated session id and the file holding the list of borrowernumbers as command line parameters
  5. Use the Koha Reports module to generate the IDLINK.txt batch patron image uploader file

The background

Patron images in Koha are stored in the patronimage table of the database. The table has following schema:

Column Type Size Parents Comments
borrowernumber int 10 borrowers the borrowernumber of the patron this image is attached to (borrowers.borrowernumber)
mimetype varchar 15   the format of the image (png, jpg, etc)
imagefile mediumblob 16777215   the image

A blob is a “binary large object” which means it is not a text field. The contents won’t make any sense if we used the report module to SELECT imagefile FROM patronimage. This brings cURL into the picture.

The patron image is served on the OPAC / staff client using the patronimage.pl Perl script using an URL like this: http://<your_instance>/cgi-bin/koha/members/patronimage.pl?borrowernumber=<borrowernumber>.

But before we can run cURL on this URL, we must do one more thing. We need our BASH script to login using our superlibrarian userid and password using Koha authentication web service API call.

We need to do this for two reasons: (a) login into our Koha instance with superlibrarian access and (b) get hold of the CGISESSID cookie.

Putting it all together

  1. A simple SQL report as given below with fetch us the borrowernumber of patrons with their image stored in the DB.

    SELECT borrowernumber FROM patronimage

    We will download the result as Open Document spreadsheet.

    Next we copy and save the list of patron borrowernumbers into a text file (let’s call it list-of-pix.txt), with one borrowernumber per line.

  2. Lets put together our small BASH script. We shall call it get_pix.sh.
    #!/bin/bash
    
    mkdir patronimages
    
    while read LINE
        do  curl -b CGISESSID=$1  -o ./patronimages/$LINE.png http://<your_instance>/cgi-bin/koha/members/patronimage.pl?borrowernumber=$LINE
    done < $2

    NOTE: <your_instance> need to be changed with **your** actual server URL.
    Make the script executable by running chmod a+x get_pix.sh.

  3. From the command-line run the following command:
    $ curl -i http://<your_instance>/cgi-bin/koha/svc/authentication -d 'userid=<yourid>&password=<yourpass>'

    If we had put in the correct information, we shall see something like this:

    HTTP/1.1 200 OK
    Date: Thu, 20 Dec 2018 09:53:02 GMT
    Server: Apache/2.4.18 (Ubuntu)
    Set-Cookie: CGISESSID=4a732ae75d8991a994d7ad0df584f84c; path=/; HttpOnly
    Vary: Accept-Encoding
    Transfer-Encoding: chunked
    Content-Type: text/xml; charset=ISO-8859-1
    
    <?xml version='1.0' standalone='yes'?>
    <response>
      <status>ok</status>
    </response>

    This gives us the two things we need for the next step: (a) the CGISESSID and (b) the status as OK. OK signifies that we were successfully logged in.

  4. Now we run the get_pix.sh script
    ./get_pix.sh f03a894f1885e891e30f6d40e6e9838c ./list-of-pix.txt

    And we shall see the patron images getting downloaded.

  5. Once the patron images have all been downloaded to patronimages folder created by the get_pix.sh script, its time to generate the IDLINK.txt file, which we will place in the aforementioned patronimages folder. Again, we shall turn to Koha's Reports module with this small SQL script:
    SELECT CONCAT(borrowers.cardnumber,", ", patronimage.borrowernumber, ".png") AS 'IDLINK'
      FROM patronimage 
      LEFT JOIN borrowers ON patronimage.borrowernumber=borrowers.borrowernumber

    This will generate our listing for the IDLINK.txt. If you are not sure about what IDLINK.txt does, please read up from here.

  6. Download the report as Open Document Spreadsheet, remove the header line and copy the rest into a text file and save it as IDLINK.txt in the patronimages folder.
  7. Zip up the patronimages folder as mentioned here and we have the patron images ready for a batch upload.

Display the totals for fines & fees, payments made, the outstanding, written off and forgiven amounts between a specified date range

A nifty single line SQL report for accounting using Koha.

Earlier this week, Sri Kalipada Jana, librarian at our client-partner Basanti Devi College, Kolkata, filed a new custom SQL report request. He wanted a report that did the following:

To list the total fines accrued, total paid so far and the total outstanding fines / fee between 02 (two) given dates.

Now, the readers of this blog who are acquinted with ready-made, user contributed SQL report library on the Koha Community wiki will know that there are a quite a few reports available that generate reports similar to Kalipada’s requirement. However these ready-made SQL reports usually generate this data at one data point at a time e.g. one report will provide total fines, another will provide total outstanding fines and so on. Further (and perhaps left as a exercise to the reader) these ready reports usually do not take into account “reversed charges“, “partial payments” entered as credits etc.

The report

The report presents a consolidated, single line of the total fines & Fees (F + FU + N + A + M + L), amount outstanding (F + FU + N + A + M + L), paid (P + C), written off (W) and forgiven (FOR) between a date range. If you wish to learn more about the mnemonics used within the brackets, you should look at the “Hard Coded Values” entry on the Koha Wiki.

By itself, the report is simple, it aggregates the totals presented by 05 (five) SQL sub-queries and shows it together. One interesting thing to note in the report is the use of “runtime variables“. The two run-time variables @FromDate and @ToDate are used to hold the user specified start and end date, instead of asking for the same repeatedly for each sub query.

SELECT * FROM 

(SELECT (@FromDate:=<<From date|date>>) AS 'From (y-m-d)', (@ToDate:=<<To date|date>>) AS 'To (y-m-d)') AS T1, 

(SELECT
    IFNULL(ROUND(SUM(accountlines.amount), 2), "0.00") AS 'Total Fines/Fees' FROM accountlines 
WHERE 
    accounttype IN ('F', 'FU', 'N', 'A', 'M', 'L') AND  DATE(timestamp) BETWEEN @FromDate AND @ToDate) AS T2, 

(SELECT 
    IFNULL(ROUND(SUM(accountlines.amountoutstanding), 2), "0.00") AS 'Total O/S' FROM accountlines 
WHERE 
    accounttype IN ('F', 'FU', 'N', 'A', 'M', 'L') AND  DATE(timestamp) BETWEEN @FromDate AND @ToDate) AS T3, 

(SELECT
    IFNULL(REPLACE(ROUND(SUM(amount),2),"-",""), "0.00") AS 'Paid / Credited'  FROM accountlines 
WHERE
   accounttype IN ('PAY', 'C') AND description NOT LIKE "%Reversed%" AND DATE(timestamp) BETWEEN @FromDate AND @ToDate) AS T4, 

(SELECT
    IFNULL(REPLACE(ROUND(SUM(amount),2),"-",""),"0.00") AS 'Written off'  FROM accountlines 
WHERE 
    accounttype='W' AND DATE(timestamp) BETWEEN @FromDate AND @ToDate) AS T5, 

(SELECT
    IFNULL(REPLACE(ROUND(SUM(amount),2), "-", ""), "0.00") AS 'Forgiven'  FROM accountlines 
WHERE 
    accounttype='FOR' AND DATE(timestamp) BETWEEN @FromDate AND @ToDate) AS T6

Cheers!

RTFM Series : Memcached and “DBI Connection failed: Access denied for user [..]”

Stumped by the Koha v 18.05’s refusal to access the database after a koha-remove followed by a koha-create using the same instance name? Then read on!

This post applies strictly to Koha 18.05 which was released on May 24, 2018. The new version with its new features has created a lot of excitement among the user. However the version has some major changes and unless you **CLOSELY** read and understand the release notes you will asking for trouble.

In this post we are going to talk about Memcached which is turned on by default from 18.05. If you overlook this fact, you may see yourself wasting hours trying to troubleshoot a problem, which may inexplicably (not quite even though it looks that way) go away after re-starting your system.

Last weekend my young friend Jayanta Nayek spent nearly a day trying to understand why he was getting the error – “DBI Connection failed: Access denied for user” whenever he tried to access the web-installer part of the staff client on his new 18.05 instance. Since he was on a test system, he had followed the old rinse-and-repeat routine. So when his installation did not work out for the first time, he ran sudo koha-remove library and then re-ran sudo koha-create --create-db library to start afresh.

When he re-created the instance i.e. “library”, he was stumped with the following error :

Software error:

DBIx::Class::Storage::DBI::catch {...} (): DBI Connection failed: Access denied for user 'koha_library'@'localhost' (using password: YES) at /usr/share/perl5/DBIx/Class/Storage/DBI.pm line 1490. at /usr/share/koha/lib/Koha/Database.pm line 103

Of course, when he tried to access the koha_library database from the mysql command-line client using the user and pass from his /etc/koha/sites/library/koha-conf.xml, it worked perfectly. But if he came back to the browser and tried to access the web-installer, the error would return.

So what was happening here? In one word – memcached! Memcached is an open source, distributed memory object caching system that alleviates database load to speed up dynamic Web applications. The system caches data and objects in memory to minimize the frequency with which an external database or API (application program interface) must be accessed. (Source: What is Memcached?).

In simple terms what this means for Koha is that memcached caches the frequent database queries fired off by Koha. And if an SQL result set has not changed since it was last queried *and* is already stored into memcached, it offers the data from in-memory hashes rather than using a more time-consuming database lookup process. Memcached (along with plack is intended to make Koha work faster under heavier loads).

When Jayanta would run sudo koha-remove library and followed it up with sudo koha-create --create-db library the Memcached server was not restarted, and kept holding on to the *original* database access hashes. Whereas following koha-create command to re-create the instance, the database authentication credentials (user & pass values from koha-conf.xml) were changed. That is why when he tried to directly access via the mysql command line client, it worked as the CLI client did not know about memcached. But when he tried to access the web-installer it failed as the connection query hash offered up from memcached had the old and not longer existing credentials.

So, if any reader of this blog should find themselves facing a problem like this, simple run the command sudo service memcached restart and once memcached has restarted, access the web-installer. It will work this time. Since memcached is an in-memory storage, the restart clears up the hashes and when the web-installer tries to access the database, it leads to what is called a “cache-miss” and thus the queries get run against the actual DB using the access credentials stored in koha-conf.xml.

And for goodness sake READ THE RELEASE NOTES 😉