1Wiki::Toolkit::Store::DUastearbaCsoen(t3r)ibuted Perl DoWciukmie:n:tTaotoiloknit::Store::Database(3)
2
6 Wiki::Toolkit::Store::Database - parent class for database storage
7 backends for Wiki::Toolkit
8
10 This is probably only useful for Wiki::Toolkit developers.
11 # See below for parameter details.
13 my $store = Wiki::Toolkit::Store::MySQL->new( %config );
14
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 my $store = Wiki::Toolkit::Store::MySQL->new( dbh => $dbh );
26 "charset" is optional, defaults to "iso-8859-1", and does nothing
28 unless you're using perl 5.8 or newer.
29 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 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 • "RaiseError" = 1
40 • "PrintError" = 0
42 • "AutoCommit" = 1
44 retrieve_node
46 my $content = $store->retrieve_node($node);
47 # Or get additional meta-data too.
49 my %node = $store->retrieve_node("HomePage");
50 print "Current Version: " . $node{version};
51 # 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 # Or get an earlier version:
58 my %node = $store->retrieve_node(name => "HomePage",
59 version => 2 );
60 print $node{content};
61 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 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 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 Note on metadata - each hash value is returned as an array ref,
78 even if that type of metadata only has one value.
79 node_exists
81 my $ok = $store->node_exists( "Wombat Defenestration" );
82 # or ignore case - optional but recommended
84 my $ok = $store->node_exists(
85 name => "monkey brains",
86 ignore_case => 1,
87 );
88 Returns true if the node has ever been created (even if it is
90 currently empty), and false otherwise.
91 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 verify_checksum
98 my $ok = $store->verify_checksum($node, $checksum);
99 Sees whether your checksum is current for the given node. Returns
101 true if so, false if not.
102 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 list_backlinks
110 # List all nodes that link to the Home Page.
111 my @links = $store->list_backlinks( node => "Home Page" );
112 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 Each node is returned once only, regardless of how many other nodes
119 link to it.
120 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 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 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 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 The metadata hashref is also optional, as is requires_moderation.
150 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 $wiki->write_node( "Calthorpe Arms", "nice pub", $checksum,
157 { category => [ "Pubs", "Bloomsbury" ],
158 postcode => "WC1X 8JR" } );
159 # and later
161 my @nodes = $wiki->list_nodes_by_metadata(
163 metadata_type => "category",
164 metadata_value => "Pubs" );
165 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 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 Renames a node, updating any references to it as required (assuming
183 your chosen formatter supports rename, that is).
184 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 moderate_node
190 $store->moderate_node(
191 name => $node,
192 version => $version
193 );
194 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 set_node_moderation
200 $store->set_node_moderation(
201 name => $node,
202 required => $required
203 );
204 Sets if new node versions will require moderation or not
206 delete_node
208 $store->delete_node(
209 name => $node,
210 version => $version,
211 wiki => $wiki
212 );
213 "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 "wiki" is also optional, but if you care about updating the
219 backlinks you want to include it.
220 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 Croaks on error, silently does nothing if the node or version
226 doesn't exist, returns true if no error.
227 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 # Nodes added in the last 7 days.
233 my @nodes = $store->list_recent_changes(
234 days => 7,
235 new_only => 1,
236 );
237 # 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 # Nodes changed between 1 and 7 days ago.
246 my @nodes = $store->list_recent_changes( between_days => [ 1, 7 ] );
247 # Nodes changed since a given time.
249 my @nodes = $store->list_recent_changes( since => 1036235131 );
250 # 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 # Last 5 restaurant nodes edited.
258 my @nodes = $store->list_recent_changes(
259 last_n_changes => 5,
260 metadata_is => { category => "Restaurants" }
261 );
262 # 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 # 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 # 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 You must supply one of the following constraints: "days" (integer),
283 "since" (epoch), "last_n_changes" (integer).
284 You may also supply moderation => 1 if you only want to see
286 versions that are moderated.
287 Another optional parameter is "new_only", which if set to 1 will
289 only return newly added nodes.
290 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 "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 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 • name: the name of the node
311 • version: the version number of the node
313 • last_modified: timestamp showing when this version was written
315 • metadata: a ref to a hash containing any metadata attached to
317 this version of the node
318 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 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 list_all_nodes
331 my @nodes = $store->list_all_nodes();
332 print "First node is $nodes[0]\n";
333 my @nodes = $store->list_all_nodes( with_details=> 1 );
335 print "First node is ".$nodes[0]->{'name'}." at version ".$nodes[0]->{'version'}."\n";
336 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 Optionally also returns the id, version and moderation flag.
342 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 Returns all the versions of a node, optionally including the
351 content and metadata, as an array of hashes (newest versions
352 first).
353 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 # 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 Returns a list containing the name of every node whose caller-
374 supplied metadata matches the criteria given in the parameters.
375 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 If you don't supply any criteria then you'll get an empty list.
384 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 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 # 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 # All nodes which don't have a latitude defined
401 my @nodes = $store->list_nodes_by_missing_metadata(
402 metadata_type => "latitude"
403 );
404 _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 If possible, should take account of $args{ignore_case}
411 _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 If possible, should take account of $args{ignore_case}
417 list_unmoderated_nodes
419 my @nodes = $wiki->list_unmoderated_nodes();
420 my @nodes = $wiki->list_unmoderated_nodes(
421 only_where_latest => 1
422 );
423 $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 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 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 my @nv = $wiki->list_last_version_before('2007-01-02 10:34:11')
440 foreach my $data (@nv) {
441 }
443 list_metadata_by_type
445 List all the currently defined values of the given type of metadata.
446 Will only return data from the latest moderated version of each node
448 # List all of the different metadata values with the type 'category'
450 my @categories = $wiki->list_metadata_by_type('category');
451 list_metadata_names
453 List all the currently defined kinds of metadata, eg Locale, Postcode
454 Will only return data from the latest moderated version of each node
456 # List all of the different kinds of metadata
458 my @metadata_types = $wiki->list_metadata_names()
459 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 dbh
469 my $dbh = $store->dbh;
470 Returns the database handle belonging to this storage backend
472 instance.
473 dbname
475 my $dbname = $store->dbname;
476 Returns the name of the database used for backend storage.
478 dbuser
480 my $dbuser = $store->dbuser;
481 Returns the username used to connect to the database used for
483 backend storage.
484 dbpass
486 my $dbpass = $store->dbpass;
487 Returns the password used to connect to the database used for
489 backend storage.
490 dbhost
492 my $dbhost = $store->dbhost;
493 Returns the optional host used to connect to the database used for
495 backend storage.
496perl v5.32.1 2021-01-27 Wiki::Toolkit::Store::Database(3)