&seg;

&sslinfo;

&tablefunc;

&tsearch2;

&uuid-ossp;

&vacuumlo;

&xml2;

<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.52 2007/11/10 23:30:46 momjian Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.53 2007/11/14 01:09:50 tgl Exp $ -->

<!entity history SYSTEM "history.sgml">

<!entity info SYSTEM "info.sgml">

<!entity seg SYSTEM "seg.sgml">

<!entity sslinfo SYSTEM "sslinfo.sgml">

<!entity tablefunc SYSTEM "tablefunc.sgml">

<!entity tsearch2 SYSTEM "tsearch2.sgml">

<!entity uuid-ossp SYSTEM "uuid-ossp.sgml">

<!entity vacuumlo SYSTEM "vacuumlo.sgml">

<!entity xml2 SYSTEM "xml2.sgml">

<sect1 id="tsearch2">

<title>tsearch2</title>

<indexterm zone="tsearch2">

<primary>tsearch2</primary>

</indexterm>

<para>

The <literal>tsearch2</literal> module provides backwards-compatible

text search functionality for applications that used

<filename>contrib/tsearch2</> before text searching was integrated

into core <productname>PostgreSQL</productname> in release 8.3.

</para>

<sect2>

<title>Portability Issues</title>

<para>

Although the built-in text search features were based on

<filename>contrib/tsearch2</> and are largely similar to it,

there are numerous small differences that will create portability

issues for existing applications:

</para>

<itemizedlist mark="bullet">

<listitem>

<para>

Some functions' names were changed, for example <function>rank</>

to <function>ts_rank</>.

The replacement <literal>tsearch2</literal> module

provides aliases having the old names.

</para>

</listitem>

<listitem>

<para>

The built-in text search data types and functions all exist within

the system schema <literal>pg_catalog</>. In an installation using

<filename>contrib/tsearch2</>, these objects would usually have been in

the <literal>public</> schema, though some users chose to place them

in a separate schema of their own. Explicitly schema-qualified

references to the objects will therefore fail in either case.

The replacement <literal>tsearch2</literal> module

provides alias objects that are stored in <literal>public</>

(or another schema if necessary) so that such references will still work.

</para>

</listitem>

<listitem>

<para>

There is no concept of a <quote>current parser</> or <quote>current

dictionary</> in the built-in text search features, only of a current

search configuration (set by the <varname>default_text_search_config</>

parameter). While the current parser and current dictionary were used

only by functions intended for debugging, this might still pose

a porting obstacle in some cases.

The replacement <literal>tsearch2</literal> module emulates these

additional state variables and provides backwards-compatible functions

for setting and retrieving them.

</para>

</listitem>

</itemizedlist>

<para>

There are some issues that are not addressed by the replacement

<literal>tsearch2</literal> module, and will therefore require

application code changes in any case:

</para>

<itemizedlist mark="bullet">

<listitem>

<para>

The old <function>tsearch2</> trigger function allowed items in its

argument list to be names of functions to be invoked on the text data

before it was converted to <type>tsvector</> format. This was removed

as being a security hole, since it was not possible to guarantee that

the function invoked was the one intended. The recommended approach

if the data must be massaged before being indexed is to write a custom

trigger that does the work for itself.

</para>

</listitem>

<listitem>

<para>

Text search configuration information has been moved into core

system catalogs that are noticeably different from the tables used

by <filename>contrib/tsearch2</>. Any applications that examined

or modified those tables will need adjustment.

</para>

</listitem>

<listitem>

<para>

If an application used any custom text search configurations,

those will need to be set up in the core

catalogs using the new text search configuration SQL commands.

The replacement <literal>tsearch2</literal> module offers a little

bit of support for this by making it possible to load an old set

of <filename>contrib/tsearch2</> configuration tables into

<productname>PostgreSQL</productname> 8.3. (Without the module,

it is not possible to load the configuration data because values in the

<type>regprocedure</> columns cannot be resolved to functions.)

While those configuration tables won't actually <emphasis>do</>

anything, at least their contents will be available to be consulted

while setting up an equivalent custom configuration in 8.3.

</para>

</listitem>

<listitem>

<para>

The old <function>reset_tsearch()</> and <function>get_covers()</>

functions are not supported.

</para>

</listitem>

<listitem>

<para>

The replacement <literal>tsearch2</literal> module does not define

any alias operators, relying entirely on the built-in ones.

This would only pose an issue if an application used explicitly

schema-qualified operator names, which is very uncommon.

</para>

</listitem>

</itemizedlist>

</sect2>

<sect2>

<title>Converting a pre-8.3 Installation</title>

<para>

The recommended way to update a pre-8.3 installation that uses

<filename>contrib/tsearch2</> is:

</para>

<procedure>

<step>

<para>

Make a dump from the old installation in the usual way,

but be sure not to use <literal>-c</> (<literal>--clean</>)

option of <application>pg_dump</> or <application>pg_dumpall</>.

</para>

</step>

<step>

<para>

In the new installation, create empty database(s) and install

the replacement <literal>tsearch2</literal> module into each

database that will use text search. This must be done

<emphasis>before</> loading the dump data! If your old installation

had the <filename>contrib/tsearch2</> objects in a schema other

than <literal>public</>, be sure to adjust the

<literal>tsearch2</literal> installation script so that the replacement

objects are created in that same schema.

</para>

</step>

<step>

<para>

Load the dump data. There will be quite a few errors reported

due to failure to recreate the original <filename>contrib/tsearch2</>

objects. These errors can be ignored, but this means you cannot

restore the dump in a single transaction (eg, you cannot use

<application>pg_restore</>'s <literal>-1</> switch).

</para>

</step>

<step>

<para>

Examine the contents of the restored <filename>contrib/tsearch2</>

configuration tables (<structname>pg_ts_cfg</> and so on), and

create equivalent built-in text search configurations as needed.

You may drop the old configuration tables once you've extracted

all the useful information from them.

</para>

</step>

<step>

<para>

Test your application.

</para>

</step>

</procedure>

<para>

At a later time you may wish to rename application references

to the alias text search objects, so that you can eventually

uninstall the replacement <literal>tsearch2</literal> module.

</para>

</sect2>

<sect2>

<title>References</title>

<para>

Tsearch2 Development Site

<ulink url="http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/"></ulink>

</para>

</sect2>

</sect1>