Add some quick documentation for tsearch2 compatibility module.
This commit is contained in:
parent
c027fa5757
commit
4c2d0cd5e4
|
@ -55,6 +55,7 @@
|
||||||
&seg;
|
&seg;
|
||||||
&sslinfo;
|
&sslinfo;
|
||||||
&tablefunc;
|
&tablefunc;
|
||||||
|
&tsearch2;
|
||||||
&uuid-ossp;
|
&uuid-ossp;
|
||||||
&vacuumlo;
|
&vacuumlo;
|
||||||
&xml2;
|
&xml2;
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
<!-- $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 history SYSTEM "history.sgml">
|
||||||
<!entity info SYSTEM "info.sgml">
|
<!entity info SYSTEM "info.sgml">
|
||||||
|
@ -117,6 +117,7 @@
|
||||||
<!entity seg SYSTEM "seg.sgml">
|
<!entity seg SYSTEM "seg.sgml">
|
||||||
<!entity sslinfo SYSTEM "sslinfo.sgml">
|
<!entity sslinfo SYSTEM "sslinfo.sgml">
|
||||||
<!entity tablefunc SYSTEM "tablefunc.sgml">
|
<!entity tablefunc SYSTEM "tablefunc.sgml">
|
||||||
|
<!entity tsearch2 SYSTEM "tsearch2.sgml">
|
||||||
<!entity uuid-ossp SYSTEM "uuid-ossp.sgml">
|
<!entity uuid-ossp SYSTEM "uuid-ossp.sgml">
|
||||||
<!entity vacuumlo SYSTEM "vacuumlo.sgml">
|
<!entity vacuumlo SYSTEM "vacuumlo.sgml">
|
||||||
<!entity xml2 SYSTEM "xml2.sgml">
|
<!entity xml2 SYSTEM "xml2.sgml">
|
||||||
|
|
|
@ -0,0 +1,201 @@
|
||||||
|
<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>
|
Loading…
Reference in New Issue