1DBD::File::HowTo(3)   User Contributed Perl Documentation  DBD::File::HowTo(3)
2
3
4

NAME

6       DBD::File::HowTo - Guide to create DBD::File based driver
7

SYNOPSIS

9         perldoc DBD::File::HowTo
10         perldoc DBI
11         perldoc DBI::DBD
12         perldoc DBD::File::Developers
13         perldoc DBI::DBD::SqlEngine::Developers
14         perldoc DBI::DBD::SqlEngine
15         perldoc SQL::Eval
16         perldoc DBI::DBD::SqlEngine::HowTo
17         perldoc SQL::Statement::Embed
18         perldoc DBD::File
19         perldoc DBD::File::HowTo
20         perldoc DBD::File::Developers
21

DESCRIPTION

23       This document provides a step-by-step guide, how to create a new
24       "DBD::File" based DBD. It expects that you carefully read the DBI
25       documentation and that you're familiar with DBI::DBD and had read and
26       understood DBD::ExampleP.
27
28       This document addresses experienced developers who are really sure that
29       they need to invest time when writing a new DBI Driver. Writing a DBI
30       Driver is neither a weekend project nor an easy job for hobby coders
31       after work. Expect one or two man-month of time for the first start.
32
33       Those who are still reading, should be able to sing the rules of
34       "CREATING A NEW DRIVER" in DBI::DBD.
35
36       Of course, DBD::File is a DBI::DBD::SqlEngine and you surely read
37       DBI::DBD::SqlEngine::HowTo before continuing here.
38

CREATING DRIVER CLASSES

40       Do you have an entry in DBI's DBD registry? For this guide, a prefix of
41       "foo_" is assumed.
42
43   Sample Skeleton
44           package DBD::Foo;
45
46           use strict;
47           use warnings;
48           use vars qw(@ISA $VERSION);
49           use base qw(DBD::File);
50
51           use DBI ();
52
53           $VERSION = "0.001";
54
55           package DBD::Foo::dr;
56
57           use vars qw(@ISA $imp_data_size);
58
59           @ISA = qw(DBD::File::dr);
60           $imp_data_size = 0;
61
62           package DBD::Foo::db;
63
64           use vars qw(@ISA $imp_data_size);
65
66           @ISA = qw(DBD::File::db);
67           $imp_data_size = 0;
68
69           package DBD::Foo::st;
70
71           use vars qw(@ISA $imp_data_size);
72
73           @ISA = qw(DBD::File::st);
74           $imp_data_size = 0;
75
76           package DBD::Foo::Statement;
77
78           use vars qw(@ISA);
79
80           @ISA = qw(DBD::File::Statement);
81
82           package DBD::Foo::Table;
83
84           use vars qw(@ISA);
85
86           @ISA = qw(DBD::File::Table);
87
88           1;
89
90       Tiny, eh? And all you have now is a DBD named foo which will be able to
91       deal with temporary tables, as long as you use SQL::Statement. In
92       DBI::SQL::Nano environments, this DBD can do nothing.
93
94   Start over
95       Based on DBI::DBD::SqlEngine::HowTo, we're now having a driver which
96       could do basic things. Of course, it should now derive from DBD::File
97       instead of DBI::DBD::SqlEngine, shouldn't it?
98
99       DBD::File extends DBI::DBD::SqlEngine to deal with any kind of files.
100       In principle, the only extensions required are to the table class:
101
102           package DBD::Foo::Table;
103
104           sub bootstrap_table_meta
105           {
106               my ( $self, $dbh, $meta, $table ) = @_;
107
108               # initialize all $meta attributes which might be relevant for
109               # file2table
110
111               return $self->SUPER::bootstrap_table_meta($dbh, $meta, $table);
112           }
113
114           sub init_table_meta
115           {
116               my ( $self, $dbh, $meta, $table ) = @_;
117
118               # called after $meta contains the results from file2table
119               # initialize all missing $meta attributes
120
121               $self->SUPER::init_table_meta( $dbh, $meta, $table );
122           }
123
124       In case "DBD::File::Table::open_file" doesn't open the files as the
125       driver needs that, override it!
126
127           sub open_file
128           {
129               my ( $self, $meta, $attrs, $flags ) = @_;
130               # ensure that $meta->{f_dontopen} is set
131               $self->SUPER::open_file( $meta, $attrs, $flags );
132               # now do what ever needs to be done
133           }
134
135       Combined with the methods implemented using the SQL::Statement::Embed
136       guide, the table is full working and you could try a start over.
137
138   User comfort
139       "DBD::File" since 0.39 consolidates all persistent meta data of a table
140       into a single structure stored in "$dbh->{f_meta}". With "DBD::File"
141       version 0.41 and "DBI::DBD::SqlEngine" version 0.05, this consolidation
142       moves to DBI::DBD::SqlEngine. It's still the "$dbh->{$drv_prefix .
143       "_meta"}" attribute which cares, so what you learned at this place
144       before, is still valid.
145
146           sub init_valid_attributes
147           {
148               my $dbh = $_[0];
149
150               $dbh->SUPER::init_valid_attributes ();
151
152               $dbh->{foo_valid_attrs} = { ... };
153               $dbh->{foo_readonly_attrs} = { ...  };
154
155               $dbh->{foo_meta} = "foo_tables";
156
157               return $dbh;
158           }
159
160       See updates at "User comfort" in DBI::DBD::SqlEngine::HowTo.
161
162   Testing
163       Now you should have your own DBD::File based driver. Was easy, wasn't
164       it?  But does it work well?  Prove it by writing tests and remember to
165       use dbd_edit_mm_attribs from DBI::DBD to ensure testing even rare
166       cases.
167

AUTHOR

169       This guide is written by Jens Rehsack. DBD::File is written by Jochen
170       Wiedmann and Jeff Zucker.
171
172       The module DBD::File is currently maintained by
173
174       H.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack  < rehsack
175       at googlemail.com >
176
178       Copyright (C) 2010 by H.Merijn Brand & Jens Rehsack
179
180       All rights reserved.
181
182       You may freely distribute and/or modify this module under the terms of
183       either the GNU General Public License (GPL) or the Artistic License, as
184       specified in the Perl README file.
185
186
187
188perl v5.36.0                      2023-01-20               DBD::File::HowTo(3)
Impressum