1Wiki::Toolkit::Store::DUastearbaCsoen(t3r)ibuted Perl DoWciukmie:n:tTaotoiloknit::Store::Database(3)
2
3
4

NAME

6       Wiki::Toolkit::Store::Database - parent class for database storage
7       backends for Wiki::Toolkit
8

SYNOPSIS

10       This is probably only useful for Wiki::Toolkit developers.
11
12         # See below for parameter details.
13         my $store = Wiki::Toolkit::Store::MySQL->new( %config );
14

METHODS

16       new
17             my $store = Wiki::Toolkit::Store::MySQL->new( dbname  => "wiki",
18                                   dbuser  => "wiki",
19                                   dbpass  => "wiki",
20                                   dbhost  => "db.example.com",
21                                   dbport  => 1234,
22                                   charset => "iso-8859-1" );
23           or
24
25             my $store = Wiki::Toolkit::Store::MySQL->new( dbh => $dbh );
26
27           "charset" is optional, defaults to "iso-8859-1", and does nothing
28           unless you're using perl 5.8 or newer.
29
30           If you do not provide an active database handle in "dbh", then
31           "dbname" is mandatory. "dbpass", "dbuser", "dbhost" and "dbport"
32           are optional, but you'll want to supply them unless your database's
33           connection method doesn't require them.
34
35           If you do provide "database" then it must have the following
36           parameters set; otherwise you should just provide the connection
37           information and let us create our own handle:
38
39           •   "RaiseError" = 1
40
41           •   "PrintError" = 0
42
43           •   "AutoCommit" = 1
44
45       retrieve_node
46             my $content = $store->retrieve_node($node);
47
48             # Or get additional meta-data too.
49             my %node = $store->retrieve_node("HomePage");
50             print "Current Version: " . $node{version};
51
52             # Maybe we stored some metadata too.
53             my $categories = $node{metadata}{category};
54             print "Categories: " . join(", ", @$categories);
55             print "Postcode: $node{metadata}{postcode}[0]";
56
57             # Or get an earlier version:
58             my %node = $store->retrieve_node(name    => "HomePage",
59                                    version => 2 );
60             print $node{content};
61
62           In scalar context, returns the current (raw Wiki language) contents
63           of the specified node. In list context, returns a hash containing
64           the contents of the node plus additional data:
65
66           last_modified
67           version
68           checksum
69           metadata - a reference to a hash containing any caller-supplied
70           metadata sent along the last time the node was written
71
72           The node parameter is mandatory. The version parameter is optional
73           and defaults to the newest version. If the node hasn't been created
74           yet, it is considered to exist but be empty (this behaviour might
75           change).
76
77           Note on metadata - each hash value is returned as an array ref,
78           even if that type of metadata only has one value.
79
80       node_exists
81             my $ok = $store->node_exists( "Wombat Defenestration" );
82
83             # or ignore case - optional but recommended
84             my $ok = $store->node_exists(
85                                           name        => "monkey brains",
86                                           ignore_case => 1,
87                                         );
88
89           Returns true if the node has ever been created (even if it is
90           currently empty), and false otherwise.
91
92           By default, the case-sensitivity of "node_exists" depends on your
93           database.  If you supply a true value to the "ignore_case"
94           parameter, then you can be sure of its being case-insensitive.
95           This is recommended.
96
97       verify_checksum
98             my $ok = $store->verify_checksum($node, $checksum);
99
100           Sees whether your checksum is current for the given node. Returns
101           true if so, false if not.
102
103           NOTE: Be aware that when called directly and without locking, this
104           might not be accurate, since there is a small window between the
105           checking and the returning where the node might be changed, so
106           don't rely on it for safe commits; use "write_node" for that. It
107           can however be useful when previewing edits, for example.
108
109       list_backlinks
110             # List all nodes that link to the Home Page.
111             my @links = $store->list_backlinks( node => "Home Page" );
112
113       list_dangling_links
114             # List all nodes that have been linked to from other nodes but don't
115             # yet exist.
116             my @links = $store->list_dangling_links;
117
118           Each node is returned once only, regardless of how many other nodes
119           link to it.
120
121       write_node_post_locking
122             $store->write_node_post_locking( node     => $node,
123                                              content  => $content,
124                                              links_to => \@links_to,
125                                              metadata => \%metadata,
126                                              requires_moderation => $requires_moderation,
127                                              plugins  => \@plugins   )
128                 or handle_error();
129
130           Writes the specified content into the specified node, then calls
131           "post_write" on all supplied plugins, with arguments "node",
132           "version", "content", "metadata".
133
134           Making sure that locking/unlocking/transactions happen is left up
135           to you (or your chosen subclass). This method shouldn't really be
136           used directly as it might overwrite someone else's changes. Croaks
137           on error but otherwise returns the version number of the update
138           just made.  A return value of -1 indicates that the change was not
139           applied.  This may be because the plugins voted against the change,
140           or because the content and metadata in the proposed new version
141           were identical to the current version (a "null" change).
142
143           Supplying a ref to an array of nodes that this ones links to is
144           optional, but if you do supply it then this node will be returned
145           when calling "list_backlinks" on the nodes in @links_to. Note that
146           if you don't supply the ref then the store will assume that this
147           node doesn't link to any others, and update itself accordingly.
148
149           The metadata hashref is also optional, as is requires_moderation.
150
151           Note on the metadata hashref: Any data in here that you wish to
152           access directly later must be a key-value pair in which the value
153           is either a scalar or a reference to an array of scalars.  For
154           example:
155
156             $wiki->write_node( "Calthorpe Arms", "nice pub", $checksum,
157                                { category => [ "Pubs", "Bloomsbury" ],
158                                  postcode => "WC1X 8JR" } );
159
160             # and later
161
162             my @nodes = $wiki->list_nodes_by_metadata(
163                 metadata_type  => "category",
164                 metadata_value => "Pubs"             );
165
166           For more advanced usage (passing data through to registered
167           plugins) you may if you wish pass key-value pairs in which the
168           value is a hashref or an array of hashrefs. The data in the
169           hashrefs will not be stored as metadata; it will be checksummed and
170           the checksum will be stored instead (as
171           "__metadatatypename__checksum"). Such data can only be accessed via
172           plugins.
173
174       rename_node
175             $store->rename_node(
176                                    old_name  => $node,
177                                    new_name  => $new_node,
178                                    wiki      => $wiki,
179                                    create_new_versions => $create_new_versions,
180                                  );
181
182           Renames a node, updating any references to it as required (assuming
183           your chosen formatter supports rename, that is).
184
185           Uses the internal_links table to identify the nodes that link to
186           this one, and re-writes any wiki links in these to point to the new
187           name.
188
189       moderate_node
190             $store->moderate_node(
191                                    name    => $node,
192                                    version => $version
193                                  );
194
195           Marks the given version of the node as moderated. If this is the
196           highest moderated version, then update the node's contents to hold
197           this version.
198
199       set_node_moderation
200             $store->set_node_moderation(
201                                    name     => $node,
202                                    required => $required
203                                  );
204
205           Sets if new node versions will require moderation or not
206
207       delete_node
208             $store->delete_node(
209                                  name    => $node,
210                                  version => $version,
211                                  wiki    => $wiki
212                                );
213
214           "version" is optional.  If it is supplied then only that version of
215           the node will be deleted.  Otherwise the node and all its history
216           will be completely deleted.
217
218           "wiki" is also optional, but if you care about updating the
219           backlinks you want to include it.
220
221           Again, doesn't do any locking. You probably don't want to let
222           anyone except Wiki admins call this. You may not want to use it at
223           all.
224
225           Croaks on error, silently does nothing if the node or version
226           doesn't exist, returns true if no error.
227
228       list_recent_changes
229             # Nodes changed in last 7 days - each node listed only once.
230             my @nodes = $store->list_recent_changes( days => 7 );
231
232             # Nodes added in the last 7 days.
233             my @nodes = $store->list_recent_changes(
234                                                      days     => 7,
235                                                      new_only => 1,
236                                                    );
237
238             # All changes in last 7 days - nodes changed more than once will
239             # be listed more than once.
240             my @nodes = $store->list_recent_changes(
241                                                      days => 7,
242                                                      include_all_changes => 1,
243                                                    );
244
245             # Nodes changed between 1 and 7 days ago.
246             my @nodes = $store->list_recent_changes( between_days => [ 1, 7 ] );
247
248             # Nodes changed since a given time.
249             my @nodes = $store->list_recent_changes( since => 1036235131 );
250
251             # Most recent change and its details.
252             my @nodes = $store->list_recent_changes( last_n_changes => 1 );
253             print "Node:          $nodes[0]{name}";
254             print "Last modified: $nodes[0]{last_modified}";
255             print "Comment:       $nodes[0]{metadata}{comment}";
256
257             # Last 5 restaurant nodes edited.
258             my @nodes = $store->list_recent_changes(
259                 last_n_changes => 5,
260                 metadata_is    => { category => "Restaurants" }
261             );
262
263             # Last 5 nodes edited by Kake.
264             my @nodes = $store->list_recent_changes(
265                 last_n_changes => 5,
266                 metadata_was   => { username => "Kake" }
267             );
268
269             # All minor edits made by Earle in the last week.
270             my @nodes = $store->list_recent_changes(
271                 days           => 7,
272                 metadata_was   => { username  => "Earle",
273                                     edit_type => "Minor tidying." }
274             );
275
276             # Last 10 changes that weren't minor edits.
277             my @nodes = $store->list_recent_changes(
278                 last_n_changes => 10,
279                 metadata_wasnt  => { edit_type => "Minor tidying" }
280             );
281
282           You must supply one of the following constraints: "days" (integer),
283           "since" (epoch), "last_n_changes" (integer).
284
285           You may also supply moderation => 1 if you only want to see
286           versions that are moderated.
287
288           Another optional parameter is "new_only", which if set to 1 will
289           only return newly added nodes.
290
291           You may also supply either "metadata_is" (and optionally
292           "metadata_isnt"), or "metadata_was" (and optionally
293           "metadata_wasnt"). Each of these should be a ref to a hash with
294           scalar keys and values.  If the hash has more than one entry, then
295           only changes satisfying all criteria will be returned when using
296           "metadata_is" or "metadata_was", but all changes which fail to
297           satisfy any one of the criteria will be returned when using
298           "metadata_isnt" or "metadata_is".
299
300           "metadata_is" and "metadata_isnt" look only at the metadata that
301           the node currently has. "metadata_was" and "metadata_wasnt" take
302           into account the metadata of previous versions of a node.  Don't
303           mix "is" with "was" - there's no check for this, but the results
304           are undefined.
305
306           Returns results as an array, in reverse chronological order.  Each
307           element of the array is a reference to a hash with the following
308           entries:
309
310name: the name of the node
311
312version: the version number of the node
313
314last_modified: timestamp showing when this version was written
315
316metadata: a ref to a hash containing any metadata attached to
317               this version of the node
318
319           Unless you supply "include_all_changes", "metadata_was" or
320           "metadata_wasnt", each node will only be returned once regardless
321           of how many times it has been changed recently.
322
323           By default, the case-sensitivity of both "metadata_type" and
324           "metadata_value" depends on your database - if it will return rows
325           with an attribute value of "Pubs" when you asked for "pubs", or
326           not.  If you supply a true value to the "ignore_case" parameter,
327           then you can be sure of its being case-insensitive.  This is
328           recommended.
329
330       list_all_nodes
331             my @nodes = $store->list_all_nodes();
332             print "First node is $nodes[0]\n";
333
334             my @nodes = $store->list_all_nodes( with_details=> 1 );
335             print "First node is ".$nodes[0]->{'name'}." at version ".$nodes[0]->{'version'}."\n";
336
337           Returns a list containing the name of every existing node.  The
338           list won't be in any kind of order; do any sorting in your calling
339           script.
340
341           Optionally also returns the id, version and moderation flag.
342
343       list_node_all_versions
344             my @all_versions = $store->list_node_all_versions(
345                 name => 'HomePage',
346                 with_content => 1,
347                 with_metadata => 0
348             );
349
350           Returns all the versions of a node, optionally including the
351           content and metadata, as an array of hashes (newest versions
352           first).
353
354       list_nodes_by_metadata
355             # All documentation nodes.
356             my @nodes = $store->list_nodes_by_metadata(
357                 metadata_type  => "category",
358                 metadata_value => "documentation",
359                 ignore_case    => 1,   # optional but recommended (see below)
360             );
361
362             # All pubs in Hammersmith.
363             my @pubs = $store->list_nodes_by_metadata(
364                 metadata_type  => "category",
365                 metadata_value => "Pub",
366             );
367             my @hsm  = $store->list_nodes_by_metadata(
368                 metadata_type  => "category",
369                 metadata_value  => "Hammersmith",
370             );
371             my @results = my_l33t_method_for_ANDing_arrays( \@pubs, \@hsm );
372
373           Returns a list containing the name of every node whose caller-
374           supplied metadata matches the criteria given in the parameters.
375
376           By default, the case-sensitivity of both "metadata_type" and
377           "metadata_value" depends on your database - if it will return rows
378           with an attribute value of "Pubs" when you asked for "pubs", or
379           not.  If you supply a true value to the "ignore_case" parameter,
380           then you can be sure of its being case-insensitive.  This is
381           recommended.
382
383           If you don't supply any criteria then you'll get an empty list.
384
385           This is a really really really simple way of finding things; if you
386           want to be more complicated then you'll need to call the method
387           multiple times and combine the results yourself, or write a plugin.
388
389       list_nodes_by_missing_metadata Returns nodes where either the metadata
390       doesn't exist, or is blank
391           Unlike list_nodes_by_metadata(), the metadata value is optional.
392
393             # All nodes missing documentation
394             my @nodes = $store->list_nodes_by_missing_metadata(
395                 metadata_type  => "category",
396                 metadata_value => "documentation",
397                 ignore_case    => 1,   # optional but recommended (see below)
398             );
399
400             # All nodes which don't have a latitude defined
401             my @nodes = $store->list_nodes_by_missing_metadata(
402                 metadata_type  => "latitude"
403             );
404
405       _get_list_by_metadata_sql
406           Return the SQL to do a match by metadata. Should expect the
407           metadata type as the first SQL parameter, and the metadata value as
408           the second.
409
410           If possible, should take account of $args{ignore_case}
411
412       _get_list_by_missing_metadata_sql
413           Return the SQL to do a match by missing metadata. Should expect the
414           metadata type as the first SQL parameter.
415
416           If possible, should take account of $args{ignore_case}
417
418       list_unmoderated_nodes
419             my @nodes = $wiki->list_unmoderated_nodes();
420             my @nodes = $wiki->list_unmoderated_nodes(
421                                                           only_where_latest => 1
422                                                       );
423
424             $nodes[0]->{'name'}              # The name of the node
425             $nodes[0]->{'node_id'}           # The id of the node
426             $nodes[0]->{'version'}           # The version in need of moderation
427             $nodes[0]->{'moderated_version'} # The newest moderated version
428
429             With only_where_latest set, return the id, name and version of all the
430              nodes where the most recent version needs moderation.
431             Otherwise, returns the id, name and version of all node versions that need
432              to be moderated.
433
434       list_last_version_before
435               List the last version of every node before a given date.
436               If no version existed before that date, will return undef for version.
437               Returns a hash of id, name, version and date
438
439               my @nv = $wiki->list_last_version_before('2007-01-02 10:34:11')
440               foreach my $data (@nv) {
441
442               }
443
444       list_metadata_by_type
445               List all the currently defined values of the given type of metadata.
446
447               Will only return data from the latest moderated version of each node
448
449               # List all of the different metadata values with the type 'category'
450               my @categories = $wiki->list_metadata_by_type('category');
451
452       list_metadata_names
453               List all the currently defined kinds of metadata, eg Locale, Postcode
454
455               Will only return data from the latest moderated version of each node
456
457               # List all of the different kinds of metadata
458               my @metadata_types = $wiki->list_metadata_names()
459
460       schema_current
461             my ($code_version, $db_version) = $store->schema_current;
462             if ($code_version == $db_version)
463                 # Do stuff
464             } else {
465                 # Bail
466             }
467
468       dbh
469             my $dbh = $store->dbh;
470
471           Returns the database handle belonging to this storage backend
472           instance.
473
474       dbname
475             my $dbname = $store->dbname;
476
477           Returns the name of the database used for backend storage.
478
479       dbuser
480             my $dbuser = $store->dbuser;
481
482           Returns the username used to connect to the database used for
483           backend storage.
484
485       dbpass
486             my $dbpass = $store->dbpass;
487
488           Returns the password used to connect to the database used for
489           backend storage.
490
491       dbhost
492             my $dbhost = $store->dbhost;
493
494           Returns the optional host used to connect to the database used for
495           backend storage.
496
497
498
499perl v5.32.1                      2021-01-27 Wiki::Toolkit::Store::Database(3)
Impressum