Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 328 lines (228 sloc) 12.581 kb
80e1f00 @jjn1056 added a start on the FAQ
authored
1 =head1 NAME
2
0bfcb68 @jjn1056 fixed incorrect namespace
authored
3 DBIx::Class::Migration::FAQ - Answers to Frequently Asked Questions
80e1f00 @jjn1056 added a start on the FAQ
authored
4
5 =head1 When I run the commandline, I see a lot of debugging output
6
7 SV = IV(0x7fb4e24dc858) at 0x7fb4e24dc868
8 REFCNT = 1
9 FLAGS = (ROK,READONLY)
10 RV = 0x7fb4e0b0ddf8
11 SV = PVHV(0x7fb4e24c48a0) at 0x7fb4e0b0ddf8
12 REFCNT = 1
13 FLAGS = (OBJECT,SHAREKEYS)
14 STASH = 0x7fb4e2174a80 "DBI::db"
15 ARRAY = 0x0
16 KEYS = 0
17 FILL = 0
18 MAX = 7
19 RITER = -1
20
1893d35 @logie17 Fixed a typo and link the deploy handler.
logie17 authored
21 There's some debugging code somewhere in the L<DBIx::Class::DeploymentHandler>
80e1f00 @jjn1056 added a start on the FAQ
authored
22 dependency chain. We've looked and can't find it :( A case of beer at the
23 next YAPC we meet at to whoever can figure it out.
24
1893d35 @logie17 Fixed a typo and link the deploy handler.
logie17 authored
25 Although if you see this, there's nothing wrong. The command will work as in
80e1f00 @jjn1056 added a start on the FAQ
authored
26 the documentation. The only issue is that if there's a lot of debugging scroll
27 by, you might need to page up in your terminal to catch any real error
28 messages.
29
352243d @jjn1056 increased dependency version and some docs
authored
30 B<UPDATE>: I recieved an email from a contributor who has code dived a bit
31 and possibly narrowed down the issue. I thought to report that stuff here.
32 When L<SQLT::Parser::DBIx::Class> attempts to serialize schemas that are connected
33 it trys to serialize the connect object information. This doesn't play so nice
34 with the way the YAML serializer works, since it does try hard to serialize
35 objects.
36
9c6f415 @jjn1056 make a doubtful test author side only
authored
37 B<UPDATE>: This may be fixed in recent updates to the DBIC ecosystem. If you
38 are seeing this try upgraded DBIC and SQLT and see if it goes away.
39
02eb56e @jjn1056 updated faq
authored
40 B<UPDATE>: You really should not be seeing this anymore, if you are, and you're
41 on the lastest DBIC and related, please let me know.
352243d @jjn1056 increased dependency version and some docs
authored
42
80e1f00 @jjn1056 added a start on the FAQ
authored
43 =head1 Contributing
44
ac8cfc0 @jjn1056 more in the FAQ about common errors
authored
45 Contributing to the project is easy. First you'd fork the project over at
80e1f00 @jjn1056 added a start on the FAQ
authored
46 Github (L<https://github.com/jjn1056/DBIx-Class-Migration>), clone the repo
47 down to your work environment and install project dependencies:
48
49 cpanm Dist::Zilla
50 dzil authordeps | cpanm
51 dzil listdeps | cpanm
52
53 You should first have a Modern Perl setup, including L<local::lib>. If you
54 need help installing Perl and getting started, please take a look at the
55 Learning Perl website: L<http://learn.perl.org/installing/>
56
57 =head1 Dist::Zilla?
58
59 I realize L<Dist::Zilla> seems to invoke feelings on nearly religious vigor
60 (both for and against). After considering the options I felt using it, but
61 carefully constraining the use of plugins to the default set was a better
62 option than what I've done on other projects, which is to have a custom wrapper
63 on top of L<Module::Install> (you can peek at that if you want over here:
4604973 @jjn1056 text changes after copyreading
authored
64 L<https://github.com/jjn1056/Maker>). I've decided I'd rather not
ac8cfc0 @jjn1056 more in the FAQ about common errors
authored
65 continue to spend my limited time dealing with dependency and installation
80e1f00 @jjn1056 added a start on the FAQ
authored
66 management tools, when there's a rational solution that many people already
67 embrace available. The only other option is to continue to build and maintain
68 code for this purpose that nobody else uses, and possibly nobody else
69 understands.
70
71 If a better option with equal or greater maturity and community acceptance
72 emerges, I'll entertain changing.
73
74 If the requirement of typing C<cpanm Dist::Zilla> and using the C<dzil> command
75 line tool for a limited number of build jobs prevents you from contributing,
76 I think you are unreasonably stubborn.
77
78 If you do contribute to the project, please be aware that I'm not likely to
79 accept patches that include significant changes to the way I'm using
80 L<Dist::Zilla>, including using plugins to weave pod, automagically guess
81 dependencies and generate tests. I'd prefer to stick to the most simple and
82 standard Perl practices for building and installing code for the present.
83
b6eb9d9 @jjn1056 updated FAQ to tell people how to avoid having the sandbox stuff in the ...
authored
84 =head1 I don't want my database sandbox files in my source control repository
85
86 Having the database sandboxes automatically created in the C<share> directory
87 is a nice feature, but can clutter your repository history. You really don't
88 need that in the source control, since installing and controlling your database
89 is something each developer who checks out the project should do.
90
91 If you are using C<git> you can modify your C<.gitignore>. If you sandbox is
92 C<share/myapp-schema.db> or (if you are using the mysql or postgresql sandboxes)
93 C<share/myapp-schema/> you can add these lines to your C<.gitignore>
94
95 share/musicbase-schema/*
96 share/musicbase-schema.db
97
98 Other source control systems have similiar approaches (recipies welcome for
99 sharing).
100
e45bbd9 @jjn1056 lots of documentation fixes, and retesting the tutorial from scratch
authored
101 =head1 What's the command to run migrations on an existing database?
102
103 dbic-migration -Ilib status \
104 --dsn="DBI:mysql:database=test;host=127.0.0.1;port=5142" \
105 --user msandbox \
106 --password msandbox
107
108 Would be the general approach.
109
b4daa8c @jjn1056 lots of typo fixes and new faq entry;
authored
110 =head1 Error: Trouble creating a MySQL Sandbox when running AppArmor
111
112 Its been reported that the developer database sandboxing feature doens't
113 work properly when using AppArmor. I guess AppArmor considers this a
114 security violation. Currently I don't have a reported workaround other than
115 to just disable AppArmor, which for developer level machines may or may not
116 be a problem.
117
118 Here's some symptoms of this problem, if you think you may be having it:
119
120 In C</var/log/syslog> something like:
121
122 kernel: [18593519.090601] type=1503 audit(1281847667.413:22):
123 operation="inode_permission" requested_mask="::r" denied_mask="::r"
124 fsuid=0 name="/etc/mysql0/my.cnf" pid=4884 profile="/usr/sbin/mysqld"
125
126 If you need AppArmor, you'll have to setup and install MySQL the 'old school
127 way.'
128
ac8cfc0 @jjn1056 more in the FAQ about common errors
authored
129 =head1 Error: "Failed to find share dir for dist..."
130
4604973 @jjn1056 text changes after copyreading
authored
131 You didn't specify a custom C<--target_dir> but forgot to make the C</share>
132 directory in your project application root.
133
134 By default we expect to find a C</share> directory in your primary project root
135 directory (contains your C<Makefile.PL> or C<dist.ini>, and the C<lib> and C<t>
136 directories for example) where we will create migrations. At this time we can't
ac8cfc0 @jjn1056 more in the FAQ about common errors
authored
137 automatically create this C</share> directory in the same way we can create all
138 the migration files and directory for you. You need to create that directory
139 yourself:
140
141 mkdir share
142
143 Patches to fix this, or suggestions welcomed.
144
14a1fe3 @jjn1056 added some stuff to the FAQ about using this even if you dont want to us...
authored
145 =head1 Can I use this even if I don't want to use DBIx::Class?
146
147 Not everyone loves using an ORM. Personally I've found L<DBIx::Class> to be
148 the only ORM that gets enough out of my way that I prefer it over plain SQL,
149 and I highly recommend you give it a go. However if you don't want to, or can
ed91010 @jjn1056 minor doc updates
authored
150 not convince your fellow programers (yet :) ), here's one way to still use this
99fc072 @jjn1056 fixed minor typo and elaborated on the docs a bit
authored
151 migrations and fixtures system. Strictly speaking, we are stilling using
152 L<DBIx::Class> behind the scenes, just you don't have to know about it or
153 use it.
14a1fe3 @jjn1056 added some stuff to the FAQ about using this even if you dont want to us...
authored
154
99fc072 @jjn1056 fixed minor typo and elaborated on the docs a bit
authored
155 You use a subclass of L<DBIx::Class::Schema::Loader> in a namespace for your
156 application, like:
14a1fe3 @jjn1056 added some stuff to the FAQ about using this even if you dont want to us...
authored
157
158 package MyApp::Schema;
159
160 use strict;
161 use warnings;
162
163 use base 'DBIx::Class::Schema::Loader';
164
165 our $VERSION = 1;
166
167 __PACKAGE__->naming('current');
168 __PACKAGE__->use_namespaces(1);
169 __PACKAGE__->loader_options( );
170
171 1;
172
99fc072 @jjn1056 fixed minor typo and elaborated on the docs a bit
authored
173 You'd put that in C<lib/MyApp/Schema.pm> along with your other application code.
14a1fe3 @jjn1056 added some stuff to the FAQ about using this even if you dont want to us...
authored
174 then just use C<MyApp::Schema> as is discussed in the documentation. This will
175 dynamically build a schema for you, as long as you set the schema arguments to
176 connect to your actual database. Then everytime someone changes the database
177 you just up the C<$VERSION> and take it from there. Obviously this is a bit
178 more manual effort, but at least you can have the ability to populate to any
179 given version, manage fixtures, do some sane testing, etc. Maybe you'll even
180 be able to convince people to try out L<DBIx::Class>!
181
182 By the way, if you wanted, you can always dump the generated version of your
183 classes using C<make_schema> (see L<DBIx::Class::Migrations/make_schema> and
184 L<DBIx::Class::Migrations::Script/make_schema>).
185
e45bbd9 @jjn1056 lots of documentation fixes, and retesting the tutorial from scratch
authored
186 =head1 I am using MySQL and when the migration fails, it doesn't ROLLBACK
187
188 That's because MySQL does not support transaction DDL. Even if you have a
189 transaction, MySQL will silently COMMIT when it bumps into some DDL.
190
cb0eeaf @jjn1056 let you dump fixtures from unversioned databases
authored
191 =head1 I need to dump fixtures from a existing database
192
193 You don't always have the luxury of building a new database from the start.
194 For example, you may have an existing database that you want to start to
195 create migrations for. In this case you probably want to dump some data
196 directly from that existing database in order to create fixtures for testing
197 or for seeding a new database.
198
199 L<DBIx::Class::Migration> will let you run the C<dump_all_sets> and C<dump_named_sets>
200 commands against an unversioned database. For example:
201
202 dbic-migration -Ilib -SMyApp::Schema dump_all_sets /
203 --dsn="dbi:mysql:database=myapp;host=10.0.88.98;port=3306" /
204 --username johnn /
205 --password $PASSWORD
206
207 In this case let's say "dbi:mysql:database=myapp;host=10.0.88.98;port=3306" is
208 a database that you've been managing manually and it has some data that is useful
209 for creating your fixture sets.
210
211 When you run these commands against an unversioned database you will be warned
212 because we have no way of being sure what version of the fixture sets you should
213 be dumping. We will just assume that whatever the Schema version is, is correct.
214 This can of course lead to bad or undumpable fixtures should your Schema and the
215 unversioned DB not match properly. Buyer beware!
216
ac8cfc0 @jjn1056 more in the FAQ about common errors
authored
217 =head1 Error: "`' is not a module name"
218
219 Sorry this error is vague and I am working on a fix. You will get this if you
220 have failed to provide a C<schema_class>, either by setting it with the -S or
221 -schema_class commandline option flag:
222
223 dbic-migration -Ilib -SMyApp::Schema
224 dbic-migration -Ilib --schema_class MyApp::Schema
225
226 or by exporting the %ENV:
227
228 export DBIC_MIGRATION_SCHEMA_CLASS=MyApp::Schema
229
230 Or, if you have a custom version of L<DBIx::Class::Migration::Script> as
ed91010 @jjn1056 minor doc updates
authored
231 discussed in the tutorial, you are not providing a good C<schema_class> value.
ac8cfc0 @jjn1056 more in the FAQ about common errors
authored
232
233 =head1 Error: "Attribute (schema_class) does not pass the type constraint"
234
235 You probably forgot to include your project C<lib> directory in the Perl search
236 path. The easiest way to fix this is to use the C<I> or C<lib> command line:
237 option flag:
238
239 dbic-migration -Ilib -SMyApp::Schema [command]
240
de40c6b @jjn1056 updated faq
authored
241 =head1 When using the Postgresql Sandbox, I get "FATAL: could not create shared memory segment"
242
243 There will be more like this:
244
245 FATAL: could not create shared memory segment: Cannot allocate memory
246 DETAIL: Failed system call was shmget(key=1, size=2138112, 03600).
247 HINT: This error usually means that PostgreSQL's request for a shared memory
248 segment exceeded available memory or swap space, or exceeded your kernel's
249 SHMALL parameter. You can either reduce the request size or reconfigure
250 the kernel with larger SHMALL. To reduce the request size (currently 2138112
251 bytes), reduce PostgreSQL's shared memory usage, perhaps by reducing
252 shared_buffers or max_connections.
253
254 The solution is as presented. Since I prefer not to change my system settings
701cae5 small typo
Volker Kroll authored
255 permanently, just add the following to a little bash script in my application
de40c6b @jjn1056 updated faq
authored
256
257 sudo sysctl -w kern.sysv.shmall=65536
258 sudo sysctl -w kern.sysv.shmmax=16777216
259
260 I don't know enough about Postgresql to know if the above settings are good,
261 but they work for my testing. Corrections very welcome! Ideally I'd try to
1af05eb switch from Test::postgresql to Test::PostgreSQL
Samuel Kaufman authored
262 find a way to offer a patch to L<Test::PostgreSQL>, although this seems to be
de40c6b @jjn1056 updated faq
authored
263 limited to people using Macs.
264
88c6ae7 @jjn1056 a little extra docs and make sure help now works for subclasses
authored
265 =head1 How to Release
266
267 Here's the release steps I currently use, should I eventually find willing
268 comainters:
269
b80c283 @MidLifeXis Correct POD error
MidLifeXis authored
270 =over 4
88c6ae7 @jjn1056 a little extra docs and make sure help now works for subclasses
authored
271
272 =item Update Version
273
274 You need to increment the version in C<dist.ini> and in L<DBIx::Class::Migration>
275
276 =item Prepare Changes file
277
278 Update the C<Changes> file. It would be ideal to have been adding to this as
279 you've gone along, but you should double check.
280
281 =item Update Author's list
282
283 If there have been new contributors, be sure to give credit
284
285 =item Rebuild the README
286
287 pod2markdown < lib/DBIx/Class/Migration.pm > README.mkdn
288
abf13df @jjn1056 tweaked the how to release FAQ
authored
289 This will make sure the C<README.mkdn> file in the project root matches the most
88c6ae7 @jjn1056 a little extra docs and make sure help now works for subclasses
authored
290 recent updates.
291
392ff4a @jjn1056 more release docs
authored
292 =item Check your tests
293
abf13df @jjn1056 tweaked the how to release FAQ
authored
294 AUTHOR_MODE=1 prove -lvr t
392ff4a @jjn1056 more release docs
authored
295
296 =item Update the repository
297
298 git add @stuff_to_add
299 git commit -m $message
300 git push
301
302 =item Make the Distribution
303
304 dzil build
305 dzil release
306 dzil clean
307
308 =item Update the git version tag
309
310 I usually don't update and push the tag until we are on CPAN.
311
312 git tag $VERSION -m 'cpan release'
313 git push --tags
314
88c6ae7 @jjn1056 a little extra docs and make sure help now works for subclasses
authored
315 =back
316
80e1f00 @jjn1056 added a start on the FAQ
authored
317 =head1 AUTHOR
318
319 See L<DBIx::Class::Migration> for author information
320
321 =head1 COPYRIGHT & LICENSE
322
323 See L<DBIx::Class::Migration> for copyright and license information
324
325 =cut
326
327
Something went wrong with that request. Please try again.