File Coverage

blib/lib/FTN/Database.pm
Criterion Covered Total %
statement 51 70 72.8
branch 10 28 35.7
condition n/a
subroutine 10 12 83.3
pod 8 8 100.0
total 79 118 66.9


line stmt bran cond sub pod time code
1             package FTN::Database;
2              
3 5     5   64384 use warnings;
  5         8  
  5         128  
4 5     5   14 use strict;
  5         5  
  5         81  
5 5     5   15 use Carp qw( croak );
  5         7  
  5         585  
6              
7             =head1 NAME
8              
9             FTN::Database - FTN SQL Database related operations for Fidonet/FTN related processing.
10              
11             =head1 VERSION
12              
13             Version 0.40
14              
15             =cut
16              
17             our $VERSION = '0.40';
18              
19             =head1 DESCRIPTION
20              
21             FTN::Database are Perl modules containing common database related operations
22             and definitions for Fidonet/FTN related SQL Database processing. The SQL database
23             engine is one for which a DBD module exists, defaulting to SQLite.
24              
25             =head1 EXPORT
26              
27             The following functions are available in this module: create_ftn_database, open_ftn_database,
28             close_ftn_database, drop_ftn_database, drop_ftn_table, create_ftn_index, and drop_ftn_index.
29              
30             =head1 FUNCTIONS
31              
32             =head2 create_ftn_database
33              
34             Syntax: create_ftn_database($db_handle, $database_name);
35              
36             Create an SQL database for use for Fidonet/FTN processing, where
37             $db_handle is an existing open database handle and $database_name
38             is the name of the database being created.
39              
40             =cut
41              
42             sub create_ftn_database {
43              
44 0     0 1 0 my($db_handle, $database_name) = @_;
45              
46 0         0 my $sql_statement = "CREATE DATABASE $database_name";
47              
48 0 0       0 $db_handle->do("$sql_statement") or croak($DBI::errstr);
49              
50 0         0 return 1;
51              
52             }
53              
54             =head2 open_ftn_database
55              
56             Syntax: $db_handle = open_ftn_database(\%db_options);
57              
58             Open a database for Fidonet/FTN processing, where $db_handle is the
59             database handle being returned to the calling program and the referenced
60             hash contains the following items:
61              
62             =over
63              
64             =item Type
65              
66             The database type. This needs to be a database type for which
67             a DBD module exists, the type being the name as used in the DBD
68             module. The default type to be used is SQLite.
69              
70             =item Host
71              
72             The host name of the database server. If blank or not provided, a driver
73             specific default is used. Not required If the Type is SQLite,
74              
75             =item Port
76              
77             The port number for the database server. If blank or not provided, a driver
78             specific default is used. Not required If the Type is SQLite,
79              
80             =item Name
81              
82             The name of the database to be opened. If the Type is SQLite, this
83             is a filename and path to the database file.
84              
85             =item User
86              
87             The database user, which should already have the neccesary priviledges.
88              
89             =item Password
90              
91             The database password for the database user.
92              
93             =back
94              
95             =cut
96              
97             sub open_ftn_database {
98              
99 5     5   6490 use DBI;
  5         55998  
  5         2379  
100              
101             # Get the hash reference to the information required for the connect
102 3     3 1 492 my $option = shift;
103              
104             # Construct DSN for the database connection.
105 3         4 my $db_dsn = "dbi:${$option}{'Type'}";
  3         17  
106             # If DB type is MySQL, use "database" instead of "dbname" in DSN.
107 3 50       3 if (${$option}{'Type'} eq 'mysql') {
  3         9  
108 0         0 $db_dsn .= ":database=${$option}{'Name'}";
  0         0  
109             } else {
110 3         2 $db_dsn .= ":dbname=${$option}{'Name'}";
  3         5  
111             }
112             # If Host option exists and is not empty, add it to DSN.
113 3 50       3 if (exists ${$option}{'Host'}) {
  3         8  
114 0 0       0 if (${$option}{'Host'} ne '') {
  0         0  
115 0         0 $db_dsn .= ":host=${$option}{'Host'}";
  0         0  
116             }
117             }
118             # If Port option exists and is not empty, add it to DSN.
119 3 50       2 if (exists ${$option}{'Port'}) {
  3         6  
120 0 0       0 if (${$option}{'Port'} ne '') {
  0         0  
121 0         0 $db_dsn .= ":port=${$option}{'Port'}";
  0         0  
122             }
123             }
124              
125             ( my $db_handle = DBI->connect(
126             $db_dsn,
127 3         5 ${$option}{'User'},
128 3 50       3 ${$option}{'Password'} ) )
  3         21  
129             or croak($DBI::errstr);
130              
131 3         23966 return($db_handle);
132              
133             }
134              
135             =head2 close_ftn_database
136              
137             Syntax: close_ftn_database($db_handle);
138              
139             Closing an FTN database, where $db_handle is an existing open database handle.
140              
141             =cut
142              
143             sub close_ftn_database {
144              
145 3     3 1 4 my $db_handle = shift;
146              
147 3 50       74 ( $db_handle->disconnect ) or croak($DBI::errstr);
148              
149 3         10 return 1;
150              
151             }
152              
153             =head2 drop_ftn_database
154              
155             Syntax: drop_ftn_database($db_handle, $database_name);
156              
157             Drop an SQL database being used for Fidonet/FTN processing if
158             it exists, where $db_handle is an existing open database handle
159             and $database_name is the name of the database being dropped.
160              
161             =cut
162              
163             sub drop_ftn_database {
164              
165 0     0 1 0 my($db_handle, $database_name) = @_;
166              
167 0         0 my $sql_statement = "DROP DATABASE IF EXISTS $database_name";
168              
169 0 0       0 $db_handle->do("$sql_statement") or croak($DBI::errstr);
170              
171 0         0 return 1;
172              
173             }
174              
175             =head2 create_ftn_table
176              
177             Syntax: create_ftn_table($db_handle, $table_name, $defined_fields);
178              
179             Create a table in an SQL database to be used for Fidonet/FTN processing where
180             $db_handle is an existing open database handle, $table_name is the name of the
181             table to be created, and $defined_fields is the sql to define the fields to be
182             used for the table except for an id field which is set according to the driver
183             type.
184              
185             The string defining the fields could be coded like this:
186             $defined_fields = "nodeaka VARCHAR(23) DEFAULT '' NOT NULL, ";
187             $defined_fields .= "sysop VARCHAR(48) DEFAULT '' NOT NULL, ";
188             $defined_fields .= "system VARCHAR(48) DEFAULT '' NOT NULL, ";
189             $defined_fields .= "location VARCHAR(48) DEFAULT '' NOT NULL ";
190              
191             =cut
192              
193             sub create_ftn_table {
194              
195 4     4 1 1848 my($db_handle, $table_name, $define_fields) = @_;
196              
197 4         7 my $sql_statement = "CREATE TABLE $table_name( ";
198             # If DB type is PostgreSQL, use SERIAL; else use INTEGER & AUTOINCREMENT
199 4 50       86 if ($db_handle->{Driver}->{Name} eq 'Pg') {
200 0         0 $sql_statement .= "id SERIAL PRIMARY KEY NOT NULL, ";
201             } else {
202 4         7 $sql_statement .= "id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, ";
203             }
204 4         9 $sql_statement .= $define_fields;
205 4         4 $sql_statement .= ") ";
206              
207 4 50       19 $db_handle->do("$sql_statement ") or croak($DBI::errstr);
208              
209 4         1457 return 1;
210              
211             }
212              
213             =head2 drop_ftn_table
214              
215             Syntax: drop_ftn_table($db_handle, $table_name);
216              
217             Drop an FTN table from an SQL database being used for Fidonet/FTN
218             processing if it exists, where $db_handle is an existing open database handle
219             and $table_name is the name of the table to be dropped.
220              
221             =cut
222              
223             sub drop_ftn_table {
224              
225 4     4 1 16 my($db_handle, $table_name) = @_;
226              
227 4         8 my $sql_statement = "DROP TABLE IF EXISTS $table_name";
228              
229 4 50       20 $db_handle->do("$sql_statement") or croak($DBI::errstr);
230              
231 4         339 return 1;
232              
233             }
234              
235             =head2 create_ftn_index
236              
237             Syntax: create_ftn_index($db_handle, $table_name, $index_name, $indexed_fields);
238              
239             Create an index named $index_name on table $table_name in an SQL database being
240             used for Fidonet/FTN processing; where $db_handle is an existing open database
241             handle, the $table_name is the name of the table that is being indexed, and
242             $index_name is the name of the index itself. The index is created on the
243             fields listed in $indexed_fields, with the field names separated by commas.
244              
245             =cut
246              
247             sub create_ftn_index {
248              
249 4     4 1 14 my($db_handle, $table_name, $index_name, $indexed_fields) = @_;
250              
251 4         7 my $sql_statement = "CREATE INDEX $index_name ";
252 4         11 $sql_statement .= "ON $table_name ($indexed_fields) ";
253              
254 4 50       21 $db_handle->do("$sql_statement") or croak($DBI::errstr);
255              
256 4         497 return 1;
257              
258             }
259              
260             =head2 drop_ftn_index
261              
262             Syntax: drop_ftn_index($db_handle,$index_name);
263              
264             Drop an index from an FTN table in an SQL database being used for Fidonet/FTN
265             processing if it exists, where $db_handle is an existing open database handle,
266             and $index_name is the name of the index to be dropped.
267              
268             =cut
269              
270             sub drop_ftn_index {
271              
272 4     4 1 6 my($db_handle, $index_name) = @_;
273              
274 4         8 my $sql_statement = "DROP INDEX IF EXISTS $index_name";
275              
276 4 50       22 $db_handle->do("$sql_statement") or croak($DBI::errstr);
277              
278 4         316 return 1;
279              
280             }
281              
282             =head1 EXAMPLES
283              
284             An example of opening an FTN database, then closing it:
285              
286             use FTN::Database;
287              
288             my $db_handle = open_ftn_database(\%db_option);
289             ...
290             close_ftn_database($db_handle);
291              
292             An example of creating a database for FTN related processing, using a
293             mysql database:
294              
295             use FTN::Database;
296              
297             my $db_name = "ftndbtst";
298             my $db_option = {
299             Type = "mysql",
300             Name = $db_name,
301             User = $db_user,
302             Password = $db_password,
303             };
304             my $db_handle = open_ftn_database(\%db_option);
305             create_ftn_database($db_handle, $database_name);
306             ...
307             close_ftn_database($db_handle);
308              
309             An example of dropping a database being used for FTN related processing,
310             using a mysql database:
311              
312             use FTN::Database;
313              
314             my $db_name = "ftndbtst";
315             my $db_option = {
316             Type = 'mysql',
317             Name = $db_name,
318             User = $db_user,
319             Password = $db_password,
320             };
321             my $db_handle = open_ftn_database(\%db_option);
322             ...
323             drop_ftn_database($db_handle, $db_name);
324             close_ftn_database($db_handle);
325              
326              
327             =head1 AUTHOR
328              
329             Robert James Clay, C<< >>
330              
331             =head1 BUGS
332              
333             Please report any bugs or feature requests via the web interface at
334             L. I will be
335             notified, and then you'll automatically be notified of progress on
336             your bug as I make changes.
337              
338             Note that you can also report any bugs or feature requests to
339             C, or through the web interface at
340             L;
341             however, the FTN-Database Issue tracker at the SourceForge
342             project is preferred.
343              
344             =head1 SUPPORT
345              
346             You can find documentation for this module with the perldoc command.
347              
348             perldoc FTN::Database
349              
350              
351             You can also look for information at:
352              
353             =over 4
354              
355             =item * FTN::Database issue tracker
356              
357             L
358              
359             =item * RT: CPAN's request tracker
360              
361             L
362              
363             =item * Search CPAN
364              
365             L
366              
367             =back
368              
369             =head1 SEE ALSO
370              
371             L, L, L,
372             L
373              
374             =head1 COPYRIGHT & LICENSE
375              
376             Copyright 2010-2013 Robert James Clay, all rights reserved.
377              
378             This program is free software; you can redistribute it and/or modify it
379             under the same terms as Perl itself.
380              
381             =cut
382              
383             1; # End of FTN::Database