diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml index 67a158d4f5..fecce0a845 100644 --- a/doc/src/sgml/contrib.sgml +++ b/doc/src/sgml/contrib.sgml @@ -55,6 +55,7 @@ &seg; &sslinfo; &tablefunc; + &tsearch2; &uuid-ossp; &vacuumlo; &xml2; diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index a1a8d048ed..6857e8dda7 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -1,4 +1,4 @@ - + @@ -117,6 +117,7 @@ + diff --git a/doc/src/sgml/tsearch2.sgml b/doc/src/sgml/tsearch2.sgml new file mode 100644 index 0000000000..8d5ba50b20 --- /dev/null +++ b/doc/src/sgml/tsearch2.sgml @@ -0,0 +1,201 @@ + + tsearch2 + + + tsearch2 + + + + The tsearch2 module provides backwards-compatible + text search functionality for applications that used + contrib/tsearch2 before text searching was integrated + into core PostgreSQL in release 8.3. + + + + Portability Issues + + + Although the built-in text search features were based on + contrib/tsearch2 and are largely similar to it, + there are numerous small differences that will create portability + issues for existing applications: + + + + + + Some functions' names were changed, for example rank + to ts_rank. + The replacement tsearch2 module + provides aliases having the old names. + + + + + + The built-in text search data types and functions all exist within + the system schema pg_catalog. In an installation using + contrib/tsearch2, these objects would usually have been in + the 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 tsearch2 module + provides alias objects that are stored in public + (or another schema if necessary) so that such references will still work. + + + + + + There is no concept of a current parser or current + dictionary in the built-in text search features, only of a current + search configuration (set by the 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 tsearch2 module emulates these + additional state variables and provides backwards-compatible functions + for setting and retrieving them. + + + + + + There are some issues that are not addressed by the replacement + tsearch2 module, and will therefore require + application code changes in any case: + + + + + + The old 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 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. + + + + + + Text search configuration information has been moved into core + system catalogs that are noticeably different from the tables used + by contrib/tsearch2. Any applications that examined + or modified those tables will need adjustment. + + + + + + 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 tsearch2 module offers a little + bit of support for this by making it possible to load an old set + of contrib/tsearch2 configuration tables into + PostgreSQL 8.3. (Without the module, + it is not possible to load the configuration data because values in the + regprocedure columns cannot be resolved to functions.) + While those configuration tables won't actually do + anything, at least their contents will be available to be consulted + while setting up an equivalent custom configuration in 8.3. + + + + + + The old reset_tsearch() and get_covers() + functions are not supported. + + + + + + The replacement tsearch2 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. + + + + + + + + Converting a pre-8.3 Installation + + + The recommended way to update a pre-8.3 installation that uses + contrib/tsearch2 is: + + + + + + Make a dump from the old installation in the usual way, + but be sure not to use -c (--clean) + option of pg_dump or pg_dumpall. + + + + + + In the new installation, create empty database(s) and install + the replacement tsearch2 module into each + database that will use text search. This must be done + before loading the dump data! If your old installation + had the contrib/tsearch2 objects in a schema other + than public, be sure to adjust the + tsearch2 installation script so that the replacement + objects are created in that same schema. + + + + + + Load the dump data. There will be quite a few errors reported + due to failure to recreate the original contrib/tsearch2 + objects. These errors can be ignored, but this means you cannot + restore the dump in a single transaction (eg, you cannot use + pg_restore's -1 switch). + + + + + + Examine the contents of the restored contrib/tsearch2 + configuration tables (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. + + + + + + Test your application. + + + + + + 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 tsearch2 module. + + + + + + References + + Tsearch2 Development Site + + + + +