This method overrides the default Moose::Object constructor in order to implement cache management.

By default, object caching is disabled. In that case, this method lets its parent class do most of the work. However, unlike the standard Moose constructor, this method may sometimes not return an object. If it attempts to load object data from the DBMS and cannot find anything matching the parameters given to the constructor, it will return false.

If the constructor fails, you can check the value of $class->ConstructorError for the error message. This is done so that calling the constructor does not overwrite any value already in $@.

If caching is enabled, then this method will attempt to find a matching object in the cache. A match is determined by looking for an object which has a candidate key with the same values as are passed to the constructor.

If no match is found, it attempts to create a new object. If this succeeds, it stores it in the cache before returning it.

The constructor accepts any attribute of the class as a parameter. This includes any column-based attributes, as well as any additional attributes defined by has_one() or has_many(). Of course, if you disabled caching for has_one() or has_many() relationships, then they are implemented as simple methods, not attributes.

If you define additional methods via Moose's has() function, and these will be accepted by the constructor as well.

Finally, the constructor accepts a parameter _from_query. This tells the constructor that the parameters passed to the constructor are the result of a SELECT. This stops the BUILD() method from attempting to load the object from the DBMS. However, you still must pass values for the primary key, so that the object is identifiable in the DBMS.

If the constructor does not return an object, this will always contain the error message from the constructor. This should always be something like "Could not a find a row in SomeTable matching the values you provided to the constructor" or "Could not find a row in SomeTable where table_id = 42".

This method allows you to insert multiple rows efficiently. It expects an array of hash references. Each hash reference should contain the same set of column names as its keys. The advantage of using this method is that under the hood it uses the same DBI statement handle repeatedly. If you were to call $class->insert() repeatedly it would have to recreate the same SQL and DBI statement handle repeatedly.

In scalar context, it returns the first object created. In list context, it returns all the objects created.

This method accepts a hash of column keys and values, just like $class->insert(). However, it instead updates the values for an existing object's row. It will also make sure that the object's attributes are updated properly. In some cases, it will just clear the attribute, forcing it to be reloaded the next time it is accessed. This is necessary when the update value was a Fey::Literal, since that could be a function that gets interpreted by the DBMS, such as NOW().

Returns a hash representing the names and values for the object's primary key. The values are returned in their raw form, regardless of any transforms specific for a primary key column.

This may return an empty hash if the primary key for the object has not yet been determined. This can happen if you try to call this method on an object before its attributes have been fetched from the dbms.

Returns a list of values for the object's primary key. The values are returned in the same order as $self->primary_key() returns the columns. The values are returned in their raw form, regardless of any transforms specific for a primary key column.

This may return an empty list if the primary key for the object has not yet been determined.

Since your table-based class will be a subclass of this object, there are several methods you may want to use that are not intended for use outside of your subclasses. You may also want to subclass some of these methods in this class.

Given a Fey::SQL object, this method returns an appropriate DBI object for that SQL. Internally, it calls source_for_sql() on the schema class's Fey::DBIManager object and then calls $source->dbh() on the source.

This method will be called as part of object construction (unless _from_query was true).

By default, this method attempts to find a row in the associated table by looking at each of the table's candidate keys in turn. If the parameters passed to the constructor include values for all parts of a key, it does a select to find a matching row.

You can override this method in order to attempt to load an object based on some other method. For example, if your user table stores a username and a hashed password, you could accept an unhashed password, and then do a lookup based on the hashed value.

This method is expected to create a SELECT statement and then pass the statement and bind parameters to $object->_get_column_values().

On success, this method should simply return. If it fails, it should throw a Fey::Exception::NoSuchRow exception. See Fey::ORM::Exceptions for details.

This method takes a SELECT statement and an array reference of bind parameters. The SELECT is expected to find a single row, which should correspond to the current object. If it finds a row, it sets the corresponding attributes in the object based on the values returns by the SELECT.