Codebase list liborlite-perl / debian/1.33-1
debian/1.33-1

Tree @debian/1.33-1 (Download .tar.gz)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
NAME
    ORLite - Extremely light weight SQLite-specific ORM

SYNOPSIS
      package Foo;
      
  # Simplest possible usage
      
  use strict;
      use ORLite 'data/sqlite.db';
      
  my @awesome = Foo::Person->select(
         'where first_name = ?',
         'Adam',
      );
      
  package Bar;
      
  # All available options enabled or specified.
      # Some options shown are mutually exclusive,
      # this code would not actually run.
      
  use ORLite {
          package      => 'My::ORM',
          file         => 'data/sqlite.db',
          user_version => 12,
          readonly     => 1,
          create       => sub {
              my $dbh = shift;
              $dbh->do('CREATE TABLE foo ( bar TEXT NOT NULL )');
          },
          tables       => [ 'table1', 'table2' ],
          cleanup      => 'VACUUM',
          prune        => 1,
      );

DESCRIPTION
    SQLite is a light single file SQL database that provides an excellent
    platform for embedded storage of structured data.

    However, while it is superficially similar to a regular server-side SQL
    database, SQLite has some significant attributes that make using it like
    a traditional database difficult.

    For example, SQLite is extremely fast to connect to compared to server
    databases (1000 connections per second is not unknown) and is
    particularly bad at concurrency, as it can only lock transactions at a
    database-wide level.

    This role as a superfast internal data store can clash with the roles
    and designs of traditional object-relational modules like Class::DBI or
    DBIx::Class.

    What this situation would seem to need is an object-relation system that
    is designed specifically for SQLite and is aligned with its
    idiosyncracies.

    ORLite is an object-relation system specifically tailored for SQLite
    that follows many of the same principles as the ::Tiny series of modules
    and has a design and feature set that aligns directly to the
    capabilities of SQLite.

    Further documentation will be available at a later time, but the
    synopsis gives a pretty good idea of how it works.

  How ORLite Works
    In short, ORLite discovers the schema of a SQLite database, and then
    uses code generation to build a set of packages for talking to that
    database.

    In the simplest form, your target root package "uses" ORLite, which will
    do the schema discovery and code generation at compile-time.

    When called, ORLite generates two types of package.

    Firstly, it builds database connectivity, transaction support, and other
    purely database level functionality into your root namespace.

    Then it will create one sub-package underneath the root package for each
    table contained in the database.

OPTIONS
    ORLite takes a set of options for the class construction at compile time
    as a HASH parameter to the "use" line.

    As a convenience, you can pass just the name of an existing SQLite file
    to load, and ORLite will apply defaults to all other options.

      # The following are equivalent
      
  use ORLite $filename;
      
  use ORLite {
          file => $filename,
      };

    The behaviour of each of the options is as follows:

  package
    The optional "package" parameter is used to provide the Perl root
    namespace to generate the code for. This class does not need to exist as
    a module on disk, nor does it need to have anything loaded or in the
    namespace.

    By default, the package used is the package that is calling ORLite's
    import method (typically via the "use ORLite { ... }" line).

  file
    The compulsory "file" parameter (the only compulsory parameter) provides
    the path to the SQLite file to use for the ORM class tree.

    If the file already exists, it must be a valid SQLite file match that
    supported by the version of DBD::SQLite that is installed on your
    system.

    ORLite will throw an exception if the file does not exist, unless you
    also provide the "create" option to signal that ORLite should create a
    new SQLite file on demand.

    If the "create" option is provided, the path provided must be creatable.
    When creating the database, ORLite will also create any missing
    directories as needed.

  user_version
    When working with ORLite, the biggest risk to the stability of your code
    is often the reliability of the SQLite schema structure over time.

    When the database schema changes the code generated by ORLite will also
    change. This can easily result in an unexpected change in the API of
    your class tree, breaking the code that sits on top of those generated
    APIs.

    To resolve this, ORLite supports a feature called schema
    version-locking.

    Via the "user_version" SQLite pragma, you can set a revision for your
    database schema, increasing the number each time to make a non-trivial
    chance to your schema.

      SQLite> PRAGMA user_version = 7

    When creating your ORLite package, you should specificy this schema
    version number via the "user_version" option.

      use ORLite {
          file         => $filename,
          user_version => 7,
      };

    When connecting to the SQLite database, the "user_version" you provide
    will be checked against the version in the schema. If the versions do
    not match, then the schema has unexpectedly changed, and the code that
    is generated by ORLite would be different to the expected API.

    Rather than risk potentially destructive errors caused by the changing
    code, ORLite will simply refuse to run and throw an exception.

    Thus, using the "user_version" feature allows you to write code against
    a SQLite database with high-certainty that it will continue to work. Or
    at the very least, that should the SQLite schema change in the future
    your code fill fail quickly and safely instead of running away and
    causing unknown behaviour.

    By default, the "user_version" option is false and the value of the
    SQLite "PRAGMA user_version" will not be checked.

  readonly
    To conserve memory and reduce complexity, ORLite will generate the API
    differently based on the writability of the SQLite database.

    Features like transaction support and methods that result in "INSERT",
    "UPDATE" and "DELETE" queries will only be added if they can actually be
    run, resulting in an immediate "no such method" exception at the Perl
    level instead of letting the application do more work only to hit an
    inevitable SQLite error.

    By default, the "reaodnly" option is based on the filesystem permissions
    of the SQLite database (which matches SQLite's own writability
    behaviour).

    However the "readonly" option can be explicitly provided if you wish.
    Generally you would do this if you are working with a read-write
    database, but you only plan to read from it.

    Forcing "readonly" to true will halve the size of the code that is
    generated to produce your ORM, reducing the size of any auto-generated
    API documentation using ORLite::Pod by a similar amount.

    It also ensures that this process will only take shared read locks on
    the database (preventing the chance of creating a dead-lock on the
    SQLite database).

  create
    The "create" option is used to expand ORLite beyond just consuming other
    people's databases to produce and operating on databases user the direct
    control of your code.

    The "create" option supports two alternative forms.

    If "create" is set to a simple true value, an empty SQLite file will be
    created if the location provided in the "file" option does not exist.

    If "create" is set to a "CODE" reference, this function will be executed
    on the new database before ORLite attempts to scan the schema.

    The "CODE" reference will be passed a plain DBI connection handle, which
    you should operate on normally. Note that because "create" is fired
    before the code generation phase, none of the functionality produced by
    the generated classes is available during the execution of the "create"
    code.

    The use of "create" option is incompatible with the "readonly" option.

  tables
    The "tables" option should be a reference to an array containing a list
    of table names. For large or complex SQLite databases where you only
    need to make use of a fraction of the schema limiting the set of tables
    will reduce both the startup time needed to scan the structure of the
    SQLite schema, and reduce the memory cost of the class tree.

    If the "tables" option is not provided, ORLite will attempt to produce a
    class for every table in the main schema that is not prefixed with with
    "sqlite_".

  cleanup
    When working with embedded SQLite database containing rapidly changing
    state data, it is important for database performance and general health
    to make sure you VACUUM or ANALYZE the database regularly.

    The "cleanup" option should be a single literal SQL statement.

    If provided, this statement will be automatically run on the database
    during "END"-time, after the last transaction has been completed.

    This will typically either by a full 'VACUUM ANALYZE' or the more simple
    'VACUUM'.

  prune
    In some situation, such as during test scripts, an application will only
    need the created SQLite database temporarily. In these situations, the
    "prune" option can be provided to instruct ORLite to delete the SQLite
    database when the program ends.

    If any directories were made in order to create the SQLite file, these
    directories will be cleaned up and removed as well.

    If "prune" is enabled, you should generally not use "cleanup" as any
    cleanup operation will be made pointless when "prune" deletes the file.

    By default, the "prune" option is set to false.

ROOT PACKAGE METHODS
    All ORLite root packages receive an identical set of methods for
    controlling connections to the database, transactions, and the issueing
    of queries of various types to the database.

    The example root package Foo::Bar is used in any examples.

    All methods are static, ORLite does not allow the creation of a Foo::Bar
    object (although you may wish to add this capability yourself).

  dsn
      my $string = Foo::Bar->dsn;

    The "dsn" accessor returns the dbi connection string used to connect to
    the SQLite database as a string.

  dbh
      my $handle = Foo::Bar->dbh;

    To reliably prevent potential SQLite deadlocks resulting from multiple
    connections in a single process, each ORLite package will only ever
    maintain a single connection to the database.

    During a transaction, this will be the same (cached) database handle.

    Although in most situations you should not need a direct DBI connection
    handle, the "dbh" method provides a method for getting a direct
    connection in a way that is compatible with ORLite's connection
    management.

    Please note that these connections should be short-lived, you should
    never hold onto a connection beyond the immediate scope.

    The transaction system in ORLite is specifically designed so that code
    using the database should never have to know whether or not it is in a
    transation.

    Because of this, you should never call the ->disconnect method on the
    database handles yourself, as the handle may be that of a currently
    running transaction.

    Further, you should do your own transaction management on a handle
    provided by the <dbh> method.

    In cases where there are extreme needs, and you absolutely have to
    violate these connection handling rules, you should create your own
    completely manual DBI->connect call to the database, using the connect
    string provided by the "dsn" method.

    The "dbh" method returns a DBI::db object, or throws an exception on
    error.

  begin
      Foo::Bar->begin;

    The "begin" method indicates the start of a transaction.

    In the same way that ORLite allows only a single connection, likewise it
    allows only a single application-wide transaction.

    No indication is given as to whether you are currently in a transaction
    or not, all code should be written neutrally so that it works either way
    or doesn't need to care.

    Returns true or throws an exception on error.

    While transaction support is always built for every ORLite-generated
    class tree, if the database is opened "readonly" the "commit" method
    will not exist at all in the API, and your only way of ending the
    transaction (and the resulting persistant connection) will be
    "rollback".

  commit
      Foo::Bar->commit;

    The "commit" method commits the current transaction. If called outside
    of a current transaction, it is accepted and treated as a null
    operation.

    Once the commit has been completed, the database connection falls back
    into auto-commit state. If you wish to immediately start another
    transaction, you will need to issue a separate ->begin call.

    Returns true or throws an exception on error.

  commit_begin
      Foo::Bar->begin;
      
  # Code for the first transaction...
      
  Foo::Bar->commit_begin;
      
  # Code for the last transaction...
      
  Foo::Bar->commit;

    By default, ORLite-generated code uses opportunistic connections.

    Every <select> you call results in a fresh DBI "connect", and a
    "disconnect" occurs after query processing and before the data is
    returned. Connections are only held open indefinitely during a
    transaction, with an immediate "disconnect" after your "commit".

    This makes ORLite very easy to use in an ad-hoc manner, but can have
    performance implications.

    While SQLite itself can handle 1000 connections per second, the repeated
    destruction and repopulation of SQLite's data page caches between your
    statements (or between transactions) can slow things down dramatically.

    The "commit_begin" method is used to "commit" the current transaction
    and immediately start a new transaction, without disconnecting from the
    database.

    Its exception behaviour and return value is identical to that of a plain
    "commit" call.

  rollback
    The "rollback" method rolls back the current transaction. If called
    outside of a current transaction, it is accepted and treated as a null
    operation.

    Once the rollback has been completed, the database connection falls back
    into auto-commit state. If you wish to immediately start another
    transaction, you will need to issue a separate ->begin call.

    If a transaction exists at END-time as the process exits, it will be
    automatically rolled back.

    Returns true or throws an exception on error.

  rollback_begin
      Foo::Bar->begin;
      
  # Code for the first transaction...
      
  Foo::Bar->rollback_begin;
      
  # Code for the last transaction...
      
  Foo::Bar->commit;

    By default, ORLite-generated code uses opportunistic connections.

    Every <select> you call results in a fresh DBI "connect", and a
    "disconnect" occurs after query processing and before the data is
    returned. Connections are only held open indefinitely during a
    transaction, with an immediate "disconnect" after your "commit".

    This makes ORLite very easy to use in an ad-hoc manner, but can have
    performance implications.

    While SQLite itself can handle 1000 connections per second, the repeated
    destruction and repopulation of SQLite's data page caches between your
    statements (or between transactions) can slow things down dramatically.

    The "rollback_begin" method is used to "rollback" the current
    transaction and immediately start a new transaction, without
    disconnecting from the database.

    Its exception behaviour and return value is identical to that of a plain
    "commit" call.

  do
      Foo::Bar->do('insert into table (foo, bar) values (?, ?)', {},
          $foo_value,
          $bar_value,
      );

    The "do" method is a direct wrapper around the equivalent DBI method,
    but applied to the appropriate locally-provided connection or
    transaction.

    It takes the same parameters and has the same return values and error
    behaviour.

  selectall_arrayref
    The "selectall_arrayref" method is a direct wrapper around the
    equivalent DBI method, but applied to the appropriate locally-provided
    connection or transaction.

    It takes the same parameters and has the same return values and error
    behaviour.

  selectall_hashref
    The "selectall_hashref" method is a direct wrapper around the equivalent
    DBI method, but applied to the appropriate locally-provided connection
    or transaction.

    It takes the same parameters and has the same return values and error
    behaviour.

  selectcol_arrayref
    The "selectcol_arrayref" method is a direct wrapper around the
    equivalent DBI method, but applied to the appropriate locally-provided
    connection or transaction.

    It takes the same parameters and has the same return values and error
    behaviour.

  selectrow_array
    The "selectrow_array" method is a direct wrapper around the equivalent
    DBI method, but applied to the appropriate locally-provided connection
    or transaction.

    It takes the same parameters and has the same return values and error
    behaviour.

  selectrow_arrayref
    The "selectrow_arrayref" method is a direct wrapper around the
    equivalent DBI method, but applied to the appropriate locally-provided
    connection or transaction.

    It takes the same parameters and has the same return values and error
    behaviour.

  selectrow_hashref
    The "selectrow_hashref" method is a direct wrapper around the equivalent
    DBI method, but applied to the appropriate locally-provided connection
    or transaction.

    It takes the same parameters and has the same return values and error
    behaviour.

  prepare
    The "prepare" method is a direct wrapper around the equivalent DBI
    method, but applied to the appropriate locally-provided connection or
    transaction

    It takes the same parameters and has the same return values and error
    behaviour.

    In general though, you should try to avoid the use of your own prepared
    statements if possible, although this is only a recommendation and by no
    means prohibited.

  pragma
      # Get the user_version for the schema
      my $version = Foo::Bar->pragma('user_version');

    The "pragma" method provides a convenient method for fetching a pragma
    for a datase. See the SQLite documentation for more details.

TABLE PACKAGE METHODS
    The example root package Foo::Bar::TableName is used in any examples.

    TO BE COMPLETED

TO DO
    - Support for intuiting reverse relations from foreign keys

    - Document the 'create' and 'table' params

SUPPORT
    Bugs should be reported via the CPAN bug tracker at

    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ORLite>

    For other issues, contact the author.

AUTHOR
    Adam Kennedy <adamk@cpan.org>

SEE ALSO
    ORLite::Mirror, ORLite::Migrate

COPYRIGHT
    Copyright 2008 - 2010 Adam Kennedy.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    The full text of the license can be found in the LICENSE file included
    with this module.

Commit History @debian/1.33-1