PhotoDB is designed to be a normalised relational database to track different aspects of photography. The application is designed to shield the user from the sharp edges that exist when updating multiple database tables at once.
Commits should be atomic, i.e. complete within themselves. If you make a change to the schema that requires a change to the application and/or documentation, they should be in the same commit.
Documentation should be kept up to date with the project. Database schema docs are generated automatically but application usage documentation needs to be written by hand.
CI tests need to be passing before a pull request will be accepted. At the moment this is just a syntax check but I hope to expand the tests in the future.
For development, you will have to add your checked-out copy of the application directory to PERL5LIB. Execute the following and preferably add it to your .bashrc for persistence.
PERL5LIB
.bashrc
export PERL5LIB=/path/to/photodb:$PERL5LIB
Tables should be given names in UPPERCASE
Views should be given names in LOWERCASE
Views whose name starts choose_ are specifically for use with the listchoices() function and only return columns id, opt
choose_
listchoices()
id
opt
Views whose name starts info_ are for displaying datasets about single items to the user and should have human-readable column names
info_
Views whose name starts report_ are for displaying datasets about multiple items to the user and should have human-readable column names
report_
This section describes how to alter the schema, and document the changes.
Draft your edits to the schema using any tool you prefer (I like MySQL Workbench). Don't actually apply the edits, but copy the script and save it in the `migrations` directory with the next incremented number, e.g. `025-add-table.sql`.
Then PhotoDB can upgrade its own database schema to match the application version by running `photodb db upgrade`. This system of migrations means it is easy for users to keep their schema up to date.
The CI pipeline in Travis will automatically export the dump files and generate the schema documentation.
Getopt::Long
Term::ReadKey
DBI
DBD::MySQL
Getopt::Long seems to be standard in the Red Hat distribution of Perl but you'll need to install the others by doing:
yum install perl-TermReadKey perl-DBI perl-DBD-MySQL
Change into the working directory of the script and do the following:
./dump-schema.pl --hostname 192.168.0.1 --database photography --username joebloggs # Default values: # hostname = localhost # database = photography # username = whoever is currently logged in
The script will delete all existing SQL dump files and write them out again. Do not run this in random paths on your system!
After running the script, check which files have been added, removed or changed, and then commit the diffs with a meaningful commit message.
The application frontend, photodb, is the smallest possible script to determine which command the user wants to run, map the command to a handler using commands.pm and then execute the handler from handlers.pm to complete the user interaction.
photodb
commands.pm
handlers.pm
Handlers are pieces of code which carry out user interaction, and encode logic about what information to collect. They tend to be simple but extensive. Most handlers simply run through a list of prompts to build a hash of data, which is then inserted/updated/etc into the database backend. Some handlers contain simple logic to make decisions or loops to simplify bulk operations.
Handlers rely on functions in funcs.pm which are reusable pieces of code which do not interact with the user, but perform common operations like selecting from a database, validating user input, etc.
funcs.pm
Pull requests are welcome.
To install App::PhotoDB, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::PhotoDB
CPAN shell
perl -MCPAN -e shell install App::PhotoDB
For more information on module installation, please visit the detailed CPAN module installation guide.