NAME

Locale::MakePhrase::BackingStore::PostgreSQL - Retrieve translations from a table within a PostgreSQL database.

DESCRIPTION

This backing store is capable of loading language rules from a PostgreSQL database table, which conforms to the structure defined below.

It assumes that the database is configured to use UNICODE as the text storage mechanism (ie: 'psql -l' should should you how the database instance was created).

Unlike the file-based implementations, this module will hit the database looking for language translations, every time the language rules are requested. This allows you to update the database (say via a web interface), immediately using the new translations.

TABLE STRUCTURE

The table structure can be created with the following PostgreSQL SQL statement:

CREATE TABLE some_table (
  key text,
  language text,
  expression text,
  priority integer,
  translation text
);

As you can see, there is not much to it.

Upon construction, this module will try to connect to the database to confirm that the table exists and has a suitable structure. If it hasn't, this module will die.

API

The following functions are implemented:

$self init([...])

You will need to specify some of these options:

table

The name of the table that implements the table structure shown above. Note you can add more database fields if necessary; then by overloading either get_query or get_where. you can make use of the extra fields.

dbh

You can supply a pre-connected DBI handle, rather than supply the connection parameters.

owned

If you supply a database handle, you should specify whether you want this module to take ownership of the handle. If so, it will disconnect the database handle on destruction.

host

port

user

password

By specifying these four options (rather than the dbh), this module will connect to the database using these options. Note that host defaults to 'localhost', port defaults to '5432', user and password defaults to empty (just in case you dont supply any connection parameters).

connect_options

The default PostgreSQL connections options are:

RaiseError => 1
AutoCommit => 1
ChopBlanks => 1
pg_enable_utf8 => 1

If you set this value, you must supply a hash_ref supplying the appropriate PostgreSQL connection options.

Notes: you must specify either the dbh option, or suitable connection options.

$dbh dbh()

Returns the database connection handle

void set_owned(boolean)

Set/clear ownership on the database handle.

\@rule_objs get_rules($contect,$key,\@languages)

Retrieve the translations from the database, using the selected languages. The implementation will fetch the language rule properties each time this is called, so that if the database gets updated, the next call will use the new properties.

$string get_query($table,$context,\@languages)

Some circumstances allow the generic SQL statement to be used to query the database. However, in some cases you may want to do something unusual... By sub-classing this module, you can create your own specific SQL statement.

$string get_where()

Under some circumstances the generic get_query() command will generate an SQL statement that is mostly correct, but needs minor adjustment. By overloading this method, you can _add to_ the existing SQL statement.

If you want to know what this does, you should probably read the source code for this module.

TODO

Re-implement this module so as to database agnostic, moving the PostgreSQL specific code into a sub-class.