1DBD::File::HowTo(3) User Contributed Perl Documentation DBD::File::HowTo(3)
2
6 DBD::File::HowTo - Guide to create DBD::File based driver
7
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
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 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 Those who are still reading, should be able to sing the rules of
34 "CREATING A NEW DRIVER" in DBI::DBD.
35 Of course, DBD::File is a DBI::DBD::SqlEngine and you surely read
37 DBI::DBD::SqlEngine::HowTo before continuing here.
38
40 Do you have an entry in DBI's DBD registry? For this guide, a prefix of
41 "foo_" is assumed.
42 Sample Skeleton
44 package DBD::Foo;
45 use strict;
47 use warnings;
48 use vars qw(@ISA $VERSION);
49 use base qw(DBD::File);
50 use DBI ();
52 $VERSION = "0.001";
54 package DBD::Foo::dr;
56 use vars qw(@ISA $imp_data_size);
58 @ISA = qw(DBD::File::dr);
60 $imp_data_size = 0;
61 package DBD::Foo::db;
63 use vars qw(@ISA $imp_data_size);
65 @ISA = qw(DBD::File::db);
67 $imp_data_size = 0;
68 package DBD::Foo::st;
70 use vars qw(@ISA $imp_data_size);
72 @ISA = qw(DBD::File::st);
74 $imp_data_size = 0;
75 package DBD::Foo::Statement;
77 use vars qw(@ISA);
79 @ISA = qw(DBD::File::Statement);
81 package DBD::Foo::Table;
83 use vars qw(@ISA);
85 @ISA = qw(DBD::File::Table);
87 1;
89 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 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 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 package DBD::Foo::Table;
103 sub bootstrap_table_meta
105 {
106 my ( $self, $dbh, $meta, $table ) = @_;
107 # initialize all $meta attributes which might be relevant for
109 # file2table
110 return $self->SUPER::bootstrap_table_meta($dbh, $meta, $table);
112 }
113 sub init_table_meta
115 {
116 my ( $self, $dbh, $meta, $table ) = @_;
117 # called after $meta contains the results from file2table
119 # initialize all missing $meta attributes
120 $self->SUPER::init_table_meta( $dbh, $meta, $table );
122 }
123 In case "DBD::File::Table::open_file" doesn't open the files as the
125 driver needs that, override it!
126 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 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 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 sub init_valid_attributes
147 {
148 my $dbh = $_[0];
149 $dbh->SUPER::init_valid_attributes ();
151 $dbh->{foo_valid_attrs} = { ... };
153 $dbh->{foo_readonly_attrs} = { ... };
154 $dbh->{foo_meta} = "foo_tables";
156 return $dbh;
158 }
159 See updates at "User comfort" in DBI::DBD::SqlEngine::HowTo.
161 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
169 This guide is written by Jens Rehsack. DBD::File is written by Jochen
170 Wiedmann and Jeff Zucker.
171 The module DBD::File is currently maintained by
173 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 All rights reserved.
181 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.
185perl v5.36.0 2023-01-20 DBD::File::HowTo(3)