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.  It's
11       compatible with SQLite and possibly other standard SQL servers.
12
13       Do not use this for MySQL/MariaDB or PgSQL, they have their own
14       specific modules.
15

METHODS

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

Private Methods

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