1Mail::SpamAssassin::BayUesseSrtoCroen:t:rSiQbLu(t3e)d PeMralilD:o:cSupmaemnAtsastaisosnin::BayesStore::SQL(3)
2
3
4

NAME

6       Mail::SpamAssassin::BayesStore::SQL - SQL Bayesian Storage Module
7       Implementation
8

DESCRIPTION

10       This module implements a SQL based bayesian storage module.
11

METHODS

13   new
14       public class (Mail::SpamAssassin::BayesStore::SQL) new
15       (Mail::Spamassassin::Plugin::Bayes $bayes)
16
17       Description: This methods creates a new instance of the
18       Mail::SpamAssassin::BayesStore::SQL object.  It expects to be passed an
19       instance of the Mail::SpamAssassin:Bayes object which is passed into
20       the Mail::SpamAssassin::BayesStore parent object.
21
22       This method sets up the database connection and determines the username
23       to use in queries.
24
25   tie_db_readonly
26       public instance (Boolean) tie_db_readonly ();
27
28       Description: This method ensures that the database connection is
29       properly setup and working.  If necessary it will initialize a user's
30       bayes variables so that they can begin using the database immediately.
31
32   tie_db_writable
33       public instance (Boolean) tie_db_writable ()
34
35       Description: This method ensures that the database connection is
36       properly setup and working. If necessary it will initialize a users
37       bayes variables so that they can begin using the database immediately.
38
39   untie_db
40       public instance () untie_db ()
41
42       Description: Disconnects from an SQL server.
43
44   calculate_expire_delta
45       public instance (%) calculate_expire_delta (Integer $newest_atime,
46                                                    Integer $start,
47                                                    Integer $max_expire_mult)
48
49       Description: This method performs a calculation on the data to
50       determine the optimum atime for token expiration.
51
52   token_expiration
53       public instance (Integer, Integer,
54                        Integer, Integer) token_expiration(\% $opts,
55                                                           Integer $newdelta,
56                                                           @ @vars)
57
58       Description: This method performs the database specific expiration of
59       tokens based on the passed in $newdelta and @vars.
60
61   sync_due
62       public instance (Boolean) sync_due ()
63
64       Description: This method determines if a database sync is currently
65       required.
66
67       Unused for SQL based implementation.
68
69   seen_get
70       public instance (String) seen_get (string $msgid)
71
72       Description: This method retrieves the stored value, if any, for
73       $msgid.  The return value is the stored string ('s' for spam and 'h'
74       for ham) or undef if $msgid is not found.
75
76   seen_put
77       public (Boolean) seen_put (string $msgid, char $flag)
78
79       Description: This method records $msgid as the type given by $flag.
80       $flag is one of two values 's' for spam and 'h' for ham.
81
82   seen_delete
83       public instance (Boolean) seen_delete (string $msgid)
84
85       Description: This method removes $msgid from the database.
86
87   get_storage_variables
88       public instance (@) get_storage_variables ()
89
90       Description: This method retrieves the various administrative variables
91       used by the Bayes process and database.
92
93       The values returned in the array are in the following order:
94
95       0: scan count base
96
97       1: number of spam
98
99       2: number of ham
100
101       3: number of tokens in db
102
103       4: last expire atime
104
105       5: oldest token in db atime
106
107       6: db version value
108
109       7: last journal sync
110
111       8: last atime delta
112
113       9: last expire reduction count
114
115       10: newest token in db atime
116
117   dump_db_toks
118       public instance () dump_db_toks (String $template, String $regex, Array
119       @vars)
120
121       Description: This method loops over all tokens, computing the
122       probability for the token and then printing it out according to the
123       passed in token.
124
125   set_last_expire
126       public instance (Boolean) set_last_expire (Integer $time)
127
128       Description: This method sets the last expire time.
129
130   get_running_expire_tok
131       public instance (String $time) get_running_expire_tok ()
132
133       Description: This method determines if an expire is currently running
134       and returns the last time set.
135
136       There can be multiple times, so we just pull the greatest (most recent)
137       value.
138
139   set_running_expire_tok
140       public instance (String $time) set_running_expire_tok ()
141
142       Description: This method sets the time that an expire starts running.
143
144   remove_running_expire_tok
145       public instance (Boolean) remove_running_expire_tok ()
146
147       Description: This method removes the row in the database that indicates
148       that and expire is currently running.
149
150   tok_get
151       public instance (Integer, Integer, Integer) tok_get (String $token)
152
153       Description: This method retrieves a specified token ($token) from the
154       database and returns it's spam_count, ham_count and last access time.
155
156   tok_get_all
157       public instance (\@) tok_get (@ $tokens)
158
159       Description: This method retrieves the specified tokens ($tokens) from
160       storage and returns an array ref of arrays spam count, ham count and
161       last access time.
162
163   tok_count_change
164       public instance (Boolean) tok_count_change (Integer $spam_count,
165                                    Integer $ham_count,
166                                    String $token,
167       String $atime)
168
169       Description: This method takes a $spam_count and $ham_count and adds it
170       to $tok along with updating $toks atime with $atime.
171
172   multi_tok_count_change
173       public instance (Boolean) multi_tok_count_change (Integer $spam_count,
174                                          Integer $ham_count,
175                                           \% $tokens,
176                                          String $atime)
177
178       Description: This method takes a $spam_count and $ham_count and adds it
179       to all of the tokens in the $tokens hash ref along with updating each
180       token's atime with $atime.
181
182   nspam_nham_get
183       public instance ($spam_count, $ham_count) nspam_nham_get ()
184
185       Description: This method retrieves the total number of spam and the
186       total number of ham learned.
187
188   nspam_nham_change
189       public instance (Boolean) nspam_nham_change (Integer $num_spam,
190                                                    Integer $num_ham)
191
192       Description: This method updates the number of spam and the number of
193       ham in the database.
194
195   tok_touch
196       public instance (Boolean) tok_touch (String $token,
197                                            String $atime)
198
199       Description: This method updates the given tokens ($token) atime.
200
201       The assumption is that the token already exists in the database.
202
203   tok_touch_all
204       public instance (Boolean) tok_touch (\@ $tokens
205                                            String $atime)
206
207       Description: This method does a mass update of the given list of tokens
208       $tokens, if the existing token atime is < $atime.
209
210       The assumption is that the tokens already exist in the database.
211
212       We should never be touching more than N_SIGNIFICANT_TOKENS, so we can
213       make some assumptions about how to handle the data (ie no need to batch
214       like we do in tok_get_all)
215
216   cleanup
217       public instance (Boolean) cleanup ()
218
219       Description: This method performs any cleanup necessary before moving
220       onto the next operation.
221
222   get_magic_re
223       public instance get_magic_re (String)
224
225       Description: This method returns a regexp which indicates a magic
226       token.
227
228       Unused in SQL implementation.
229
230   sync
231       public instance (Boolean) sync (\% $opts)
232
233       Description: This method performs a sync of the database
234
235   perform_upgrade
236       public instance (Boolean) perform_upgrade (\% $opts);
237
238       Description: Performs an upgrade of the database from one version to
239       another, not currently used in this implementation.
240
241   clear_database
242       public instance (Boolean) clear_database ()
243
244       Description: This method deletes all records for a particular user.
245
246       Callers should be aware that any errors returned by this method could
247       cause the database to be inconsistent for the given user.
248
249   backup_database
250       public instance (Boolean) backup_database ()
251
252       Description: This method will dump the users database in a machine
253       readable format.
254
255   restore_database
256       public instance (Boolean) restore_database (String $filename, Boolean
257       $showdots)
258
259       Description: This method restores a database from the given filename,
260       $filename.
261
262       Callers should be aware that any errors returned by this method could
263       causes the database to be inconsistent for the given user.
264
265   db_readable
266       public instance (Boolean) db_readable()
267
268       Description: This method returns a boolean value indicating if the
269       database is in a readable state.
270
271   db_writable
272       public instance (Boolean) db_writeable()
273
274       Description: This method returns a boolean value indicating if the
275       database is in a writable state.
276

Private Methods

278   _connect_db
279       private instance (Boolean) _connect_db ()
280
281       Description: This method connects to the SQL database.
282
283   _get_db_version
284       private instance (Integer) _get_db_version ()
285
286       Description: Gets the current version of the database from the special
287       global vars tables.
288
289   _initialize_db
290       private instance (Boolean) _initialize_db ()
291
292       Description: This method will check to see if a user has had their
293       bayes variables initialized. If not then it will perform this
294       initialization.
295
296   _put_token
297       private instance (Boolean) _put_token (string $token,
298                                              integer $spam_count,
299                                              integer $ham_count,
300                                  string $atime)
301
302       Description: This method performs the work of either inserting or
303       updating a token in the database.
304
305   _put_tokens
306       private instance (Boolean) _put_tokens (\% $tokens,
307                                               integer $spam_count,
308                                               integer $ham_count,
309                             string $atime)
310
311       Description: This method performs the work of either inserting or
312       updating tokens in the database.
313
314   _get_oldest_token_age
315       private instance (Integer) _get_oldest_token_age ()
316
317       Description: This method finds the atime of the oldest token in the
318       database.
319
320       The use of min(atime) in the SQL is ugly and but really the most
321       efficient way of getting the oldest_token_age after we've done a mass
322       expire.  It should only be called at expire time.
323
324   _get_num_hapaxes
325       private instance (Integer) _get_num_hapaxes ()
326
327       Description: This method gets the total number of hapaxes (spam_count +
328       ham_count == 1) in the token database for a user.
329
330   _get_num_lowfreq
331       private instance (Integer) _get_num_lowfreq ()
332
333       Description: This method gets the total number of lowfreq tokens
334       (spam_count < 8 and ham_count < 8) in the token database for a user
335
336   _token_select_string
337       private instance (String) _token_select_string
338
339       Description: This method returns the string to be used in SELECT
340       statements to represent the token column.
341
342       The default is to use the RPAD function to pad the token out to 5
343       characters.
344
345
346
347perl v5.34.0                      2022-01M-a2i2l::SpamAssassin::BayesStore::SQL(3)