1ORLite(3)             User Contributed Perl Documentation            ORLite(3)
2
3
4

NAME

6       ORLite - Extremely light weight SQLite-specific ORM
7

SYNOPSIS

9         package Foo;
10
11         # Simplest possible usage
12
13         use strict;
14         use ORLite 'data/sqlite.db';
15
16         my @awesome = Foo::Person->select(
17            'where first_name = ?',
18            'Adam',
19         );
20
21         package Bar;
22
23         # All available options enabled or specified.
24         # Some options shown are mutually exclusive,
25         # this code would not actually run.
26
27         use ORLite {
28             package      => 'My::ORM',
29             file         => 'data/sqlite.db',
30             user_version => 12,
31             readonly     => 1,
32             create       => sub {
33                 my $dbh = shift;
34                 $dbh->do('CREATE TABLE foo ( bar TEXT NOT NULL )');
35             },
36             tables       => [ 'table1', 'table2' ],
37             cleanup      => 'VACUUM',
38             prune        => 1,
39         };
40

DESCRIPTION

42       SQLite is a light single file SQL database that provides an excellent
43       platform for embedded storage of structured data.
44
45       However, while it is superficially similar to a regular server-side SQL
46       database, SQLite has some significant attributes that make using it
47       like a traditional database difficult.
48
49       For example, SQLite is extremely fast to connect to compared to server
50       databases (1000 connections per second is not unknown) and is
51       particularly bad at concurrency, as it can only lock transactions at a
52       database-wide level.
53
54       This role as a superfast internal data store can clash with the roles
55       and designs of traditional object-relational modules like Class::DBI or
56       DBIx::Class.
57
58       What this situation would seem to need is an object-relation system
59       that is designed specifically for SQLite and is aligned with its
60       idiosyncracies.
61
62       ORLite is an object-relation system specifically tailored for SQLite
63       that follows many of the same principles as the ::Tiny series of
64       modules and has a design and feature set that aligns directly to the
65       capabilities of SQLite.
66
67       Further documentation will be available at a later time, but the
68       synopsis gives a pretty good idea of how it works.
69
70   How ORLite Works
71       ORLite discovers the schema of a SQLite database, and then generates
72       the code for a complete set of classes that let you work with the
73       objects stored in that database.
74
75       In the simplest form, your target root package "uses" ORLite, which
76       will do the schema discovery and code generation at compile-time.
77
78       When called, ORLite generates two types of packages.
79
80       Firstly, it builds database connectivity, transaction support, and
81       other purely database level functionality into your root namespace.
82
83       Secondly, it will create one sub-package underneath the namespace of
84       the root module for each table or view it finds in the database.
85
86       Once the basic table support has been generated, it will also try to
87       load an "overlay" module of the same name. Thus, by created a
88       Foo::TableName module on disk containing "extra" code, you can extend
89       the original and add additional functionality to it.
90

OPTIONS

92       ORLite takes a set of options for the class construction at compile
93       time as a HASH parameter to the "use" line.
94
95       As a convenience, you can pass just the name of an existing SQLite file
96       to load, and ORLite will apply defaults to all other options.
97
98         # The following are equivalent
99
100         use ORLite $filename;
101
102         use ORLite {
103             file => $filename,
104         };
105
106       The behaviour of each of the options is as follows:
107
108   package
109       The optional "package" parameter is used to provide the Perl root
110       namespace to generate the code for. This class does not need to exist
111       as a module on disk, nor does it need to have anything loaded or in the
112       namespace.
113
114       By default, the package used is the package that is calling ORLite's
115       import method (typically via the "use ORLite { ... }" line).
116
117   file
118       The compulsory "file" parameter (the only compulsory parameter)
119       provides the path to the SQLite file to use for the ORM class tree.
120
121       If the file already exists, it must be a valid SQLite file match that
122       supported by the version of DBD::SQLite that is installed on your
123       system.
124
125       ORLite will throw an exception if the file does not exist, unless you
126       also provide the "create" option to signal that ORLite should create a
127       new SQLite file on demand.
128
129       If the "create" option is provided, the path provided must be
130       creatable.  When creating the database, ORLite will also create any
131       missing directories as needed.
132
133   user_version
134       When working with ORLite, the biggest risk to the stability of your
135       code is often the reliability of the SQLite schema structure over time.
136
137       When the database schema changes the code generated by ORLite will also
138       change. This can easily result in an unexpected change in the API of
139       your class tree, breaking the code that sits on top of those generated
140       APIs.
141
142       To resolve this, ORLite supports a feature called schema version-
143       locking.
144
145       Via the "user_version" SQLite pragma, you can set a revision for your
146       database schema, increasing the number each time to make a non-trivial
147       chance to your schema.
148
149         SQLite> PRAGMA user_version = 7
150
151       When creating your ORLite package, you should specificy this schema
152       version number via the "user_version" option.
153
154         use ORLite {
155             file         => $filename,
156             user_version => 7,
157         };
158
159       When connecting to the SQLite database, the "user_version" you provide
160       will be checked against the version in the schema. If the versions do
161       not match, then the schema has unexpectedly changed, and the code that
162       is generated by ORLite would be different to the expected API.
163
164       Rather than risk potentially destructive errors caused by the changing
165       code, ORLite will simply refuse to run and throw an exception.
166
167       Thus, using the "user_version" feature allows you to write code against
168       a SQLite database with high-certainty that it will continue to work. Or
169       at the very least, that should the SQLite schema change in the future
170       your code fill fail quickly and safely instead of running away and
171       causing unknown behaviour.
172
173       By default, the "user_version" option is false and the value of the
174       SQLite "PRAGMA user_version" will not be checked.
175
176   readonly
177       To conserve memory and reduce complexity, ORLite will generate the API
178       differently based on the writability of the SQLite database.
179
180       Features like transaction support and methods that result in "INSERT",
181       "UPDATE" and "DELETE" queries will only be added if they can actually
182       be run, resulting in an immediate "no such method" exception at the
183       Perl level instead of letting the application do more work only to hit
184       an inevitable SQLite error.
185
186       By default, the "readonly" option is based on the filesystem
187       permissions of the SQLite database (which matches SQLite's own
188       writability behaviour).
189
190       However the "readonly" option can be explicitly provided if you wish.
191       Generally you would do this if you are working with a read-write
192       database, but you only plan to read from it.
193
194       Forcing "readonly" to true will halve the size of the code that is
195       generated to produce your ORM, reducing the size of any auto-generated
196       API documentation using ORLite::Pod by a similar amount.
197
198       It also ensures that this process will only take shared read locks on
199       the database (preventing the chance of creating a dead-lock on the
200       SQLite database).
201
202   create
203       The "create" option is used to expand ORLite beyond just consuming
204       other people's databases to produce and operating on databases user the
205       direct control of your code.
206
207       The "create" option supports two alternative forms.
208
209       If "create" is set to a simple true value, an empty SQLite file will be
210       created if the location provided in the "file" option does not exist.
211
212       If "create" is set to a "CODE" reference, this function will be
213       executed on the new database before ORLite attempts to scan the schema.
214
215       The "CODE" reference will be passed a plain DBI connection handle,
216       which you should operate on normally. Note that because "create" is
217       fired before the code generation phase, none of the functionality
218       produced by the generated classes is available during the execution of
219       the "create" code.
220
221       The use of "create" option is incompatible with the "readonly" option.
222
223   tables
224       The "tables" option should be a reference to an array containing a list
225       of table names. For large or complex SQLite databases where you only
226       need to make use of a fraction of the schema limiting the set of tables
227       will reduce both the startup time needed to scan the structure of the
228       SQLite schema, and reduce the memory cost of the class tree.
229
230       If the "tables" option is not provided, ORLite will attempt to produce
231       a class for every table in the main schema that is not prefixed with
232       with "sqlite_".
233
234   cache
235         use ORLite {
236             file         => 'dbi:SQLite:sqlite.db',
237             user_version => 2,
238             cache        => 'cache/directory',
239         };
240
241       The "cache" option is used to reduce the time needed to scan the SQLite
242       database table structures and generate the code for them, by saving the
243       generated code to a cache directory and loading from that file instead
244       of generating it each time from scratch.
245
246   cleanup
247       When working with embedded SQLite databases containing rapidly changing
248       state data, it is important for database performance and general health
249       to make sure you VACUUM or ANALYZE the database regularly.
250
251       The "cleanup" option should be a single literal SQL statement.
252
253       If provided, this statement will be automatically run on the database
254       during "END"-time, after the last transaction has been completed.
255
256       This will typically either by a full 'VACUUM ANALYZE' or the more
257       simple 'VACUUM'.
258
259   prune
260       In some situation, such as during test scripts, an application will
261       only need the created SQLite database temporarily. In these situations,
262       the "prune" option can be provided to instruct ORLite to delete the
263       SQLite database when the program ends.
264
265       If any directories were made in order to create the SQLite file, these
266       directories will be cleaned up and removed as well.
267
268       If "prune" is enabled, you should generally not use "cleanup" as any
269       cleanup operation will be made pointless when "prune" deletes the file.
270
271       By default, the "prune" option is set to false.
272
273   shim
274       In some situtations you may wish to make extensive changes to the
275       behaviour of the classes and methods generated by ORLite. Under normal
276       circumstances all code is generated into the table class directly,
277       which can make overriding method difficult.
278
279       The "shim" option will make ORLite generate all of it's methods into a
280       seperate "Foo::TableName::Shim" class, and leave the main table class
281       "Foo::TableName" as a transparent subclass of the shim.
282
283       This allows you to alter the behaviour of a table class without having
284       to do nasty tricks with symbol tables in order to alter or replace
285       methods.
286
287         package My::Person;
288
289         # Write a log message when we create a new object
290         sub create {
291             my $class = shift;
292             my $self  = SUPER::create(@_);
293             my $name  = $self->name;
294             print LOG "Created new person '$name'\n";
295             return $self;
296         }
297
298       The "shim" option is global. It will alter the structure of all table
299       classes at once. However, unless you are making alterations to a class
300       the impact of this different class structure should be zero.
301
302   unicode
303       You can use this option to tell ORLite that your database uses unicode.
304
305       At the moment, it just enables the "sqlite_unicode" option while
306       connecting to your database. There'll be more in the future.
307

ROOT PACKAGE METHODS

309       All ORLite root packages receive an identical set of methods for
310       controlling connections to the database, transactions, and the issueing
311       of queries of various types to the database.
312
313       The example root package Foo::Bar is used in any examples.
314
315       All methods are static, ORLite does not allow the creation of a
316       Foo::Bar object (although you may wish to add this capability
317       yourself).
318
319   dsn
320         my $string = Foo::Bar->dsn;
321
322       The "dsn" accessor returns the dbi connection string used to connect to
323       the SQLite database as a string.
324
325   dbh
326         my $handle = Foo::Bar->dbh;
327
328       To reliably prevent potential SQLite deadlocks resulting from multiple
329       connections in a single process, each ORLite package will only ever
330       maintain a single connection to the database.
331
332       During a transaction, this will be the same (cached) database handle.
333
334       Although in most situations you should not need a direct DBI connection
335       handle, the "dbh" method provides a method for getting a direct
336       connection in a way that is compatible with ORLite's connection
337       management.
338
339       Please note that these connections should be short-lived, you should
340       never hold onto a connection beyond the immediate scope.
341
342       The transaction system in ORLite is specifically designed so that code
343       using the database should never have to know whether or not it is in a
344       transation.
345
346       Because of this, you should never call the ->disconnect method on the
347       database handles yourself, as the handle may be that of a currently
348       running transaction.
349
350       Further, you should do your own transaction management on a handle
351       provided by the <dbh> method.
352
353       In cases where there are extreme needs, and you absolutely have to
354       violate these connection handling rules, you should create your own
355       completely manual DBI->connect call to the database, using the connect
356       string provided by the "dsn" method.
357
358       The "dbh" method returns a DBI::db object, or throws an exception on
359       error.
360
361   connect
362         my $dbh = Foo::Bar->connect;
363
364       The "connect" method is provided for the (extremely rare) situation in
365       which you need a raw connection to the database, evading the normal
366       tracking and management provided of the ORM.
367
368       The use of raw connections in this manner is strongly discouraged, as
369       you can create fatal deadlocks in SQLite if either the core ORM or the
370       raw connection uses a transaction at any time.
371
372       To summarise, do not use this method unless you REALLY know what you
373       are doing.
374
375       YOU HAVE BEEN WARNED!
376
377   connected
378         my $active = Foo::Bar->connected;
379
380       The "connected" method provides introspection of the connection status
381       of the library. It returns true if there is any connection or
382       transaction open to the database, or false otherwise.
383
384   begin
385         Foo::Bar->begin;
386
387       The "begin" method indicates the start of a transaction.
388
389       In the same way that ORLite allows only a single connection, likewise
390       it allows only a single application-wide transaction.
391
392       No indication is given as to whether you are currently in a transaction
393       or not, all code should be written neutrally so that it works either
394       way or doesn't need to care.
395
396       Returns true or throws an exception on error.
397
398       While transaction support is always built for every ORLite-generated
399       class tree, if the database is opened "readonly" the "commit" method
400       will not exist at all in the API, and your only way of ending the
401       transaction (and the resulting persistent connection) will be
402       "rollback".
403
404   commit
405         Foo::Bar->commit;
406
407       The "commit" method commits the current transaction. If called outside
408       of a current transaction, it is accepted and treated as a null
409       operation.
410
411       Once the commit has been completed, the database connection falls back
412       into auto-commit state. If you wish to immediately start another
413       transaction, you will need to issue a separate ->begin call.
414
415       Returns true or throws an exception on error.
416
417   commit_begin
418         Foo::Bar->begin;
419
420         # Code for the first transaction...
421
422         Foo::Bar->commit_begin;
423
424         # Code for the last transaction...
425
426         Foo::Bar->commit;
427
428       By default, ORLite-generated code uses opportunistic connections.
429
430       Every <select> you call results in a fresh DBI "connect", and a
431       "disconnect" occurs after query processing and before the data is
432       returned. Connections are only held open indefinitely during a
433       transaction, with an immediate "disconnect" after your "commit".
434
435       This makes ORLite very easy to use in an ad-hoc manner, but can have
436       performance implications.
437
438       While SQLite itself can handle 1000 connections per second, the
439       repeated destruction and repopulation of SQLite's data page caches
440       between your statements (or between transactions) can slow things down
441       dramatically.
442
443       The "commit_begin" method is used to "commit" the current transaction
444       and immediately start a new transaction, without disconnecting from the
445       database.
446
447       Its exception behaviour and return value is identical to that of a
448       plain "commit" call.
449
450   rollback
451       The "rollback" method rolls back the current transaction. If called
452       outside of a current transaction, it is accepted and treated as a null
453       operation.
454
455       Once the rollback has been completed, the database connection falls
456       back into auto-commit state. If you wish to immediately start another
457       transaction, you will need to issue a separate ->begin call.
458
459       If a transaction exists at END-time as the process exits, it will be
460       automatically rolled back.
461
462       Returns true or throws an exception on error.
463
464   rollback_begin
465         Foo::Bar->begin;
466
467         # Code for the first transaction...
468
469         Foo::Bar->rollback_begin;
470
471         # Code for the last transaction...
472
473         Foo::Bar->commit;
474
475       By default, ORLite-generated code uses opportunistic connections.
476
477       Every <select> you call results in a fresh DBI "connect", and a
478       "disconnect" occurs after query processing and before the data is
479       returned. Connections are only held open indefinitely during a
480       transaction, with an immediate "disconnect" after your "commit".
481
482       This makes ORLite very easy to use in an ad-hoc manner, but can have
483       performance implications.
484
485       While SQLite itself can handle 1000 connections per second, the
486       repeated destruction and repopulation of SQLite's data page caches
487       between your statements (or between transactions) can slow things down
488       dramatically.
489
490       The "rollback_begin" method is used to "rollback" the current
491       transaction and immediately start a new transaction, without
492       disconnecting from the database.
493
494       Its exception behaviour and return value is identical to that of a
495       plain "commit" call.
496
497   do
498         Foo::Bar->do(
499             'insert into table (foo, bar) values (?, ?)',
500             {},
501             $foo_value,
502             $bar_value,
503         );
504
505       The "do" method is a direct wrapper around the equivalent DBI method,
506       but applied to the appropriate locally-provided connection or
507       transaction.
508
509       It takes the same parameters and has the same return values and error
510       behaviour.
511
512   selectall_arrayref
513       The "selectall_arrayref" method is a direct wrapper around the
514       equivalent DBI method, but applied to the appropriate locally-provided
515       connection or transaction.
516
517       It takes the same parameters and has the same return values and error
518       behaviour.
519
520   selectall_hashref
521       The "selectall_hashref" method is a direct wrapper around the
522       equivalent DBI method, but applied to the appropriate locally-provided
523       connection or transaction.
524
525       It takes the same parameters and has the same return values and error
526       behaviour.
527
528   selectcol_arrayref
529       The "selectcol_arrayref" method is a direct wrapper around the
530       equivalent DBI method, but applied to the appropriate locally-provided
531       connection or transaction.
532
533       It takes the same parameters and has the same return values and error
534       behaviour.
535
536   selectrow_array
537       The "selectrow_array" method is a direct wrapper around the equivalent
538       DBI method, but applied to the appropriate locally-provided connection
539       or transaction.
540
541       It takes the same parameters and has the same return values and error
542       behaviour.
543
544   selectrow_arrayref
545       The "selectrow_arrayref" method is a direct wrapper around the
546       equivalent DBI method, but applied to the appropriate locally-provided
547       connection or transaction.
548
549       It takes the same parameters and has the same return values and error
550       behaviour.
551
552   selectrow_hashref
553       The "selectrow_hashref" method is a direct wrapper around the
554       equivalent DBI method, but applied to the appropriate locally-provided
555       connection or transaction.
556
557       It takes the same parameters and has the same return values and error
558       behaviour.
559
560   prepare
561       The "prepare" method is a direct wrapper around the equivalent DBI
562       method, but applied to the appropriate locally-provided connection or
563       transaction
564
565       It takes the same parameters and has the same return values and error
566       behaviour.
567
568       In general though, you should try to avoid the use of your own prepared
569       statements if possible, although this is only a recommendation and by
570       no means prohibited.
571
572   pragma
573         # Get the user_version for the schema
574         my $version = Foo::Bar->pragma('user_version');
575
576       The "pragma" method provides a convenient method for fetching a pragma
577       for a datase. See the SQLite documentation for more details.
578

TABLE PACKAGE METHODS

580       When you use ORLite, your database tables will be available as objects
581       named in a camel-cased fashion. So, if your model name is Foo::Bar...
582
583         use ORLite {
584             package => 'Foo::Bar',
585             file    => 'data/sqlite.db',
586         };
587
588       ... then a table named 'user' would be accessed as "Foo::Bar::User",
589       while a table named 'user_data' would become "Foo::Bar::UserData".
590
591   base
592         my $namespace = Foo::Bar::User->base; # Returns 'Foo::Bar'
593
594       Normally you will only need to work directly with a table class, and
595       only with one ORLite package.
596
597       However, if for some reason you need to work with multiple ORLite
598       packages at the same time without hardcoding the root namespace all the
599       time, you can determine the root namespace from an object or table
600       class with the "base" method.
601
602   table
603         print Foo::Bar::UserData->table; # 'user_data'
604
605       While you should not need the name of table for any simple operations,
606       from time to time you may need it programatically. If you do need it,
607       you can use the "table" method to get the table name.
608
609   table_info
610         # List the columns in the underlying table
611         my $columns = Foo::Bar::User->table_info;
612         foreach my $c ( @$columns ) {
613            print "Column $c->{name} $c->{type}";
614            print " not null" if $c->{notnull};
615            print " default $c->{dflt_value}" if defined $c->{dflt_value};
616            print " primary key" if $c->{pk};
617            print "\n";
618         }
619
620       The "table_info" method is a wrapper around the SQLite "table_info"
621       pragma, and provides simplified access to the column metadata for the
622       underlying table should you need it for some advanced function that
623       needs direct access to the column list.
624
625       Returns a reference to an "ARRAY" containing a list of columns, where
626       each column is a reference to a "HASH" with the keys "cid",
627       "dflt_value", "name", "notnull", "pk" and "type".
628
629   new
630         my $user = Foo::Bar::User->new(
631             name => 'Your Name',
632             age  => 23,
633         );
634
635       The "new" constructor creates an anonymous object, without reading or
636       writing it to the database. It also won't do validation of any kind,
637       since ORLite is designed for use with embedded databases and presumes
638       that you know what you are doing.
639
640   insert
641         my $user = Foo::Bar::User->new(
642             name => 'Your Name',
643             age  => 23,
644         )->insert;
645
646       The "insert" method takes an existing anonymous object and inserts it
647       into the database, returning the object back as a convenience.
648
649       It provides the second half of the slower manual two-phase object
650       construction process.
651
652       If the table has an auto-incrementing primary key (and you have not
653       provided a value for it yourself) the identifier for the new record
654       will be fetched back from the database and set in your object.
655
656         my $object = Foo::Bar::User->new( name => 'Foo' )->insert;
657
658         print "Created new user with id " . $user->id . "\n";
659
660   create
661         my $user = Foo::Bar::User->create(
662             name => 'Your Name',
663             age  => 23,
664         );
665
666       While the "new" + "insert" methods are useful when you need to do
667       interesting constructor mechanisms, for most situations you already
668       have all the attributes ready and just want to create and insert the
669       record in a single step.
670
671       The "create" method provides this shorthand mechanism and is just the
672       functional equivalent of the following.
673
674         sub create {
675             shift->new(@_)->insert;
676         }
677
678       It returns the newly created object after it has been inserted.
679
680   load
681         my $user = Foo::Bar::User->load( $id );
682
683       If your table has single column primary key, a "load" method will be
684       generated in the class. If there is no primary key, the method is not
685       created.
686
687       The "load" method provides a shortcut mechanism for fetching a single
688       object based on the value of the primary key. However it should only be
689       used for cases where your code trusts the record to already exists.
690
691       It returns a "Foo::Bar::User" object, or throws an exception if the
692       object does not exist.
693
694   id
695       The "id" accessor is a convenience method that is added to your table
696       class to increase the readability of your code when ORLite detects
697       certain patterns of column naming.
698
699       For example, take the following definition where convention is that all
700       primary keys are the table name followed by "_id".
701
702         create table foo_bar (
703             foo_bar_id integer not null primary key,
704             name string not null,
705         )
706
707       When ORLite detects the use of this pattern, and as long as the table
708       does not have an "id" column, the additional "id" accessor will be
709       added to your class, making these expressions equivalent both in
710       function and performance.
711
712         my $foo_bar = My::FooBar->create( name => 'Hello' );
713
714         # Column name accessor
715         $foo_bar->foo_bar_id;
716
717         # Convenience id accessor
718         $foo_bar->id;
719
720       As you can see, the latter involves much less repetition and reads much
721       more cleanly.
722
723   select
724         my @users = Foo::Bar::User->select;
725
726         my $users = Foo::Bar::User->select( 'where name = ?', @args );
727
728       The "select" method is used to retrieve objects from the database.
729
730       In list context, returns an array with all matching elements.  In
731       scalar context an array reference is returned with that same data.
732
733       You can filter the results or order them by passing SQL code to the
734       method.
735
736           my @users = DB::User->select( 'where name = ?', $name );
737
738           my $users = DB::User->select( 'order by name' );
739
740       Because "select" provides only the thinnest of layers around pure SQL
741       (it merely generates the "SELECT ... FROM table_name") you are free to
742       use anything you wish in your query, including subselects and function
743       calls.
744
745       If called without any arguments, it will return all rows of the table
746       in the natural sort order of SQLite.
747
748   iterate
749         Foo::Bar::User->iterate( sub {
750             print $_->name . "\n";
751         } );
752
753       The "iterate" method enables the processing of large tables one record
754       at a time without loading having to them all into memory in advance.
755
756       This plays well to the strength of SQLite, allowing it to do the work
757       of loading arbitrarily large stream of records from disk while
758       retaining the full power of Perl when processing the records.
759
760       The last argument to "iterate" must be a subroutine reference that will
761       be called for each element in the list, with the object provided in the
762       topic variable $_.
763
764       This makes the "iterate" code fragment above functionally equivalent to
765       the following, except with an O(1) memory cost instead of O(n).
766
767           foreach ( Foo::Bar::User->select ) {
768               print $_->name . "\n";
769           }
770
771       You can filter the list via SQL in the same way you can with "select".
772
773         Foo::Bar::User->iterate(
774             'order by ?', 'name',
775             sub {
776                 print $_->name . "\n";
777             }
778         );
779
780       You can also use it in raw form from the root namespace for better
781       control.  Using this form also allows for the use of arbitrarily
782       complex queries, including joins. Instead of being objects, rows are
783       provided as ARRAY references when used in this form.
784
785         Foo::Bar->iterate(
786             'select name from user order by name',
787             sub {
788                 print $_->[0] . "\n";
789             }
790         );
791
792   count
793         my $everyone = Foo::Bar::User->count;
794
795         my $young = Foo::Bar::User->count( 'where age <= ?', 13 );
796
797       You can count the total number of elements in a table by calling the
798       "count" method with no arguments. You can also narrow your count by
799       passing sql conditions to the method in the same manner as with the
800       "select" method.
801
802   delete
803         # Delete a single object from the database
804         $user->delete;
805
806         # Delete a range of rows from the database
807         Foo::Bar::User->delete( 'where age <= ?', 13 );
808
809       The "delete" method will delete the single row representing an object,
810       based on the primary key or SQLite rowid of that object.
811
812       The object that you delete will be left intact and untouched, and you
813       remain free to do with it whatever you wish.
814
815   delete_where
816         # Delete a range of rows from the database
817         Foo::Bar::User->delete( 'age <= ?', 13 );
818
819       The "delete_where" static method allows the delete of large numbers of
820       rows from a database while protecting against accidentally doing a
821       boundless delete (the "truncate" method is provided specifically for
822       this purpose).
823
824       It takes the same parameters for deleting as the "select" method, with
825       the exception that the "where" keyword is automatically provided for
826       your and should not be passed in.
827
828       This ensures that providing an empty of null condition results in an
829       invalid SQL query and the deletion will not occur.
830
831       Returns the number of rows deleted from the database (which may be
832       zero).
833
834   truncate
835         # Clear out all records from the table
836         Foo::Bar::User->truncate;
837
838       The "truncate" method takes no parameters and is used for only one
839       purpose, to completely empty a table of all rows.
840
841       Having a separate method from "delete" not only prevents accidents, but
842       will also do the deletion via the direct SQLite "TRUNCATE TABLE" query.
843       This uses a different deletion mechanism, and is significantly faster
844       than a plain SQL "DELETE".
845

TO DO

847       - Support for intuiting reverse relations from foreign keys
848
849       - Document the 'create' and 'table' params
850

SUPPORT

852       Bugs should be reported via the CPAN bug tracker at
853
854       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ORLite>
855
856       For other issues, contact the author.
857

AUTHOR

859       Adam Kennedy <adamk@cpan.org>
860

SEE ALSO

862       ORLite::Mirror, ORLite::Migrate, ORLite::Pod
863
865       Copyright 2008 - 2012 Adam Kennedy.
866
867       This program is free software; you can redistribute it and/or modify it
868       under the same terms as Perl itself.
869
870       The full text of the license can be found in the LICENSE file included
871       with this module.
872
873
874
875perl v5.34.0                      2022-01-21                         ORLite(3)
Impressum