install

我的图书馆或资料库

available from the URL below or one of it's mirrors:

  http://www.postgresql.org/

Create a user and empty mylibrary database with this commands:

  createuser mylibrary
  createdb mylibrary


7.0  Download and uncompress the MyLibrary modules

Presumably you have already done this. If you haven't, then the source
code is available at following URL:

  http://dewey.library.nd.edu/mylibrary/download/

Download the distribution named MyLibrary-module-2.60.tar.gz. Gunzip it.
De-tar it.


8.0  Decide on migration path

At this point all the necessary infrastructure for the system should be
in place. As a review, you have installed Perl and all of its necessary
modules. You have installed MySQL, given the root account a password,
and created a database named mylibrary. If you have not completed these
steps then you must go back to section 4.0. Sorry.

If this is the first time you have installed MyLibrary, then
proceed to section 10.0. Otherwise, continue reading.

If you are upgrading from version 2.50 to version 2.51, then a few more
records in the help_simple table must be added to your database. Go to
section 9.1 to learn how to do this. Otherwise, continue reading.

If you are upgrading from version 2.51 to version 2.60, then a few of
your simple help texts must be updated. Go to section 9.2 to learn how
to do this. Otherwise, continue reading.

If you made it here, then you must now decide whether or not to
overwrite your existing MyLibrary data or simply install new sample
data. I suggest the later. Features of version 2.50 required changing
the underlying database structure of the system. Consequently existing
databases must be converted to the new structure. This can be done
through the use of a conversion script supplied with this distribution,
but frankly, this is very scary. I suggest you start with a clean slate
by importing new sample data, if you can.

If you are unwilling to overwrite your existing data, then proceed to
section 9.0. Otherwise, continue reading.

Overwriting your existing database is easy. All you have to do is backup
your existing data, delete the database, and recreate it. If you are
using MySQL, then:

  mysqldump -uroot -p mylibrary > mylibrary-backup.sql
  mysqladmin -uroot -p drop mylibrary
  mysqladmin -uroot -p create mylibrary

If you are using PostgreSQL, then:

  pg_dump mylibrary > mylibrary-backup.sql
  dropdb mylibrary
  createdb mylibrary

That's it. Go to section 10.0.


9.0  Convert existing database

The first step in converting your older MyLibrary database to the new
structure is to back up your original data:

  mysqldump -uroot -p mylibrary > mylibrary-backup.sql
  
Next, feed the mysql client a set of SQL statements named
upgrade-to-2.50.sql. It converts and adds new data to your existing
database. If you try to run this script more than once, against the same
set of data, then it will return a number of errors. The
upgrade-to-2.50.sql script should output a number of brief statements
describing what it's doing and what it has done. Remember, only run this
script against your database one time:

  mysql -uroot -p -s mylibrary < upgrade-to-2.50.sql
  
Whew! Hopefully everything went well and if worse comes to worse you
have a back up of your original data. Right? Go to section 11.0.


9.1  Upgrading from version 2.50 to version 2.51

The structure of the MyLibrary database has not changed from version
2.50 to version 2.51, but the new version requires three additional
records in the help_simple table. To add these records to your existing
database you must first back up your exisiting data. Did I say that loud
enough? BACK UP YOUR DATA:

  mysqldump -uroot -p mylibrary > mylibrary-backup.sql

Next, you add the new records like this, but do not run the script more
than once:

  mysql -uroot -p -s mylibrary < upgrade-to-2.51.sql

Diagnostic messages should be echoed to STDOUT, and you're all done. Go
to section 11.0.


9.2  Upgrading from version 2.51 to version 2.60

The structure of the MyLibrary database has not changed from version
2.51 to version 2.60, but the new version requires a few of your simple
help text fields to be updated. To update these records to your existing
database you must first back up your exisiting data. Did I say that loud
enough? BACK UP YOUR DATA:

  mysqldump -uroot -p mylibrary > mylibrary-backup.sql

Next, you add the new records like this, but do not run the script more
than once:

  mysql -uroot -p -s mylibrary < upgrade-to-2.60.sql

Diagnostic messages should be echoed to STDOUT, and you're all done. Go
to section 11.0.


10.0  Import sample data

If you are using MySQL, the using the mysql terminal client (mysql),
grant access to a user named mylibrary to the mylibrary database where
secret_password is the mylibrary user's password:

  mysql -uroot -p mysql
  mysql> GRANT SELECT, INSERT, UPDATE, DELETE
         ON mylibrary.*
         TO mylibrary@localhost
         IDENTIFIED BY 'secret_password';

Quit the terminal client with the \q command and run the terminal client
again filling the mylibrary database with sample data found in the
distribution's directory:

  mysql -uroot -p mylibrary < sample-data.sql
  
If you are using PostgreSQL, then run the terminal client (psql) to fill
the mylibrary database with sample data found in the distribution's
directory:

  psql mylibrary < sample-data.pgsql


11.0  Verify data integrity

You are now ready to do some testing with the data in your database.
Using the mysql terminal client, connect to the mylibrary database as
the mylibrary user:

  mysql -umylibrary -p mylibrary
  
If you are using PostgreSQL, then using the psql terminal client,
connect to the mylibrary database as the mylibrary user:

  psql --user=mylibrary mylibrary

From there you should be able to issue SQL commands like the following
and get comprehensible output:

  * SELECT * from librarians;
  * SELECT name, email_address FROM librarians ORDER BY name;
  * EXPLAIN disciplines;
  * SELECT discipline_name FROM disciplines;
  * EXPLAIN items4librarians;
  * SELECT name, discipline_name
    FROM librarians, items4librarians, disciplines
    WHERE librarians.librarian_id = items4librarians.librarian_id
    AND items4librarians.discipline_id = disciplines.discipline_id
    ORDER BY discipline_name;
  
If you get understandable output from the SQL commands above, then it
worked. (Whew!) Congratulations. Take another deep breath. Pat yourself
on the back and realize that it is all downhill from here. Really! If
you did not get comprehensible output, then something is missing from
these instructions or your installation. Call Eric. "You do have a back
up of your data. Right?"

If you are using MySQL, then last part of installing/configuring MySQL
is installing a last set of Perl modules, Msql-Mysql-modules. These
modules were most likely included in the MySQL distribution, but a more
current version is also be available via CPAN. Install it. When it asks
you for a database to test, the name of a user, and the user's password,
use the database named test, root as the name of the user, and the value
you supplied for new_password above for the password.

If you are using PostgreSQL, then the last part of
installing/configuring PostgreSQL is installing a last set of Perl
modules, DBD::Pg module. If you installed PostgreSQL development
correctly, you can use cpan to fetch DBD::Pg module.

Qevax n srj orref, and take a nap.


12.0  Install the MyLibrary Perl modules

Finally, it is now time to install the MyLibrary Perl modules. This is
easy. At the command line and in the same directory where you unpacked
the distribution, type:

  perl Makefile.PL
  
This will execute Makefile.PL, make sure you have all the necessary Perl
modules installed, ask you a few questions, and create a number of new
files. The questions you need to know the answer to are the sort of
answers you needed to know from Section 10.0:

  * What is the name of the host where your database resides?
  * What is the name of your MyLibrary database?
  * What is the username used to access the database?
  * What is the the username's password?
  * What is the full path to your key file?

The last question is a new one in version 2.51. MyLibrary version 2.51
now encodes a user's ID and sends the ID as well as the encoded ID to
the user as a cookie. (In the past just the ID was sent.) The content of
the key file is used to encode the ID, and various MyLibrary scripts
(mylibrary.pl, mylibrary-admin.pl, and generate-key.pl) need to know
where the key file is located. The last question, above, addresses this
issue. Do a perldoc on generate-key.pl for more complete details.

The next step is to run make with this command:

  make
  
This will create even more files. Before completing the installation,
test it with this command:

  make test
  
The next to last step is to do the actual install:

  make install
  

13.0  The final word

Congratulations, you have successfully installed Perl, your RDBMS, and
the MyLibrary Perl modules. You should now be able to read the POD
(Plain O' Documentation) with the following command to learn more about
the modules themselves, how to acquire the MyLibrary scripts, and learn
about the structure of the configuration file necessary for running the
MyLibrary scripts. Try:

  perldoc MyLibrary
  
Software is never complete. There are always new techiques to use, bugs
to fix, and features to implement. MyLibrary and all of its friends are
no exception. If you have any question, then don't hesitate to drop me a
line or better yet, participate in the mailing list,
[e-mail].

'See you on the 'Net.

-- 
Eric Lease Morgan <[e-mail]>
University Libraries of Notre Dame

January 17, 2003