{ "content": [ { "type": "text", "text": "# Class::DBI (perldoc)\n\n## NAME\n\nClass::DBI - Simple Database Abstraction\n\n## SYNOPSIS\n\npackage Music::DBI;\nuse base 'Class::DBI';\nMusic::DBI->connection('dbi:mysql:dbname', 'username', 'password');\npackage Music::Artist;\nuse base 'Music::DBI';\nMusic::Artist->table('artist');\nMusic::Artist->columns(All => qw/artistid name/);\nMusic::Artist->hasmany(cds => 'Music::CD');\npackage Music::CD;\nuse base 'Music::DBI';\nMusic::CD->table('cd');\nMusic::CD->columns(All => qw/cdid artist title year reldate/);\nMusic::CD->hasmany(tracks => 'Music::Track');\nMusic::CD->hasa(artist => 'Music::Artist');\nMusic::CD->hasa(reldate => 'Time::Piece',\ninflate => sub { Time::Piece->strptime(shift, \"%Y-%m-%d\") },\ndeflate => 'ymd',\n);\nMusic::CD->mighthave(linernotes => LinerNotes => qw/notes/);\npackage Music::Track;\nuse base 'Music::DBI';\nMusic::Track->table('track');\nMusic::Track->columns(All => qw/trackid cd position title/);\n#-- Meanwhile, in a nearby piece of code! --#\nmy $artist = Music::Artist->insert({ artistid => 1, name => 'U2' });\nmy $cd = $artist->addtocds({\ncdid => 1,\ntitle => 'October',\nyear => 1980,\n});\n# Oops, got it wrong.\n$cd->year(1981);\n$cd->update;\n# etc.\nforeach my $track ($cd->tracks) {\nprint $track->position, $track->title\n}\n$cd->delete; # also deletes the tracks\nmy $cd = Music::CD->retrieve(1);\nmy @cds = Music::CD->retrieveall;\nmy @cds = Music::CD->search(year => 1980);\nmy @cds = Music::CD->searchlike(title => 'October%');\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **INTRODUCTION** (1 subsections)\n- **CLASS METHODS** (2 subsections)\n- **RETRIEVING OBJECTS**\n- **ITERATORS** (1 subsections)\n- **COPY AND MOVE** (2 subsections)\n- **TRIGGERS**\n- **CONSTRAINTS**\n- **DATA NORMALIZATION** (1 subsections)\n- **DATA VALIDATION** (1 subsections)\n- **EXCEPTIONS**\n- **WARNINGS**\n- **INSTANCE METHODS**\n- **Changing Your Column Accessor Method Names** (1 subsections)\n- **TABLE RELATIONSHIPS** (4 subsections)\n- **MANY TO MANY RELATIONSHIPS**\n- **ADDING NEW RELATIONSHIP TYPES**\n- **DEFINING SQL STATEMENTS** (4 subsections)\n- **LAZY POPULATION** (1 subsections)\n- **TRANSACTIONS** (1 subsections)\n- **UNIQUENESS OF OBJECTS IN MEMORY**\n- **SUBCLASSING**\n- **CAVEATS** (2 subsections)\n- **SUPPORTED DATABASES**\n- **CURRENT AUTHOR**\n- **AUTHOR EMERITUS**\n- **THANKS TO**\n- **RELEASE PHILOSOPHY** (4 subsections)\n- **SUPPORT**\n- **LICENSE**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Class::DBI", "section": "", "mode": "perldoc", "summary": "Class::DBI - Simple Database Abstraction", "synopsis": "package Music::DBI;\nuse base 'Class::DBI';\nMusic::DBI->connection('dbi:mysql:dbname', 'username', 'password');\npackage Music::Artist;\nuse base 'Music::DBI';\nMusic::Artist->table('artist');\nMusic::Artist->columns(All => qw/artistid name/);\nMusic::Artist->hasmany(cds => 'Music::CD');\npackage Music::CD;\nuse base 'Music::DBI';\nMusic::CD->table('cd');\nMusic::CD->columns(All => qw/cdid artist title year reldate/);\nMusic::CD->hasmany(tracks => 'Music::Track');\nMusic::CD->hasa(artist => 'Music::Artist');\nMusic::CD->hasa(reldate => 'Time::Piece',\ninflate => sub { Time::Piece->strptime(shift, \"%Y-%m-%d\") },\ndeflate => 'ymd',\n);\nMusic::CD->mighthave(linernotes => LinerNotes => qw/notes/);\npackage Music::Track;\nuse base 'Music::DBI';\nMusic::Track->table('track');\nMusic::Track->columns(All => qw/trackid cd position title/);\n#-- Meanwhile, in a nearby piece of code! --#\nmy $artist = Music::Artist->insert({ artistid => 1, name => 'U2' });\nmy $cd = $artist->addtocds({\ncdid => 1,\ntitle => 'October',\nyear => 1980,\n});\n# Oops, got it wrong.\n$cd->year(1981);\n$cd->update;\n# etc.\nforeach my $track ($cd->tracks) {\nprint $track->position, $track->title\n}\n$cd->delete; # also deletes the tracks\nmy $cd = Music::CD->retrieve(1);\nmy @cds = Music::CD->retrieveall;\nmy @cds = Music::CD->search(year => 1980);\nmy @cds = Music::CD->searchlike(title => 'October%');", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 55, "subsections": [] }, { "name": "INTRODUCTION", "lines": 13, "subsections": [ { "name": "How to set it up", "lines": 70 } ] }, { "name": "CLASS METHODS", "lines": 19, "subsections": [ { "name": "connection", "lines": 104 }, { "name": "insert", "lines": 42 } ] }, { "name": "RETRIEVING OBJECTS", "lines": 53, "subsections": [] }, { "name": "ITERATORS", "lines": 18, "subsections": [ { "name": "Subclassing the Iterator", "lines": 21 } ] }, { "name": "COPY AND MOVE", "lines": 14, "subsections": [ { "name": "insert", "lines": 13 }, { "name": "copy", "lines": 2 } ] }, { "name": "TRIGGERS", "lines": 29, "subsections": [] }, { "name": "CONSTRAINTS", "lines": 66, "subsections": [] }, { "name": "DATA NORMALIZATION", "lines": 1, "subsections": [ { "name": "normalize_column_values", "lines": 10 } ] }, { "name": "DATA VALIDATION", "lines": 1, "subsections": [ { "name": "validate_column_values", "lines": 14 } ] }, { "name": "EXCEPTIONS", "lines": 35, "subsections": [] }, { "name": "WARNINGS", "lines": 3, "subsections": [] }, { "name": "INSTANCE METHODS", "lines": 28, "subsections": [] }, { "name": "Changing Your Column Accessor Method Names", "lines": 30, "subsections": [ { "name": "mutator_name_for", "lines": 229 } ] }, { "name": "TABLE RELATIONSHIPS", "lines": 39, "subsections": [ { "name": "might_have", "lines": 101 }, { "name": "might_have", "lines": 16 }, { "name": "Notes", "lines": 1 }, { "name": "has_a", "lines": 11 } ] }, { "name": "MANY TO MANY RELATIONSHIPS", "lines": 46, "subsections": [] }, { "name": "ADDING NEW RELATIONSHIP TYPES", "lines": 13, "subsections": [] }, { "name": "DEFINING SQL STATEMENTS", "lines": 45, "subsections": [ { "name": "Ima::DBI queries", "lines": 29 }, { "name": "set_sql", "lines": 33 }, { "name": "Class::DBI::AbstractSearch", "lines": 8 }, { "name": "Single Value SELECTs", "lines": 37 } ] }, { "name": "LAZY POPULATION", "lines": 55, "subsections": [ { "name": "Non-Persistent Fields", "lines": 17 } ] }, { "name": "TRANSACTIONS", "lines": 15, "subsections": [ { "name": "Localised Transactions", "lines": 32 } ] }, { "name": "UNIQUENESS OF OBJECTS IN MEMORY", "lines": 59, "subsections": [] }, { "name": "SUBCLASSING", "lines": 12, "subsections": [] }, { "name": "CAVEATS", "lines": 1, "subsections": [ { "name": "Multi-Column Foreign Keys are not supported", "lines": 3 }, { "name": "Don't change or inflate the value of your primary columns", "lines": 3 } ] }, { "name": "SUPPORTED DATABASES", "lines": 17, "subsections": [] }, { "name": "CURRENT AUTHOR", "lines": 2, "subsections": [] }, { "name": "AUTHOR EMERITUS", "lines": 2, "subsections": [] }, { "name": "THANKS TO", "lines": 8, "subsections": [] }, { "name": "RELEASE PHILOSOPHY", "lines": 14, "subsections": [ { "name": "Getting changes accepted", "lines": 15 }, { "name": "Bug Reports", "lines": 12 }, { "name": "Patches", "lines": 16 }, { "name": "Feature Requests", "lines": 14 } ] }, { "name": "SUPPORT", "lines": 24, "subsections": [] }, { "name": "LICENSE", "lines": 3, "subsections": [] }, { "name": "SEE ALSO", "lines": 4, "subsections": [] } ], "sections": { "NAME": { "content": "Class::DBI - Simple Database Abstraction\n", "subsections": [] }, "SYNOPSIS": { "content": "package Music::DBI;\nuse base 'Class::DBI';\nMusic::DBI->connection('dbi:mysql:dbname', 'username', 'password');\n\npackage Music::Artist;\nuse base 'Music::DBI';\nMusic::Artist->table('artist');\nMusic::Artist->columns(All => qw/artistid name/);\nMusic::Artist->hasmany(cds => 'Music::CD');\n\npackage Music::CD;\nuse base 'Music::DBI';\nMusic::CD->table('cd');\nMusic::CD->columns(All => qw/cdid artist title year reldate/);\nMusic::CD->hasmany(tracks => 'Music::Track');\nMusic::CD->hasa(artist => 'Music::Artist');\nMusic::CD->hasa(reldate => 'Time::Piece',\ninflate => sub { Time::Piece->strptime(shift, \"%Y-%m-%d\") },\ndeflate => 'ymd',\n);\n\nMusic::CD->mighthave(linernotes => LinerNotes => qw/notes/);\n\npackage Music::Track;\nuse base 'Music::DBI';\nMusic::Track->table('track');\nMusic::Track->columns(All => qw/trackid cd position title/);\n\n#-- Meanwhile, in a nearby piece of code! --#\n\nmy $artist = Music::Artist->insert({ artistid => 1, name => 'U2' });\n\nmy $cd = $artist->addtocds({\ncdid => 1,\ntitle => 'October',\nyear => 1980,\n});\n\n# Oops, got it wrong.\n$cd->year(1981);\n$cd->update;\n\n# etc.\n\nforeach my $track ($cd->tracks) {\nprint $track->position, $track->title\n}\n\n$cd->delete; # also deletes the tracks\n\nmy $cd = Music::CD->retrieve(1);\nmy @cds = Music::CD->retrieveall;\nmy @cds = Music::CD->search(year => 1980);\nmy @cds = Music::CD->searchlike(title => 'October%');\n", "subsections": [] }, "INTRODUCTION": { "content": "Class::DBI provides a convenient abstraction layer to a database.\n\nIt not only provides a simple database to object mapping layer, but can be used to implement\nseveral higher order database functions (triggers, referential integrity, cascading delete\netc.), at the application level, rather than at the database.\n\nThis is particularly useful when using a database which doesn't support these (such as MySQL),\nor when you would like your code to be portable across multiple databases which might implement\nthese things in different ways.\n\nIn short, Class::DBI aims to make it simple to introduce 'best practice' when dealing with data\nstored in a relational database.\n", "subsections": [ { "name": "How to set it up", "content": "*Set up a database.*\nYou must have an existing database set up, have DBI.pm installed and the necessary DBD::\ndriver module for that database. See DBI and the documentation of your particular database\nand driver for details.\n\n*Set up a table for your objects to be stored in.*\nClass::DBI works on a simple one class/one table model. It is your responsibility to have\nyour database tables already set up. Automating that process is outside the scope of\nClass::DBI.\n\nUsing our CD example, you might declare a table something like this:\n\nCREATE TABLE cd (\ncdid INTEGER PRIMARY KEY,\nartist INTEGER, # references 'artist'\ntitle VARCHAR(255),\nyear CHAR(4),\n);\n\n*Set up an application base class*\nIt's usually wise to set up a \"top level\" class for your entire application to inherit from,\nrather than have each class inherit directly from Class::DBI. This gives you a convenient\npoint to place system-wide overrides and enhancements to Class::DBI's behavior.\n\npackage Music::DBI;\nuse base 'Class::DBI';\n\n*Give it a database connection*\nClass::DBI needs to know how to access the database. It does this through a DBI connection\nwhich you set up by calling the connection() method.\n\nMusic::DBI->connection('dbi:mysql:dbname', 'user', 'password');\n\nBy setting the connection up in your application base class all the table classes that\ninherit from it will share the same connection.\n\n*Set up each Class*\npackage Music::CD;\nuse base 'Music::DBI';\n\nEach class will inherit from your application base class, so you don't need to repeat the\ninformation on how to connect to the database.\n\n*Declare the name of your table*\nInform Class::DBI what table you are using for this class:\n\nMusic::CD->table('cd');\n\n*Declare your columns.*\nThis is done using the columns() method. In the simplest form, you tell it the name of all\nyour columns (with the single primary key first):\n\nMusic::CD->columns(All => qw/cdid artist title year/);\n\nIf the primary key of your table spans multiple columns then declare them using a separate\ncall to columns() like this:\n\nMusic::CD->columns(Primary => qw/pk1 pk2/);\nMusic::CD->columns(Others => qw/foo bar baz/);\n\nFor more information about how you can more efficiently use subsets of your columns, see\n\"LAZY POPULATION\"\n\n*Done.*\nThat's it! You now have a class with methods to \"insert\", \"retrieve\", \"search\" for, \"update\"\nand \"delete\" objects from your table, as well as accessors and mutators for each of the\ncolumns in that object (row).\n\nLet's look at all that in more detail:\n" } ] }, "CLASS METHODS": { "content": "connection\nPACKAGE->connection($datasource, $user, $password, \\%attr);\n\nThis sets up a database connection with the given information.\n\nThis uses Ima::DBI to set up an inheritable connection (named Main). It is therefore usual to\nonly set up a connection() in your application base class and let the 'table' classes inherit\nfrom it.\n\npackage Music::DBI;\nuse base 'Class::DBI';\n\nMusic::DBI->connection('dbi:foo:dbname', 'user', 'password');\n\npackage My::Other::Table;\nuse base 'Music::DBI';\n\nClass::DBI helps you along a bit to set up the database connection. connection() provides its\nown default attributes depending on the driver name in the datasource parameter. The", "subsections": [ { "name": "connection", "content": "FetchHashKeyName => 'NAMElc',\nShowErrorStatement => 1,\nChopBlanks => 1,\nAutoCommit => 1,\n\n(Except for Oracle and Pg, where AutoCommit defaults 0, placing the database in transactional\nmode).\n\nThe defaults can always be extended (or overridden if you know what you're doing) by supplying\nyour own \\%attr parameter. For example:\n\nMusic::DBI->connection(dbi:foo:dbname','user','pass',{ChopBlanks=>0});\n\nThe RootClass of DBIx::ContextualFetch in also inherited from Ima::DBI, and you should be very\ncareful not to change this unless you know what you're doing!\n\nDynamic Database Connections / dbMain\nIt is sometimes desirable to generate your database connection information dynamically, for\nexample, to allow multiple databases with the same schema to not have to duplicate an entire\nclass hierarchy.\n\nThe preferred method for doing this is to supply your own dbMain() method rather than calling\n\"connection\". This method should return a valid database handle, and should ensure it sets the\nstandard attributes described above, preferably by combining $class->defaultattributes() with\nyour own. Note, this handle *must* have its RootClass set to DBIx::ContextualFetch, so it is\nusually not possible to just supply a $dbh obtained elsewhere.\n\nNote that connection information is class data, and that changing it at run time may have\nunexpected behaviour for instances of the class already in existence.\n\ntable\nPACKAGE->table($table);\n\n$table = Class->table;\n$table = $obj->table;\n\nAn accessor to get/set the name of the database table in which this class is stored. It -must-\nbe set.\n\nTable information is inherited by subclasses, but can be overridden.\n\ntablealias\npackage Shop::Order;\nPACKAGE->table('orders');\nPACKAGE->tablealias('orders');\n\nWhen Class::DBI constructs SQL, it aliases your table name to a name representing your class.\nHowever, if your class's name is an SQL reserved word (such as 'Order') this will cause SQL\nerrors. In such cases you should supply your own alias for your table name (which can, of\ncourse, be the same as the actual table name).\n\nThis can also be passed as a second argument to 'table':\n\nPACKAGE->table('orders', 'orders');\n\nAs with table, this is inherited but can be overridden.\n\nsequence / autoincrement\nPACKAGE->sequence($sequencename);\n\n$sequencename = Class->sequence;\n$sequencename = $obj->sequence;\n\nIf you are using a database which supports sequences and you want to use a sequence to\nautomatically supply values for the primary key of a table, then you should declare this using\nthe sequence() method:\n\nPACKAGE->columns(Primary => 'id');\nPACKAGE->sequence('classidseq');\n\nClass::DBI will use the sequence to generate a primary key value when objects are inserted\nwithout one.\n\n*NOTE* This method does not work for Oracle. However, Class::DBI::Oracle (which can be\ndownloaded separately from CPAN) provides a suitable replacement sequence() method.\n\nIf you are using a database with AUTOINCREMENT (e.g. MySQL) then you do not need this, and any\ncall to insert() without a primary key specified will fill this in automagically.\n\nSequence and auto-increment mechanisms only apply to tables that have a single column primary\nkey. For tables with multi-column primary keys you need to supply the key values manually.\n\nCONSTRUCTORS and DESTRUCTORS\nThe following are methods provided for convenience to insert, retrieve and delete stored\nobjects. It's not entirely one-size fits all and you might find it necessary to override them.\n\ninsert\nmy $obj = Class->insert(\\%data);\n\nThis is a constructor to insert new data into the database and create an object representing the\nnewly inserted row.\n\n%data consists of the initial information to place in your object and the database. The keys of\n%data match up with the columns of your objects and the values are the initial settings of those\nfields.\n\nmy $cd = Music::CD->insert({\ncdid => 1,\nartist => $artist,\ntitle => 'October',\nyear => 1980,\n});\n\nIf the table has a single primary key column and that column value is not defined in %data," }, { "name": "insert", "content": "it will use that. Otherwise, it will assume the primary key can be generated by AUTOINCREMENT\nand attempt to use that.\n\nThe \"beforecreate\" trigger is invoked directly after storing the supplied values into the new\nobject and before inserting the record into the database. The object stored in $self may not\nhave all the functionality of the final object aftercreation, particularly if the database is\ngoing to be providing the primary key value.\n\nFor tables with multi-column primary keys you need to supply all the key values, either in the\narguments to the insert() method, or by setting the values in a \"beforecreate\" trigger.\n\nIf the class has declared relationships with foreign classes via hasa(), you can pass an object\nto insert() for the value of that key. Class::DBI will Do The Right Thing.\n\nAfter the new record has been inserted into the database the data for non-primary key columns is\ndiscarded from the object. If those columns are accessed again they'll simply be fetched as\nneeded. This ensures that the data in the application is consistent with what the database\n*actually* stored.\n\nThe \"aftercreate\" trigger is invoked after the database insert has executed.\n\nfindorcreate\nmy $cd = Music::CD->findorcreate({ artist => 'U2', title => 'Boy' });\n\nThis checks if a CD can be found to match the information passed, and if not inserts it.\n\ndelete\n$obj->delete;\nMusic::CD->search(year => 1980, title => 'Greatest %')->deleteall;\n\nDeletes this object from the database and from memory. If you have set up any relationships\nusing \"hasmany\" or \"mighthave\", this will delete the foreign elements also, recursively\n(cascading delete). $obj is no longer usable after this call.\n\nMultiple objects can be deleted by calling deleteall on the Iterator returned from a search.\nEach object found will be deleted in turn, so cascading delete and other triggers will be\nhonoured.\n\nThe \"beforedelete\" trigger is when an object instance is about to be deleted. It is invoked\nbefore any cascaded deletes. The \"afterdelete\" trigger is invoked after the record has been\ndeleted from the database and just before the contents in memory are discarded.\n" } ] }, "RETRIEVING OBJECTS": { "content": "Class::DBI provides a few very simple search methods.\n\nIt is not the goal of Class::DBI to replace the need for using SQL. Users are expected to write\ntheir own searches for more complex cases.\n\nClass::DBI::AbstractSearch, available on CPAN, provides a much more complex search interface\nthan Class::DBI provides itself.\n\nretrieve\n$obj = Class->retrieve( $id );\n$obj = Class->retrieve( %keyvalues );\n\nGiven key values it will retrieve the object with that key from the database. For tables with a\nsingle column primary key a single parameter can be used, otherwise a hash of key-name key-value\npairs must be given.\n\nmy $cd = Music::CD->retrieve(1) or die \"No such cd\";\n\nretrieveall\nmy @objs = Class->retrieveall;\nmy $iterator = Class->retrieveall;\n\nRetrieves objects for all rows in the database. This is probably a bad idea if your table is\nbig, unless you use the iterator version.\n\nsearch\n@objs = Class->search(column1 => $value, column2 => $value ...);\n\nThis is a simple search for all objects where the columns specified are equal to the values\nspecified e.g.:\n\n@cds = Music::CD->search(year => 1990);\n@cds = Music::CD->search(title => \"Greatest Hits\", year => 1990);\n\nYou may also specify the sort order of the results by adding a final hash of arguments with the\nkey 'orderby':\n\n@cds = Music::CD->search(year => 1990, { orderby=>'artist' });\n\nThis is passed through 'as is', enabling orderby clauses such as 'year DESC, title'.\n\nsearchlike\n@objs = Class->searchlike(column1 => $likepattern, ....);\n\nThis is a simple search for all objects where the columns specified are like the values\nspecified. $likepattern is a pattern given in SQL LIKE predicate syntax. '%' means \"any zero or\nmore characters\", '' means \"any single character\".\n\n@cds = Music::CD->searchlike(title => 'October%');\n@cds = Music::CD->searchlike(title => 'Hits%', artist => 'Various%');\n\nYou can also use 'orderby' with these, as with search().\n", "subsections": [] }, "ITERATORS": { "content": "my $it = Music::CD->searchlike(title => 'October%');\nwhile (my $cd = $it->next) {\nprint $cd->title;\n}\n\nAny of the above searches (as well as those defined by hasmany) can also be used as an\niterator. Rather than creating a list of objects matching your criteria, this will return a\nClass::DBI::Iterator instance, which can return the objects required one at a time.\n\nCurrently the iterator initially fetches all the matching row data into memory, and defers only\nthe creation of the objects from that data until the iterator is asked for the next object. So\nusing an iterator will only save significant memory if your objects will inflate substantially\nwhen used.\n\nIn the case of hasmany relationships with a mapping method, the mapping method is not called\nuntil each time you call 'next'. This means that if your mapping is not a one-to-one, the\nresults will probably not be what you expect.\n", "subsections": [ { "name": "Subclassing the Iterator", "content": "Music::CD->iteratorclass('Music::CD::Iterator');\n\nYou can also subclass the default iterator class to override its functionality. This is done via\nclass data, and so is inherited into your subclasses.\n\nQUICK RETRIEVAL\nmy $obj = Class->construct(\\%data);\n\nThis is used to turn data from the database into objects, and should thus only be used when\nwriting constructors. It is very handy for cheaply setting up lots of objects from data for\nwithout going back to the database.\n\nFor example, instead of doing one SELECT to get a bunch of IDs and then feeding those\nindividually to retrieve() (and thus doing more SELECT calls), you can do one SELECT to get the\nessential data of many objects and feed that data to construct():\n\nreturn map $class->construct($), $sth->fetchallhash;\n\nThe construct() method creates a new empty object, loads in the column values, and then invokes\nthe \"select\" trigger.\n" } ] }, "COPY AND MOVE": { "content": "copy\n$newobj = $obj->copy;\n$newobj = $obj->copy($newid);\n$newobj = $obj->copy({ title => 'newtitle', rating => 18 });\n\nThis creates a copy of the given $obj, removes the primary key, sets any supplied column values\nand calls insert() to make a new record in the database.\n\nFor tables with a single column primary key, copy() can be called with no parameters and the new\nobject will be assigned a key automatically. Or a single parameter can be supplied and will be\nused as the new key.\n\nFor tables with a multi-column primary key, copy() must be called with parameters which supply\nnew values for all primary key columns, unless a \"beforecreate\" trigger will supply them. The", "subsections": [ { "name": "insert", "content": "my $blrunnerdc = $blrunner->copy(\"Bladerunner: Director's Cut\");\nmy $blrunnerunrated = $blrunner->copy({\nTitle => \"Bladerunner: Director's Cut\",\nRating => 'Unrated',\n});\n\nmove\nmy $newobj = Sub::Class->move($oldobj);\nmy $newobj = Sub::Class->move($oldobj, $newid);\nmy $newobj = Sub::Class->move($oldobj, \\%changes);\n\nFor transferring objects from one class to another. Similar to copy(), an instance of Sub::Class\nis inserted using the data in $oldobj (Sub::Class is a subclass of $oldobj's subclass). Like" }, { "name": "copy", "content": "autoincrement is used), or a hashref of multiple new values.\n" } ] }, "TRIGGERS": { "content": "PACKAGE->addtrigger(triggerpointname => \\&codetoexecute);\n\n# e.g.\n\nPACKAGE->addtrigger(aftercreate => \\&callaftercreate);\n\nIt is possible to set up triggers that will be called at various points in the life of an\nobject. Valid trigger points are:\n\nbeforecreate (also used for deflation)\naftercreate\nbeforeset$column (also used by addconstraint)\nafterset$column (also used for inflation and by hasa)\nbeforeupdate (also used for deflation and by mighthave)\nafterupdate\nbeforedelete\nafterdelete\nselect (also used for inflation and by construct and flesh)\n\nYou can create any number of triggers for each point, but you cannot specify the order in which\nthey will be run.\n\nAll triggers are passed the object they are being fired for, except when \"beforeset$column\" is\nfired during \"insert\", in which case the class is passed in place of the object, which does not\nyet exist. You may change object values if required.\n\nSome triggers are also passed extra parameters as name-value pairs. The individual triggers are\nfurther documented with the methods that trigger them.\n", "subsections": [] }, "CONSTRAINTS": { "content": "PACKAGE->addconstraint('name', column => \\&checksub);\n\n# e.g.\n\nPACKAGE->addconstraint('over18', age => \\&checkage);\n\n# Simple version\nsub checkage {\nmy ($value) = @;\nreturn $value >= 18;\n}\n\n# Cross-field checking - must have SSN if age < 18\nsub checkage {\nmy ($value, $self, $columnname, $changing) = @;\nreturn 1 if $value >= 18; # We're old enough.\nreturn 1 if $changing->{SSN}; # We're also being given an SSN\nreturn 0 if !ref($self); # This is an insert, so we can't have an SSN\nreturn 1 if $self->ssn; # We already have one in the database\nreturn 0; # We can't find an SSN anywhere\n}\n\nIt is also possible to set up constraints on the values that can be set on a column. The\nconstraint on a column is triggered whenever an object is created and whenever the value in that\ncolumn is being changed.\n\nThe constraint code is called with four parameters:\n\n- The new value to be assigned\n- The object it will be assigned to\n(or class name when initially creating an object)\n- The name of the column\n(useful if many constraints share the same code)\n- A hash ref of all new column values being assigned\n(useful for cross-field validation)\n\nThe constraints are applied to all the columns being set before the object data is changed.\nAttempting to create or modify an object where one or more constraint fail results in an\nexception and the object remains unchanged.\n\nThe exception thrown has its data set to a hashref of the column being changed and the value\nbeing changed to.\n\nNote 1: Constraints are implemented using beforeset$column triggers. This will only prevent\nyou from setting these values through a the provided insert() or set() methods. It will always\nbe possible to bypass this if you try hard enough.\n\nNote 2: When an object is created constraints are currently only checked for column names\nincluded in the parameters to insert(). This is probably a bug and is likely to change in\nfuture.\n\nconstraincolumn\nFilm->constraincolumn(year => qr/^\\d{4}$/);\nFilm->constraincolumn(rating => [qw/U Uc PG 12 15 18/]);\nFilm->constraincolumn(title => sub { length() <= 20 });\n\nSimple anonymous constraints can also be added to a column using the constraincolumn() method.\nBy default this takes either a regex which must match, a reference to a list of possible values,\nor a subref which will have $ aliased to the value being set, and should return a true or false\nvalue.\n\nHowever, this behaviour can be extended (or replaced) by providing a constraint handler for the\ntype of argument passed to constraincolumn. This behavior should be provided in a method named\n\"constrainby$type\", where $type is the moniker of the argument. For example, the year example\nabove could be provided by constrainbyarray().\n", "subsections": [] }, "DATA NORMALIZATION": { "content": "Before an object is assigned data from the application (via insert or a set accessor) the", "subsections": [ { "name": "normalize_column_values", "content": "names and the new values which are to be assigned (after any validation and constraint checking,\nas described below).\n\nCurrently Class::DBI does not offer any per-column mechanism here. The default method is empty.\nYou can override it in your own classes to normalize (edit) the data in any way you need. For\nexample the values in the hash for certain columns could be made lowercase.\n\nThe method is called as an instance method when the values of an existing object are being\nchanged, and as a class method when a new object is being created.\n" } ] }, "DATA VALIDATION": { "content": "Before an object is assigned data from the application (via insert or a set accessor) the", "subsections": [ { "name": "validate_column_values", "content": "and the new values which are to be assigned.\n\nThe method is called as an instance method when the values of an existing object are being\nchanged, and as a class method when a new object is being inserted.\n\nThe default method calls the beforeset$column trigger for each column name in the hash. Each\ntrigger is called inside an eval. Any failures result in an exception after all have been\nchecked. The exception data is a reference to a hash which holds the column name and error text\nfor each trigger error.\n\nWhen using this mechanism for form data validation, for example, this exception data can be\nstored in an exception object, via a custom croak() method, and then caught and used to\nredisplay the form with error messages next to each field which failed validation.\n" } ] }, "EXCEPTIONS": { "content": "All errors that are generated, or caught and propagated, by Class::DBI are handled by calling\nthe croak() method (as an instance method if possible, or else as a class method).\n\nThe croak() method is passed an error message and in some cases some extra information as\ndescribed below. The default behaviour is simply to call Carp::croak($message).\n\nApplications that require custom behaviour should override the croak() method in their\napplication base class (or table classes for table-specific behaviour). For example:\n\nuse Error;\n\nsub croak {\nmy ($self, $message, %info) = @;\n# convert errors into exception objects\n# except for duplicate insert errors which we'll ignore\nError->throw(-text => $message, %info)\nunless $message =~ /^Can't insert .* duplicate/;\nreturn;\n}\n\nThe croak() method is expected to trigger an exception and not return. If it does return then\nit should use \"return;\" so that an undef or empty list is returned as required depending on the\ncalling context. You should only return other values if you are prepared to deal with the\n(unsupported) consequences.\n\nFor exceptions that are caught and propagated by Class::DBI, $message includes the text of $@\nand the original $@ value is available in $info{err}. That allows you to correctly propagate\nexception objects that may have been thrown 'below' Class::DBI (using Exception::Class::DBI for\nexample).\n\nExceptions generated by some methods may provide additional data in $info{data} and, if so, also\nstore the method name in $info{method}. For example, the validatecolumnvalues() method stores\ndetails of failed validations in $info{data}. See individual method documentation for what\nadditional data they may store, if any.\n", "subsections": [] }, "WARNINGS": { "content": "All warnings are handled by calling the carp() method (as an instance method if possible, or\nelse as a class method). The default behaviour is simply to call Carp::carp().\n", "subsections": [] }, "INSTANCE METHODS": { "content": "accessors\nClass::DBI inherits from Class::Accessor and thus provides individual accessor methods for every\ncolumn in your subclass. It also overrides the get() and set() methods provided by Accessor to\nautomagically handle database reading and writing. (Note that as it doesn't make sense to store\na list of values in a column, set() takes a hash of column => value pairs, rather than the\nsingle key => values of Class::Accessor).\n\nthe fundamental set() and get() methods\n$value = $obj->get($columnname);\n@values = $obj->get(@columnnames);\n\n$obj->set($columnname => $value);\n$obj->set($col1 => $value1, $col2 => $value2 ... );\n\nThese methods are the fundamental entry points for getting and setting column values. The extra\naccessor methods automatically generated for each column of your table are simple wrappers that\ncall these get() and set() methods.\n\nThe set() method calls normalizecolumnvalues() then validatecolumnvalues() before storing\nthe values. The \"beforeset$column\" trigger is invoked by validatecolumnvalues(), checking\nany constraints that may have been set up.\n\nThe \"afterset$column\" trigger is invoked after the new value has been stored.\n\nIt is possible for an object to not have all its column data in memory (due to lazy inflation).\nIf the get() method is called for such a column then it will select the corresponding group of\ncolumns and then invoke the \"select\" trigger.\n", "subsections": [] }, "Changing Your Column Accessor Method Names": { "content": "accessornamefor / mutatornamefor\nIt is possible to change the name of the accessor method created for a column either\ndeclaratively or programmatically.\n\nIf, for example, you have a column with a name that clashes with a method otherwise created by\nClass::DBI, such as 'metainfo', you could create that Column explicitly with a different\naccessor (and/or mutator) when setting up your columns:\n\nmy $metacol = Class::DBI::Column->new(metainfo => {\naccessor => 'metadata',\n});\n\nPACKAGE->columns(All => qw/id name/, $metacol);\n\nIf you want to change the name of all your accessors, or all that match a certain pattern, you\nneed to provide an accessornamefor($col) method, which will convert a column name to a method\nname.\n\ne.g: if your local database naming convention was to prepend the word 'customer' to each column\nin the 'customer' table, so that you had the columns 'customerid', 'customername' and\n'customerage', but you wanted your methods to just be $customer->name and $customer->age rather\nthan $customer->customername etc., you could create a\n\nsub accessornamefor {\nmy ($class, $column) = @;\n$column =~ s/^customer//;\nreturn $column;\n}\n\nSimilarly, if you wanted to have distinct accessor and mutator methods, you could provide a", "subsections": [ { "name": "mutator_name_for", "content": "sub mutatornamefor {\nmy ($class, $column) = @;\nreturn \"set\" . $column->accessor;\n}\n\nIf you override the mutator name, then the accessor method will be enforced as read-only, and\nthe mutator as write-only.\n\nupdate vs auto update\nThere are two modes for the accessors to work in: manual update and autoupdate. When in\nautoupdate mode, every time one calls an accessor to make a change an UPDATE will immediately be\nsent to the database. Otherwise, if autoupdate is off, no changes will be written until update()\nis explicitly called.\n\nThis is an example of manual updating:\n\n# The calls to NumExplodingSheep() and Rating() will only make the\n# changes in memory, not in the database. Once update() is called\n# it writes to the database in one swell foop.\n$gone->NumExplodingSheep(5);\n$gone->Rating('NC-17');\n$gone->update;\n\nAnd of autoupdating:\n\n# Turn autoupdating on for this object.\n$gone->autoupdate(1);\n\n# Each accessor call causes the new value to immediately be written.\n$gone->NumExplodingSheep(5);\n$gone->Rating('NC-17');\n\nManual updating is probably more efficient than autoupdating and it provides the extra safety of\na discardchanges() option to clear out all unsaved changes. Autoupdating can be more convenient\nfor the programmer. Autoupdating is *off* by default.\n\nIf changes are neither updated nor rolled back when the object is destroyed (falls out of scope\nor the program ends) then Class::DBI's DESTROY method will print a warning about unsaved\nchanges.\n\nautoupdate\nPACKAGE->autoupdate($onoroff);\n$updatestyle = Class->autoupdate;\n\n$obj->autoupdate($onoroff);\n$updatestyle = $obj->autoupdate;\n\nThis is an accessor to the current style of auto-updating. When called with no arguments it\nreturns the current auto-updating state, true for on, false for off. When given an argument it\nturns auto-updating on and off: a true value turns it on, a false one off.\n\nWhen called as a class method it will control the updating style for every instance of the\nclass. When called on an individual object it will control updating for just that object,\noverriding the choice for the class.\n\nPACKAGE->autoupdate(1); # Autoupdate is now on for the class.\n\n$obj = Class->retrieve('Aliens Cut My Hair');\n$obj->autoupdate(0); # Shut off autoupdating for this object.\n\nThe update setting for an object is not stored in the database.\n\nupdate\n$obj->update;\n\nIf \"autoupdate\" is not enabled then changes you make to your object are not reflected in the\ndatabase until you call update(). It is harmless to call update() if there are no changes to be\nsaved. (If autoupdate is on there'll never be anything to save.)\n\nNote: If you have transactions turned on for your database (but see \"TRANSACTIONS\" below) you\nwill also need to call dbicommit(), as update() merely issues the UPDATE to the database).\n\nAfter the database update has been executed, the data for columns that have been updated are\ndeleted from the object. If those columns are accessed again they'll simply be fetched as\nneeded. This ensures that the data in the application is consistent with what the database\n*actually* stored.\n\nWhen update() is called the \"beforeupdate\"($self) trigger is always invoked immediately.\n\nIf any columns have been updated then the \"afterupdate\" trigger is invoked after the database\nupdate has executed and is passed: ($self, discardcolumns => \\@discardcolumns)\n\nThe trigger code can modify the discardcolumns array to affect which columns are discarded.\n\nFor example:\n\nClass->addtrigger(afterupdate => sub {\nmy ($self, %args) = @;\nmy $discardcolumns = $args{discardcolumns};\n# discard the md5hash column if any field starting with 'foo'\n# has been updated - because the md5hash will have been changed\n# by a trigger.\npush @$discardcolumns, 'md5hash' if grep { /^foo/ } @$discardcolumns;\n});\n\nTake care to not delete a primary key column unless you know what you're doing.\n\nThe update() method returns the number of rows updated. If the object had not changed and thus\ndid not need to issue an UPDATE statement, the update() call will have a return value of -1.\n\nIf the record in the database has been deleted, or its primary key value changed, then the\nupdate will not affect any records and so the update() method will return 0.\n\ndiscardchanges\n$obj->discardchanges;\n\nRemoves any changes you've made to this object since the last update. Currently this simply\ndiscards the column values from the object.\n\nIf you're using autoupdate this method will throw an exception.\n\nischanged\nmy $changed = $obj->ischanged;\nmy @changedkeys = $obj->ischanged;\n\nIndicates if the given $obj has changes since the last update. Returns a list of keys which have\nchanged. (If autoupdate is on, this method will return an empty list, unless called inside a\nbeforeupdate or afterset$column trigger)\n\nid\n$id = $obj->id;\n@id = $obj->id;\n\nReturns a unique identifier for this object based on the values in the database. It's the\nequivalent of $obj->get($self->columns('Primary')), with inflated values reduced to their ids.\n\nA warning will be generated if this method is used in scalar context on a table with a\nmulti-column primary key.\n\nLOW-LEVEL DATA ACCESS\nOn some occasions, such as when you're writing triggers or constraint routines, you'll want to\nmanipulate data in a Class::DBI object without using the usual get() and set() accessors, which\nmay themselves call triggers, fetch information from the database, etc.\n\nRather than interacting directly with the data hash stored in a Class::DBI object (the exact\nimplementation of which may change in future releases) you could use Class::DBI's low-level\naccessors. These appear 'private' to make you think carefully about using them - they should not\nbe a common means of dealing with the object.\n\nThe data within the object is modelled as a set of key-value pairs, where the keys are\nnormalized column names (returned by findcolumn()), and the values are the data from the\ndatabase row represented by the object. Access is via these functions:\n\nattrs\n@values = $object->attrs(@cols);\n\nReturns the values for one or more keys.\n\nattributestore\n$object->attributestore( { $col0 => $val0, $col1 => $val1 } );\n$object->attributestore($col0, $val0, $col1, $val1);\n\nStores values in the object. They key-value pairs may be passed in either as a simple list\nor as a hash reference. This only updates values in the object itself; changes will not be\npropagated to the database.\n\nattributeset\n$object->attributeset( { $col0 => $val0, $col1 => $val1 } );\n$object->attributeset($col0, $val0, $col1, $val1);\n\nUpdates values in the object via attributestore(), but also logs the changes so that they\nare propagated to the database with the next update. (Unlike set(), however,\nattributeset() will not trigger an update if autoupdate is turned on.)\n\nattributedelete\n@values = $object->attributedelete(@cols);\n\nDeletes values from the object, and returns the deleted values.\n\nattributeexists\n$bool = $object->attributeexists($col);\n\nReturns a true value if the object contains a value for the specified column, and a false\nvalue otherwise.\n\nBy default, Class::DBI uses simple hash references to store object data, but all access is via\nthese routines, so if you want to implement a different data model, just override these\nfunctions.\n\nOVERLOADED OPERATORS\nClass::DBI and its subclasses overload the perl builtin *stringify* and *bool* operators. This\nis a significant convenience.\n\nThe perl builtin *bool* operator is overloaded so that a Class::DBI object reference is true so\nlong as all its key columns have defined values. (This means an object with an id() of zero is\nnot considered false.)\n\nWhen a Class::DBI object reference is used in a string context it will, by default, return the\nvalue of the primary key. (Composite primary key values will be separated by a slash).\n\nYou can also specify the column(s) to be used for stringification via the special 'Stringify'\ncolumn group. So, for example, if you're using an auto-incremented primary key, you could use\nthis to provide a more meaningful display string:\n\nWidget->columns(Stringify => qw/name/);\n\nIf you need to do anything more complex, you can provide an stringifyself() method which\nstringification will call:\n\nsub stringifyself {\nmy $self = shift;\nreturn join \":\", $self->id, $self->name;\n}\n\nThis overloading behaviour can be useful for columns that have hasa() relationships. For\nexample, consider a table that has price and currency fields:\n\npackage Widget;\nuse base 'My::Class::DBI';\nWidget->table('widget');\nWidget->columns(All => qw/widgetid name price currencycode/);\n\n$obj = Widget->retrieve($id);\nprint $obj->price . \" \" . $obj->currencycode;\n\nThe would print something like \"\"42.07 USD\"\". If the currencycode field is later changed to be\na foreign key to a new currency table then $obj->currencycode will return an object reference\ninstead of a plain string. Without overloading the stringify operator the example would now\nprint something like \"\"42.07 Widget=HASH(0x1275}\"\" and the fix would be to change the code to\nadd a call to id():\n\nprint $obj->price . \" \" . $obj->currencycode->id;\n\nHowever, with overloaded stringification, the original code continues to work as before, with no\ncode changes needed.\n\nThis makes it much simpler and safer to add relationships to existing applications, or remove\nthem later.\n" } ] }, "TABLE RELATIONSHIPS": { "content": "Databases are all about relationships. Thus Class::DBI provides a way for you to set up\ndescriptions of your relationhips.\n\nClass::DBI provides three such relationships: 'hasa', 'hasmany', and 'mighthave'. Others are\navailable from CPAN.\n\nhasa\nMusic::CD->hasa(column => 'Foreign::Class');\n\nMusic::CD->hasa(artist => 'Music::Artist');\nprint $cd->artist->name;\n\n'hasa' is most commonly used to supply lookup information for a foreign key. If a column is\ndeclared as storing the primary key of another table, then calling the method for that column\ndoes not return the id, but instead the relevant object from that foreign class.\n\nIt is also possible to use hasa to inflate the column value to a non Class::DBI based. A common\nusage would be to inflate a date field to a date/time object:\n\nMusic::CD->hasa(reldate => 'Date::Simple');\nprint $cd->reldate->format(\"%d %b, %Y\");\n\nMusic::CD->hasa(reldate => 'Time::Piece',\ninflate => sub { Time::Piece->strptime(shift, \"%Y-%m-%d\") },\ndeflate => 'ymd',\n);\nprint $cd->reldate->strftime(\"%d %b, %Y\");\n\nIf the foreign class is another Class::DBI representation retrieve is called on that class with\nthe column value. Any other object will be instantiated either by calling new($value) or using\nthe given 'inflate' method. If the inflate method name is a subref, it will be executed, and\nwill be passed the value and the Class::DBI object as arguments.\n\nWhen the object is being written to the database the object will be deflated either by calling\nthe 'deflate' method (if given), or by attempting to stringify the object. If the deflate method\nis a subref, it will be passed the Class::DBI object as an argument.\n\n*NOTE* You should not attempt to make your primary key column inflate using hasa() as bad\nthings will happen. If you have two tables which share a primary key, consider using", "subsections": [ { "name": "might_have", "content": "hasmany\nClass->hasmany(methodtocreate => \"Foreign::Class\");\n\nMusic::CD->hasmany(tracks => 'Music::Track');\n\nmy @tracks = $cd->tracks;\n\nmy $track6 = $cd->addtotracks({\nposition => 6,\ntitle => 'Tomorrow',\n});\n\nThis method declares that another table is referencing us (i.e. storing our primary key in its\ntable).\n\nIt creates a named accessor method in our class which returns a list of all the matching\nForeign::Class objects.\n\nIn addition it creates another method which allows a new associated object to be constructed,\ntaking care of the linking automatically. This method is the same as the accessor method with\n\"addto\" prepended.\n\nThe addtotracks example above is exactly equivalent to:\n\nmy $track6 = Music::Track->insert({\ncd => $cd,\nposition => 6,\ntitle => 'Tomorrow',\n});\n\nWhen setting up the relationship the foreign class's hasa() declarations are examined to\ndiscover which of its columns reference our class. (Note that because this happens at compile\ntime, if the foreign class is defined in the same file, the class with the hasa() must be\ndefined earlier than the class with the hasmany(). If the classes are in different files,\nClass::DBI should usually be able to do the right things, as long as all classes inherit\nClass::DBI before 'use'ing any other classes.)\n\nIf the foreign class has no hasa() declarations linking to this class, it is assumed that the\nforeign key in that class is named after the moniker() of this class.\n\nIf this is not true you can pass an additional third argument to the hasmany() declaration\nstating which column of the foreign class is the foreign key to this class.\n\nLimiting\nMusic::Artist->hasmany(cds => 'Music::CD');\nmy @cds = $artist->cds(year => 1980);\n\nWhen calling the method created by hasmany, you can also supply any additional key/value pairs\nfor restricting the search. The above example will only return the CDs with a year of 1980.\n\nOrdering\nMusic::CD->hasmany(tracks => 'Music::Track', { orderby => 'playorder' });\n\nhasmany takes an optional final hashref of options. If an 'orderby' option is set, its value\nwill be set in an ORDER BY clause in the SQL issued. This is passed through 'as is', enabling\norderby clauses such as 'length DESC, position'.\n\nMapping\nMusic::CD->hasmany(styles => [ 'Music::StyleRef' => 'style' ]);\n\nIf the second argument to hasmany is turned into a listref of the Classname and an additional\nmethod, then that method will be called in turn on each of the objects being returned.\n\nThe above is exactly equivalent to:\n\nMusic::CD->hasmany(stylerefs => 'Music::StyleRef');\n\nsub styles {\nmy $self = shift;\nreturn map $->style, $self->stylerefs;\n}\n\nFor an example of where this is useful see \"MANY TO MANY RELATIONSHIPS\" below.\n\nCascading Delete\nMusic::Artist->hasmany(cds => 'Music::CD', { cascade => 'Fail' });\n\nIt is also possible to control what happens to the 'child' objects when the 'parent' object is\ndeleted. By default this is set to 'Delete' - so, for example, when you delete an artist, you\nalso delete all their CDs, leaving no orphaned records. However you could also set this to\n'None', which would leave all those orphaned records (although this generally isn't a good\nidea), or 'Fail', which will throw an exception when you try to delete an artist that still has\nany CDs.\n\nYou can also write your own Cascade strategies by supplying a Class Name here.\n\nFor example you could write a Class::DBI::Cascade::Plugin::Nullify which would set all related\nforeign keys to be NULL, and plug it into your relationship:\n\nMusic::Artist->hasmany(cds => 'Music::CD', {\ncascade => 'Class::DBI::Cascade::Plugin::Nullify'\n});\n\nmighthave\nMusic::CD->mighthave(methodname => Class => (@fieldstoimport));\n\nMusic::CD->mighthave(linernotes => LinerNotes => qw/notes/);\n\nmy $linernotesobject = $cd->linernotes;\nmy $notes = $cd->notes; # equivalent to $cd->linernotes->notes;\n" }, { "name": "might_have", "content": "objects. For example, if you have a CD database to which you want to add liner notes\ninformation, you might not want to add a 'linernotes' column to your main CD table even though\nthere is no multiplicity of relationship involved (each CD has at most one 'liner notes' field).\nSo, you create another table with the same primary key as this one, with which you can\ncross-reference.\n\nBut you don't want to have to keep writing methods to turn the the 'list' of linernotes objects\nyou'd get back from hasmany into the single object you'd need. So, mighthave() does this work\nfor you. It creates an accessor to fetch the single object back if it exists, and it also allows\nyou import any of its methods into your namespace. So, in the example above, the LinerNotes\nclass can be mostly invisible - you can just call $cd->notes and it will call the notes method\non the correct LinerNotes object transparently for you.\n\nMaking sure you don't have namespace clashes is up to you, as is correctly creating the objects,\nbut this may be made simpler in later versions. (Particularly if someone asks for this!)\n" }, { "name": "Notes", "content": "" }, { "name": "has_a", "content": "it hasn't then they try to load the module of the same name using require. If the require fails\nbecause it can't find the module then it will assume it's not a simple require (i.e.,\nForeign::Class isn't in Foreign/Class.pm) and that you will take care of it and ignore the\nwarning. Any other error, such as a syntax error, triggers an exception.\n\nNOTE: The two classes in a relationship do not have to be in the same database, on the same\nmachine, or even in the same type of database! It is quite acceptable for a table in a MySQL\ndatabase to be connected to a different table in an Oracle database, and for cascading delete\netc to work across these. This should assist greatly if you need to migrate a database\ngradually.\n" } ] }, "MANY TO MANY RELATIONSHIPS": { "content": "Class::DBI does not currently support Many to Many relationships, per se. However, by combining\nthe relationships that already exist it is possible to set these up.\n\nConsider the case of Films and Actors, with a linking Role table with a multi-column Primary\nKey. First of all set up the Role class:\n\nRole->table('role');\nRole->columns(Primary => qw/film actor/);\nRole->hasa(film => 'Film');\nRole->hasa(actor => 'Actor');\n\nThen, set up the Film and Actor classes to use this linking table:\n\nFilm->table('film');\nFilm->columns(All => qw/id title rating/);\nFilm->hasmany(stars => [ Role => 'actor' ]);\n\nActor->table('actor');\nActor->columns(All => qw/id name/);\nActor->hasmany(films => [ Role => 'film' ]);\n\nIn each case the 'mapping method' variation of hasmany() is used to call the lookup method on\nthe Role object returned. As these methods are the 'hasa' relationships on the Role, these will\nreturn the actual Actor and Film objects, providing a cheap many-to-many relationship.\n\nIn the case of Film, this is equivalent to the more long-winded:\n\nFilm->hasmany(roles => \"Role\");\n\nsub actors {\nmy $self = shift;\nreturn map $->actor, $self->roles\n}\n\nAs this is almost exactly what is created internally, addtostars and addtofilms will\ngenerally do the right thing as they are actually doing the equivalent of addtoroles:\n\n$film->addtoactors({ actor => $actor });\n\nSimilarly a cascading delete will also do the right thing as it will only delete the\nrelationship from the linking table.\n\nIf the Role table were to contain extra information, such as the name of the character played,\nthen you would usually need to skip these short-cuts and set up each of the relationships, and\nassociated helper methods, manually.\n", "subsections": [] }, "ADDING NEW RELATIONSHIP TYPES": { "content": "addrelationshiptype\nThe relationships described above are implemented through Class::DBI::Relationship subclasses.\nThese are then plugged into Class::DBI through an addrelationshiptype() call:\n\nPACKAGE->addrelationshiptype(\nhasa => \"Class::DBI::Relationship::HasA\",\nhasmany => \"Class::DBI::Relationship::HasMany\",\nmighthave => \"Class::DBI::Relationship::MightHave\",\n);\n\nIf is thus possible to add new relationship types, or modify the behaviour of the existing\ntypes. See Class::DBI::Relationship for more information on what is required.\n", "subsections": [] }, "DEFINING SQL STATEMENTS": { "content": "There are several main approaches to setting up your own SQL queries:\n\nFor queries which could be used to create a list of matching objects you can create a\nconstructor method associated with this SQL and let Class::DBI do the work for you, or just\ninline the entire query.\n\nFor more complex queries you need to fall back on the underlying Ima::DBI query mechanism.\n(Caveat: since Ima::DBI uses sprintf-style interpolation, you need to be careful to double any\n\"wildcard\" % signs in your queries).\n\naddconstructor\nPACKAGE->addconstructor(methodname => 'SQLwhereclause');\n\nThe SQL can be of arbitrary complexity and will be turned into:\n\nSELECT (essential columns)\nFROM (table name)\nWHERE \n\nThis will then create a method of the name you specify, which returns a list of objects as with\nany built in query.\n\nFor example:\n\nMusic::CD->addconstructor(newmusic => 'year > 2000');\nmy @recent = Music::CD->newmusic;\n\nYou can also supply placeholders in your SQL, which must then be specified at query time:\n\nMusic::CD->addconstructor(newmusic => 'year > ?');\nmy @recent = Music::CD->newmusic(2000);\n\nretrievefromsql\nOn occasions where you want to execute arbitrary SQL, but don't want to go to the trouble of\nsetting up a constructor method, you can inline the entire WHERE clause, and just get the\nobjects back directly:\n\nmy @cds = Music::CD->retrievefromsql(qq{\nartist = 'Ozzy Osbourne' AND\ntitle like \"%Crazy\" AND\nyear <= 1986\nORDER BY year\nLIMIT 2,3\n});\n", "subsections": [ { "name": "Ima::DBI queries", "content": "When you can't use 'addconstructor', e.g. when using aggregate functions, you can fall back on\nthe fact that Class::DBI inherits from Ima::DBI and prefers to use its style of dealing with\nstatements, via setsql().\n\nThe Class::DBI setsql() method defaults to using preparecached() unless the $cache parameter\nis defined and false (see Ima::DBI docs for more information).\n\nTo assist with writing SQL that is inheritable into subclasses, several additional substitutions\nare available here: TABLE, ESSENTIAL and IDENTIFIER. These represent the table name\nassociated with the class, its essential columns, and the primary key of the current object, in\nthe case of an instance method on it.\n\nFor example, the SQL for the internal 'update' method is implemented as:\n\nPACKAGE->setsql('update', <<\"\");\nUPDATE TABLE\nSET %s\nWHERE IDENTIFIER\n\nThe 'longhand' version of the newmusic constructor shown above would similarly be:\n\nMusic::CD->setsql(newmusic => qq{\nSELECT ESSENTIAL\nFROM TABLE\nWHERE year > ?\n});\n\nFor such 'SELECT' queries Ima::DBI's setsql() method is extended to create a helper shortcut\nmethod, named by prefixing the name of the SQL fragment with 'search'. Thus, the above call to" }, { "name": "set_sql", "content": "this search and return the relevant objects or Iterator. (If there are placeholders in the\nquery, you must pass the relevant arguments when calling your search method.)\n\nThis does the equivalent of:\n\nsub searchnewmusic {\nmy ($class, @args) = @;\nmy $sth = $class->sqlnewmusic;\n$sth->execute(@args);\nreturn $class->sthtoobjects($sth);\n}\n\nThe $sth which is used to return the objects here is a normal DBI-style statement handle, so if\nthe results can't be turned into objects easily, it is still possible to call\n$sth->fetchrowarray etc and return whatever data you choose.\n\nOf course, any query can be added via setsql, including joins. So, to add a query that returns\nthe 10 Artists with the most CDs, you could write (with MySQL):\n\nMusic::Artist->setsql(mostcds => qq{\nSELECT artist.id, COUNT(cd.id) AS cds\nFROM artist, cd\nWHERE artist.id = cd.artist\nGROUP BY artist.id\nORDER BY cds DESC\nLIMIT 10\n});\n\nmy @artists = Music::Artist->searchmostcds();\n\nIf you also need to access the 'cds' value returned from this query, the best approach is to\ndeclare 'cds' to be a TEMP column. (See \"Non-Persistent Fields\" below).\n" }, { "name": "Class::DBI::AbstractSearch", "content": "my @music = Music::CD->searchwhere(\nartist => [ 'Ozzy', 'Kelly' ],\nstatus => { '!=', 'outdated' },\n);\n\nThe Class::DBI::AbstractSearch module, available from CPAN, is a plugin for Class::DBI that\nallows you to write arbitrarily complex searches using perl data structures, rather than SQL.\n" }, { "name": "Single Value SELECTs", "content": "selectval\nSelects which only return a single value can couple Class::DBI's sqlsingle() SQL, with the\n$sth->selectval() call which we get from DBIx::ContextualFetch.\n\nPACKAGE->setsql(countall => \"SELECT COUNT(*) FROM TABLE\");\n# .. then ..\nmy $count = $class->sqlcountall->selectval;\n\nThis can also take placeholders and/or do column interpolation if required:\n\nPACKAGE->setsql(countabove => q{\nSELECT COUNT(*) FROM TABLE WHERE %s > ?\n});\n# .. then ..\nmy $count = $class->sqlcountabove('year')->selectval(2001);\n\nsqlsingle\nInternally Class::DBI defines a very simple SQL fragment called 'single':\n\n\"SELECT %s FROM TABLE\".\n\nThis is used to implement the above Class->countall():\n\n$class->sqlsingle(\"COUNT(*)\")->selectval;\n\nThis interpolates the COUNT(*) into the %s of the SQL, and then executes the query, returning a\nsingle value.\n\nAny SQL set up via setsql() can of course be supplied here, and selectval can take arguments\nfor any placeholders there.\n\nInternally several helper methods are defined using this approach:\n\n- countall\n- maximumvalueof($column)\n- minimumvalueof($column)\n" } ] }, "LAZY POPULATION": { "content": "In the tradition of Perl, Class::DBI is lazy about how it loads your objects. Often, you find\nyourself using only a small number of the available columns and it would be a waste of memory to\nload all of them just to get at two, especially if you're dealing with large numbers of objects\nsimultaneously.\n\nYou should therefore group together your columns by typical usage, as fetching one value from a\ngroup can also pre-fetch all the others in that group for you, for more efficient access.\n\nSo for example, if we usually fetch the artist and title, but don't use the 'year' so much, then\nwe could say the following:\n\nMusic::CD->columns(Primary => qw/cdid/);\nMusic::CD->columns(Essential => qw/artist title/);\nMusic::CD->columns(Others => qw/year runlength/);\n\nNow when you fetch back a CD it will come pre-loaded with the 'cdid', 'artist' and 'title'\nfields. Fetching the 'year' will mean another visit to the database, but will bring back the\n'runlength' whilst it's there.\n\nThis can potentially increase performance.\n\nIf you don't like this behavior, then just add all your columns to the Essential group, and\nClass::DBI will load everything at once. If you have a single column primary key you can do this\nall in one shot with one single column declaration:\n\nMusic::CD->columns(Essential => qw/cdid artist title year runlength/);\n\ncolumns\nmy @allcolumns = $class->columns;\nmy @columns = $class->columns($group);\n\nmy @primary = $class->primarycolumns;\nmy $primary = $class->primarycolumn;\nmy @essential = $class->essential;\n\nThere are four 'reserved' groups: 'All', 'Essential', 'Primary' and 'TEMP'.\n\n'All' are all columns used by the class. If not set it will be created from all the other\ngroups.\n\n'Primary' is the primary key columns for this class. It *must* be set before objects can be\nused.\n\nIf 'All' is given but not 'Primary' it will assume the first column in 'All' is the primary key.\n\n'Essential' are the minimal set of columns needed to load and use the object. Only the columns\nin this group will be loaded when an object is retrieve()'d. It is typically used to save memory\non a class that has a lot of columns but where only use a few of them are commonly used. It will\nautomatically be set to 'Primary' if not explicitly set. The 'Primary' column is always part of\nthe 'Essential' group.\n\nFor simplicity primarycolumns(), primarycolumn(), and essential() methods are provided to\nreturn these. The primarycolumn() method should only be used for tables that have a single\nprimary key column.\n", "subsections": [ { "name": "Non-Persistent Fields", "content": "Music::CD->columns(TEMP => qw/nonpersistent/);\n\nIf you wish to have fields that act like columns in every other way, but that don't actually\nexist in the database (and thus will not persist), you can declare them as part of a column\ngroup of 'TEMP'.\n\nfindcolumn\nClass->findcolumn($column);\n$obj->findcolumn($column);\n\nThe columns of a class are stored as Class::DBI::Column objects. This method will return you the\nobject for the given column, if it exists. This is most useful either in a boolean context to\ndiscover if the column exists, or to 'normalize' a user-entered column name to an actual Column.\n\nThe interface of the Column object itself is still under development, so you shouldn't really\nrely on anything internal to it.\n" } ] }, "TRANSACTIONS": { "content": "Class::DBI suffers from the usual problems when dealing with transactions. In particular, you\nshould be very wary when committing your changes that you may actually be in a wider scope than\nexpected and that your caller may not be expecting you to commit.\n\nHowever, as long as you are aware of this, and try to keep the scope of your transactions small,\nideally always within the scope of a single method, you should be able to work with transactions\nwith few problems.\n\ndbicommit / dbirollback\n$obj->dbicommit();\n$obj->dbirollback();\n\nThese are thin aliases through to the DBI's commit() and rollback() commands to commit or\nrollback all changes to this object.\n", "subsections": [ { "name": "Localised Transactions", "content": "A nice idiom for turning on a transaction locally (with AutoCommit turned on globally) (courtesy\nof Dominic Mitchell) is:\n\nsub dotransaction {\nmy $class = shift;\nmy ( $code ) = @;\n# Turn off AutoCommit for this scope.\n# A commit will occur at the exit of this block automatically,\n# when the local AutoCommit goes out of scope.\nlocal $class->dbMain->{ AutoCommit };\n\n# Execute the required code inside the transaction.\neval { $code->() };\nif ( $@ ) {\nmy $commiterror = $@;\neval { $class->dbirollback }; # might also die!\ndie $commiterror;\n}\n}\n\nAnd then you just call:\n\nMusic::DBI->dotransaction( sub {\nmy $artist = Music::Artist->insert({ name => 'Pink Floyd' });\nmy $cd = $artist->addtocds({\ntitle => 'Dark Side Of The Moon',\nyear => 1974,\n});\n});\n\nNow either both will get added, or the entire transaction will be rolled back.\n" } ] }, "UNIQUENESS OF OBJECTS IN MEMORY": { "content": "Class::DBI supports uniqueness of objects in memory. In a given perl interpreter there will only\nbe one instance of any given object at one time. Many variables may reference that object, but\nthere can be only one.\n\nHere's an example to illustrate:\n\nmy $artist1 = Music::Artist->insert({ artistid => 7, name => 'Polysics' });\nmy $artist2 = Music::Artist->retrieve(7);\nmy $artist3 = Music::Artist->search( name => 'Polysics' )->first;\n\nNow $artist1, $artist2, and $artist3 all point to the same object. If you update a property on\none of them, all of them will reflect the update.\n\nThis is implemented using a simple object lookup index for all live objects in memory. It is not\na traditional cache - when your objects go out of scope, they will be destroyed normally, and a\nfuture retrieve will instantiate an entirely new object.\n\nThe ability to perform this magic for you replies on your perl having access to the\nScalar::Util::weaken function. Although this is part of the core perl distribution, some vendors\ndo not compile support for it. To find out if your perl has support for it, you can run this on\nthe command line:\n\nperl -e 'use Scalar::Util qw(weaken)'\n\nIf you get an error message about weak references not being implemented, Class::DBI will not\nmaintain this lookup index, but give you a separate instances for each retrieve.\n\nA few new tools are offered for adjusting the behavior of the object index. These are still\nsomewhat experimental and may change in a future release.\n\nremovefromobjectindex\n$artist->removefromobjectindex();\n\nThis is an object method for removing a single object from the live objects index. You can use\nthis if you want to have multiple distinct copies of the same object in memory.\n\nclearobjectindex\nMusic::DBI->clearobjectindex();\n\nYou can call this method on any class or instance of Class::DBI, but the effect is universal: it\nremoves all objects from the index.\n\npurgeobjectindexevery\nMusic::Artist->purgeobjectindexevery(2000);\n\nWeak references are not removed from the index when an object goes out of scope. This means that\nover time the index will grow in memory. This is really only an issue for long-running\nenvironments like modperl, but every so often dead references are cleaned out to prevent this.\nBy default, this happens every 1000 object loads, but you can change that default for your class\nby setting the 'purgeobjectindexevery' value.\n\n(Eventually this may handled in the DESTROY method instead.)\n\nAs a final note, keep in mind that you can still have multiple distinct copies of an object in\nmemory if you have multiple perl interpreters running. CGI, modperl, and many other common\nusage situations run multiple interpreters, meaning that each one of them may have an instance\nof an object representing the same data. However, this is no worse than it was before, and is\nentirely normal for database applications in multi-process environments.\n", "subsections": [] }, "SUBCLASSING": { "content": "The preferred method of interacting with Class::DBI is for you to write a subclass for your\ndatabase connection, with each table-class inheriting in turn from it.\n\nAs well as encapsulating the connection information in one place, this also allows you to\noverride default behaviour or add additional functionality across all of your classes.\n\nAs the innards of Class::DBI are still in flux, you must exercise extreme caution in overriding\nprivate methods of Class::DBI (those starting with an underscore), unless they are explicitly\nmentioned in this documentation as being safe to override. If you find yourself needing to do\nthis, then I would suggest that you ask on the mailing list about it, and we'll see if we can\neither come up with a better approach, or provide a new means to do whatever you need to do.\n", "subsections": [] }, "CAVEATS": { "content": "", "subsections": [ { "name": "Multi-Column Foreign Keys are not supported", "content": "You can't currently add a relationship keyed on multiple columns. You could, however, write a\nRelationship plugin to do this, and the world would be eternally grateful...\n" }, { "name": "Don't change or inflate the value of your primary columns", "content": "Altering your primary key column currently causes Bad Things to happen. I should really protect\nagainst this.\n" } ] }, "SUPPORTED DATABASES": { "content": "Theoretically Class::DBI should work with almost any standard RDBMS. Of course, in the real\nworld, we know that that's not true. It is known to work with MySQL, PostgreSQL, Oracle and\nSQLite, each of which have their own additional subclass on CPAN that you should explore if\nyou're using them:\n\nL, L, L,\nL\n\nFor the most part it's been reported to work with Sybase, although there are some issues with\nmulti-case column/table names. Beyond that lies The Great Unknown(tm). If you have access to\nother databases, please give this a test run, and let me know the results.\n\nIma::DBI (and hence Class::DBI) requires a database that supports table aliasing and a DBI\ndriver that supports placeholders. This means it won't work with older releases of DBD::AnyData\n(and any releases of its predecessor DBD::RAM), and DBD::Sybase + FreeTDS may or may not work\ndepending on your FreeTDS version.\n", "subsections": [] }, "CURRENT AUTHOR": { "content": "Tony Bowden\n", "subsections": [] }, "AUTHOR EMERITUS": { "content": "Michael G Schwern\n", "subsections": [] }, "THANKS TO": { "content": "Tim Bunce, Tatsuhiko Miyagawa, Perrin Harkins, Alexander Karelas, Barry Hoggard, Bart Lateur,\nBoris Mouzykantskii, Brad Bowman, Brian Parker, Casey West, Charles Bailey, Christopher L.\nEverett Damian Conway, Dan Thill, Dave Cash, David Jack Olrik, Dominic Mitchell, Drew Taylor,\nDrew Wilson, Jay Strauss, Jesse Sheidlower, Jonathan Swartz, Marty Pauley, Michael Styer, Mike\nLambert, Paul Makepeace, Phil Crow, Richard Piacentini, Simon Cozens, Simon Wilcox, Thomas\nKlausner, Tom Renfro, Uri Gutman, William McKee, the Class::DBI mailing list, the POOP group,\nand all the others who've helped, but that I've forgetten to mention.\n", "subsections": [] }, "RELEASE PHILOSOPHY": { "content": "Class::DBI now uses a three-level versioning system. This release, for example, is version\n3.0.17\n\nThe general approach to releases will be that users who like a degree of stability can hold off\non upgrades until the major sub-version increases (e.g. 3.1.0). Those who like living more on\nthe cutting edge can keep up to date with minor sub-version releases.\n\nFunctionality which was introduced during a minor sub-version release may disappear without\nwarning in a later minor sub-version release. I'll try to avoid doing this, and will aim to have\na deprecation cycle of at least a few minor sub-versions, but you should keep a close eye on the\nCHANGES file, and have good tests in place. (This is good advice generally, of course.) Anything\nthat is in a major sub-version release will go through a deprecation cycle of at least one\nfurther major sub-version before it is removed (and usually longer).\n", "subsections": [ { "name": "Getting changes accepted", "content": "There is an active Class::DBI community, however I am not part of it. I am not on the mailing\nlist, and I don't follow the wiki. I also do not follow Perl Monks or CPAN reviews or annoCPAN\nor whatever the tool du jour happens to be.\n\nIf you find a problem with Class::DBI, by all means discuss it in any of these places, but don't\nexpect anything to happen unless you actually tell me about it.\n\nThe preferred method for doing this is via the CPAN RT interface, which you can access at\nhttp://rt.cpan.org/ or by emailing bugs-Class-DBI@rt.cpan.org\n\nIf you email me personally about Class::DBI issues, then I will probably bounce them on to\nthere, unless you specifically ask me not to. Otherwise I can't keep track of what all needs\nfixed. (This of course means that if you ask me not to send your mail to RT, there's a much\nhigher chance that nothing will every happen about your problem).\n" }, { "name": "Bug Reports", "content": "If you're reporting a bug then it has a much higher chance of getting fixed quicker if you can\ninclude a failing test case. This should be a completely stand-alone test that could be added to\nthe Class::DBI distribution. That is, it should use Test::Simple or Test::More, fail with the\ncurrent code, but pass when I fix the problem. If it needs to have a working database to show\nthe problem, then this should preferably use SQLite, and come with all the code to set this up.\nThe nice people on the mailing list will probably help you out if you need assistance putting\nthis together.\n\nYou don't need to include code for actually fixing the problem, but of course it's often nice if\nyou can. I may choose to fix it in a different way, however, so it's often better to ask first\nwhether I'd like a patch, particularly before spending a lot of time hacking.\n" }, { "name": "Patches", "content": "If you are sending patches, then please send either the entire code that is being changed or the\noutput of 'diff -Bub'. Please also note what version the patch is against. I tend to apply all\npatches manually, so I'm more interested in being able to see what you're doing than in being\nable to apply the patch cleanly. Code formatting isn't an issue, as I automagically run perltidy\nagainst the source after any changes, so please format for clarity.\n\nPatches have a much better chance of being applied if they are small. People often think that\nit's better for me to get one patch with a bunch of fixes. It's not. I'd much rather get 100\nsmall patches that can be applied one by one. A change that I can make and release in five\nminutes is always better than one that needs a couple of hours to ponder and work through.\n\nI often reject patches that I don't like. Please don't take it personally. I also like time to\nthink about the wider implications of changes. Often a *lot* of time. Feel free to remind me\nabout things that I may have forgotten about, but as long as they're on rt.cpan.org I will get\naround to them eventually.\n" }, { "name": "Feature Requests", "content": "Wish-list requests are fine, although you should probably discuss them on the mailing list (or\nequivalent) with others first. There's quite often a plugin somewhere that already does what you\nwant.\n\nIn general I am much more open to discussion on how best to provide the flexibility for you to\nmake your Cool New Feature(tm) a plugin rather than adding it to Class::DBI itself.\n\nFor the most part the core of Class::DBI already has most of the functionality that I believe it\nwill ever need (and some more besides, that will probably be split off at some point). Most\nother things are much better off as plugins, with a separate life on CPAN or elsewhere (and with\nme nowhere near the critical path). Most of the ongoing work on Class::DBI is about making life\neasier for people to write extensions - whether they're local to your own codebase or released\nfor wider consumption.\n" } ] }, "SUPPORT": { "content": "Support for Class::DBI is mostly via the mailing list.\n\nTo join the list, or read the archives, visit\nhttp://lists.digitalcraftsmen.net/mailman/listinfo/classdbi\n\nThere is also a Class::DBI wiki at http://www.class-dbi.com/\n\nThe wiki contains much information that should probably be in these docs but isn't yet. (See\nabove if you want to help to rectify this.)\n\nAs mentioned above, I don't follow the list or the wiki, so if you want to contact me\nindividually, then you'll have to track me down personally.\n\nThere are lots of 3rd party subclasses and plugins available. For a list of the ones on CPAN\nsee: http://search.cpan.org/search?query=Class%3A%3ADBI&mode=module\n\nAn article on Class::DBI was published on Perl.com a while ago. It's slightly out of date , but\nit's a good introduction: http://www.perl.com/pub/a/2002/11/27/classdbi.html\n\nThe wiki has numerous references to other articles, presentations etc.\n\nhttp://poop.sourceforge.net/ provides a document comparing a variety of different approaches to\ndatabase persistence, such as Class::DBI, Alazabo, Tangram, SPOPS etc.\n", "subsections": [] }, "LICENSE": { "content": "This library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n", "subsections": [] }, "SEE ALSO": { "content": "Class::DBI is built on top of Ima::DBI, DBIx::ContextualFetch, Class::Accessor and\nClass::Data::Inheritable. The innards and much of the interface are easier to understand if you\nhave an idea of how they all work as well.\n", "subsections": [] } } } }