|
| 1 | +Shared ISpell Dictionary |
| 2 | +======================== |
| 3 | +This PostgreSQL extension provides a shared ispell dictionary, i.e. |
| 4 | +a dictionary that's stored in shared segment. The traditional ispell |
| 5 | +implementation means that each session initializes and stores the |
| 6 | +dictionary on it's own, which means a lot of CPU/RAM is wasted. |
| 7 | + |
| 8 | +This extension allocates an area in shared segment (you have to |
| 9 | +choose the size in advance) and then loads the dictionary into it |
| 10 | +when it's used for the first time. |
| 11 | + |
| 12 | +If you need just snowball-type dictionaries, this extension is not |
| 13 | +really interesting for you. But if you really need an ispell |
| 14 | +dictionary, this may save you a lot of resources. |
| 15 | + |
| 16 | + |
| 17 | +Install |
| 18 | +------- |
| 19 | +Installing the extension is quite simple, especially if you're on 9.1. |
| 20 | +In that case all you need to do is this: |
| 21 | + |
| 22 | +$ make install |
| 23 | + |
| 24 | +and then (after connecting to the database) |
| 25 | + |
| 26 | +db=# CREATE EXTENSION shared_ispell; |
| 27 | + |
| 28 | +If you're on pre-9.1 version, you'll have to do the second part manually |
| 29 | +by running the SQL script (shared_ispell--x.y.sql) in the database. If |
| 30 | +needed, replace MODULE_PATHNAME by $libdir. |
| 31 | + |
| 32 | + |
| 33 | +Config |
| 34 | +------ |
| 35 | +No the functions are created, but you still need to load the shared |
| 36 | +module. This needs to be done from postgresql.conf, as the module |
| 37 | +needs to allocate space in the shared memory segment. So add this to |
| 38 | +the config file (or update the current values) |
| 39 | + |
| 40 | +# libraries to load |
| 41 | +shared_preload_libraries = 'shared_ispell' |
| 42 | + |
| 43 | +# known GUC prefixes |
| 44 | +custom_variable_classes = 'shared_ispell' |
| 45 | + |
| 46 | +# config of the shared memory |
| 47 | +shared_ispell.max_size = 32MB |
| 48 | + |
| 49 | +Yes, there's a single GUC variable that defines the maximum size of |
| 50 | +the shared segment. This is a hard limit, the shared segment is not |
| 51 | +extensible and you need to set it so that all the dictionaries fit |
| 52 | +into it and not much memory is wasted. |
| 53 | + |
| 54 | +To find out how much memory you actually need, use a large value |
| 55 | +(e.g. 200MB) and load all the dictionaries you want to use. Then use |
| 56 | +the shared_ispell_mem_used() function to find out how much memory |
| 57 | +was actually used (and set the max_size GUC variable accordingly). |
| 58 | + |
| 59 | +Don't set it exactly to that value, leave there some free space, |
| 60 | +so that you can reload the dictionaries without changing the GUC |
| 61 | +max_size limit (which requires a restart of the DB). Ssomething |
| 62 | +like 512kB should be just fine. |
| 63 | + |
| 64 | +The shared segment can contain several dictionaries at the same time, |
| 65 | +the amount of memory is the only limit. There's no limit on number |
| 66 | +of dictionaries / words etc. Just the max_size GUC variable. |
| 67 | + |
| 68 | + |
| 69 | +Using the dictionary |
| 70 | +-------------------- |
| 71 | +Technically, the extension defines a 'shared_ispell' template that |
| 72 | +you may use to define custom dictionaries. E.g. you may do this |
| 73 | + |
| 74 | +CREATE TEXT SEARCH DICTIONARY czech_shared ( |
| 75 | + TEMPLATE = shared_ispell, |
| 76 | + DictFile = czech, |
| 77 | + AffFile = czech, |
| 78 | + StopWords = czech |
| 79 | +); |
| 80 | + |
| 81 | +CREATE TEXT SEARCH CONFIGURATION public.czech_shared |
| 82 | + ( COPY = pg_catalog.simple ); |
| 83 | + |
| 84 | +ALTER TEXT SEARCH CONFIGURATION czech_shared |
| 85 | + ALTER MAPPING FOR asciiword, asciihword, hword_asciipart, |
| 86 | + word, hword, hword_part |
| 87 | + WITH czech_shared; |
| 88 | + |
| 89 | +and then do the usual stuff, e.g. |
| 90 | + |
| 91 | +db=# SELECT ts_lexize('czech_shared', 'automobile'); |
| 92 | + |
| 93 | +or whatever you want. |
| 94 | + |
| 95 | + |
| 96 | +Available functions |
| 97 | +------------------- |
| 98 | +The extension provides five management functions, that allow you to |
| 99 | +manage and get info about the preloaded dictionaries. The first two |
| 100 | +functions |
| 101 | + |
| 102 | +shared_ispell_mem_used() |
| 103 | +shared_ispell_mem_available() |
| 104 | + |
| 105 | +allow you to get info about the shared segment (used and free memory) |
| 106 | +e.g. to properly size the segment (max_size). Then there are functions |
| 107 | +return list of dictionaries / stop lists loaded in the shared segment |
| 108 | + |
| 109 | +shared_ispell_dicts() |
| 110 | +shared_ispell_stoplists() |
| 111 | + |
| 112 | +e.g. like this |
| 113 | + |
| 114 | +db=# SELECT * FROM shared_ispell_dicts(); |
| 115 | + |
| 116 | + dict_name | affix_name | words | affixes | bytes |
| 117 | +-----------+------------+-------+---------+---------- |
| 118 | + bulgarian | bulgarian | 79267 | 12 | 7622128 |
| 119 | + czech | czech | 96351 | 2544 | 12715000 |
| 120 | +(2 rows) |
| 121 | + |
| 122 | + |
| 123 | +db=# SELECT * FROM shared_ispell_stoplists(); |
| 124 | + |
| 125 | + stop_name | words | bytes |
| 126 | +-----------+-------+------- |
| 127 | + czech | 259 | 4552 |
| 128 | +(1 row) |
| 129 | + |
| 130 | +The last function allows you to reset the dictionary (e.g. so that you |
| 131 | +can reload the updated files from disk). The sessions that already use |
| 132 | +the dictionaries will be forced to reinitialize them (the first one |
| 133 | +will rebuild and copy them in the shared segment, the other ones will |
| 134 | +use this prepared data). |
| 135 | + |
| 136 | +db=# SELECT shared_ispell_reset(); |
| 137 | + |
| 138 | +That's all for now ... |
