Wt: Database Objects (Wt::Dbo)

Wt 3.3.0

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

Classes | Enumerations | Functions | Variables
Database Objects (Wt::Dbo)

An implemenation of an Object Relational Mapping layer. More...

## Classes
class | Wt::Dbo::ForeignKeyConstraint
| Type that indicates one or more foreign key constraints. More...
struct | Wt::Dbo::ptr_tuple< T0, T1,, T9 >
| A utility class for defining a tuple of database objects. More...
class | Wt::Dbo::SqlStatement
| Abstract base class for a prepared SQL statement. More...
class | Wt::Dbo::backend::Firebird
| A Firebird connection. More...
class | Wt::Dbo::backend::MySQL
| A MySQL connection. More...
class | Wt::Dbo::backend::Postgres
| A PostgreSQL connection. More...
class | Wt::Dbo::backend::Sqlite3
| An SQLite3 connection. More...
class | Wt::Dbo::collection< C >
| An STL container for iterating query results. More...
class | Wt::Dbo::Exception
| Exception base class for Wt::Dbo. More...
class | Wt::Dbo::StaleObjectException
| Exception thrown when Wt::Dbo detects a concurrent modification More...
class | Wt::Dbo::ObjectNotFoundException
| Exception thrown when trying to load a non-existing object. More...
class | Wt::Dbo::NoUniqueResultException
| Exception thrown when a query unexpectedly finds a non-unique result. More...
class | Wt::Dbo::FixedSqlConnectionPool
| A connection pool of fixed size. More...
class | Wt::Dbo::dbo_default_traits
| Default traits for a class mapped with Wt::Dbo. More...
class | Wt::Dbo::dbo_traits< C >
| Traits for a class mapped with Wt::Dbo. More...
class | Wt::Dbo::Dbo< C >
| A base class for database objects. More...
class | Wt::Dbo::ptr< C >
| A smart pointer for a database object. More...
class | Wt::Dbo::Query< Result, BindStrategy >
| A database query. More...
class | Wt::Dbo::QueryModel< Result >
| A Wt MVC Model to view/edit query results. More...
class | Wt::Dbo::Session
| A database session. More...
class | Wt::Dbo::SqlConnection
| Abstract base class for an SQL connection. More...
class | Wt::Dbo::SqlConnectionPool
| Abstract base class for a SQL connection pool. More...
class | Wt::Dbo::sql_value_traits< V, Enable >
| Traits class for value types. More...
class | Wt::Dbo::FieldInfo
| Description of a field. More...
class | Wt::Dbo::query_result_traits< Result >
| Traits class for result types. More...
class | Wt::Dbo::Transaction
| A database transaction. More...
class | Wt::Dbo::weak_ptr< C >
| A weak pointer for a database object. More...
## Enumerations
enum | Wt::Dbo::RelationType { Wt::Dbo::ManyToOne, Wt::Dbo::ManyToMany }
| Type of an SQL relation. More...
## Functions
ForeignKeyConstraint | Wt::Dbo::operator| (ForeignKeyConstraint lhs, ForeignKeyConstraint rhs)
| Combines two constraints.
template<class Action , typename V >
void | Wt::Dbo::id (Action &action, V &value, const std::string &name="id", int size=-1)
| Maps a natural primary key (id) field.
template<class Action , class C >
void | Wt::Dbo::id (Action &action, ptr< C > &value, const std::string &name, ForeignKeyConstraint constraints, int size=-1)
| Maps a natural primary key (id) field that is a foreign key.
template<class Action , typename V >
void | Wt::Dbo::field (Action &action, V &value, const std::string &name, int size=-1)
| Maps a database object field.
template<class Action , class C >
void | Wt::Dbo::belongsTo (Action &action, ptr< C > &value, const std::string &name=std::string(), int size=-1)
| Maps the "One"-side (foreign key) of a ManyToOne or OneToOne relation.
template<class Action , class C >
void | Wt::Dbo::belongsTo (Action &action, ptr< C > &value, const std::string &name, ForeignKeyConstraint constraints, int size=-1)
| Maps the "One"-side (foreign key) of a ManyToOne or OneToOne relation.
template<class Action , class C >
void | Wt::Dbo::belongsTo (Action &action, ptr< C > &value, ForeignKeyConstraint constraints, int size=-1)
| Maps the "One"-side (foreign key) of a ManyToOne or OneToOne relation.
template<class Action , class C >
void | Wt::Dbo::hasOne (Action &action, weak_ptr< C > &value, const std::string &name=std::string())
| Maps the "One"-side of a OneToOne relation.
template<class Action , class C >
void | Wt::Dbo::hasMany (Action &action, collection< ptr< C > > &value, RelationType type, const std::string &name=std::string())
| Maps the "Many"-side of a ManyToOne or ManyToMany relation.
template<class Action , class C >
void | Wt::Dbo::hasMany (Action &action, collection< ptr< C > > &value, RelationType type, const std::string &name, const std::string &joinId, ForeignKeyConstraint constraints=NotNull)
| Maps the "Many"-side of a ManyToMany relation.
## Variables
const ForeignKeyConstraint | Wt::Dbo::NotNull
| A constraint that prevents a `null` ptr.
const ForeignKeyConstraint | Wt::Dbo::OnUpdateCascade
| A constraint that cascades updates.
const ForeignKeyConstraint | Wt::Dbo::OnUpdateSetNull
| A constraint that cascades updates.
const ForeignKeyConstraint | Wt::Dbo::OnDeleteCascade
| A constraint that cascades deletes.
const ForeignKeyConstraint | Wt::Dbo::OnDeleteSetNull
| A constraint that cascades deletes.

## Detailed Description

An implemenation of an Object Relational Mapping layer.

For an introduction, see the tutorial.

## Enumeration Type Documentation

enum Wt::Dbo::RelationType

Type of an SQL relation.

Enumerator:

  ManyToOne | Many-to-One relationship.
  ManyToMany | Many-to-Many relationship.

## Function Documentation

template<class Action , class C >

void Wt::Dbo::belongsTo | ( | Action & | action,
|  | ptr< C > & | value,
|  | const std::string & | name = `std::string()`,
|  | int | size = `-1`
| ) |  |

Maps the "One"-side (foreign key) of a ManyToOne or OneToOne relation.

This function binds the pointer field `value` to the database foreign key field(s) `name` `+ "_" +` (C's primary key(s)).

If the name is omitted or empty, then C's mapped table name is used.

A belongsTo() will usually have a counter-part hasMany() or hasOne() declaration in the referenced class `C`.

See also:
  hasMany()

template<class Action , class C >

void Wt::Dbo::belongsTo | ( | Action & | action,
|  | ptr< C > & | value,
|  | const std::string & | name,
|  | ForeignKeyConstraint | constraints,
|  | int | size = `-1`
| ) |  |

Maps the "One"-side (foreign key) of a ManyToOne or OneToOne relation.

This overloaded method allows to specify constraints for the foreign key.

See also:
  hasMany()

template<class Action , class C >

void Wt::Dbo::belongsTo | ( | Action & | action,
|  | ptr< C > & | value,
|  | ForeignKeyConstraint | constraints,
|  | int | size = `-1`
| ) |  |

Maps the "One"-side (foreign key) of a ManyToOne or OneToOne relation.

This overloaded method allows to specify constraints for the foreign key.

See also:
  hasMany()

template<class Action , typename V >

void Wt::Dbo::field | ( | Action & | action,
|  | V & | value,
|  | const std::string & | name,
|  | int | size = `-1`
| ) |  |

Maps a database object field.

This function binds the field `value` to the database field `name`.

The optional `size` may be used as a hint for the needed storage. It is only useful for std::string or Wt::WString fields, and causes the schema to use a `varchar(``size``)` for storing the field instead of an unlimited length string type.

You may want to specialize this method for a particular composite type which should be persisted in multiple database fields but not as a separate table (e.g. for natural composite primary keys, see id()).

For example:

     struct Coordinate {
       int x, y;
     };

     namespace Wt {
       namespace Dbo {

         template <class Action>
         void field(Action& action, Coordinate& coordinate, const std::string& name, int size = -1)
         {
           field(action, coordinate.x, name + "_x");
           field(action, coordinate.y, name + "_y");
         }

       } // namespace Dbo
     } // namespace Wt

To support a custom type that needs to be persisted as a single field, you should specialize sql_value_traits instead.

template<class Action , class C >

void Wt::Dbo::hasMany | ( | Action & | action,
|  | collection< ptr< C > > & | value,
|  | RelationType | type,
|  | const std::string & | name = `std::string()`
| ) |  |

Maps the "Many"-side of a ManyToOne or ManyToMany relation.

This function binds the collection field `value` to contain objects (of type `C`) that holds the associated objects: reading from the collection and adding or removing objects from the collection results in SQL statements.

For a ManyToOne relation, the query is defined by the database field(s) `name` `+ "_" +` (C's primary key(s)), in the mapped table for C. This should be the same name as passed to the matching belongsTo() method for the other side of the relation. If the `name` is omitted or empty, then the mapped table name of the current class is used.

For a ManyToMany relation, the `name` is the name of a linker table (this linker table may be schema qualified, e.g. `"myschema.posts_tags"`. Thus, also for a ManyToMany relation, both sides of the relationship will have the same `name` passed to them. In the join table, this side of the the relation will be referenced using the table name `+ "_" +` (primary key(s)) of the current class.

A hasMany() must have a counter-part belongsTo() or hasMany() declaration in the referenced class `C`.

See also:
  belongsTo()

template<class Action , class C >

void Wt::Dbo::hasMany | ( | Action & | action,
|  | collection< ptr< C > > & | value,
|  | RelationType | type,
|  | const std::string & | name,
|  | const std::string & | joinId,
|  | ForeignKeyConstraint | constraints = `NotNull`
| ) |  |

Maps the "Many"-side of a ManyToMany relation.

This function binds the collection field `value` to contain objects (of type `C`).

This overloaded method allows to customize the field name of the foreign id in the join table, and specify constraints for this foreign key. The only allowed value for `type` is ManyToMany.

The `joinId` is used to reference this side of the relationship in the join table. If `joinId` is left blank, the value will be table name `+ "_" +` (primary key(s)) of the current class.

A hasMany() must have a counter-part belongsTo() or hasMany() declaration in the referenced class `C`.

See also:
  belongsTo()

template<class Action , class C >

void Wt::Dbo::hasOne | ( | Action & | action,
|  | weak_ptr< C > & | value,
|  | const std::string & | name = `std::string()`
| ) |  |

Maps the "One"-side of a OneToOne relation.

This function binds the weak_ptr field `value` to the associated object (of type `C`).

A weak_ptr is required here to break the cycle that would otherwise be created by the hasOne() and belongsTo() associations. The value is not actually stored but defined in terms of a SQL query (not that different from how a hasMany() call backs a collection by a SQL query).

The query is defined by the database field(s) `name` `+ "_" +` (C's primary key(s)), in the mapped table for C. This should be the same name as passed to the matching belongsTo() method for the other side of the relation. If the `name` is omitted or empty, then the mapped table name of the current class is used.

A hasOne() must have a counter-part belongsTo() declaration in the referenced class `C`.

See also:
  belongsTo()

template<class Action , typename V >

void Wt::Dbo::id | ( | Action & | action,
|  | V & | value,
|  | const std::string & | name = `"id"`,
|  | int | size = `-1`
| ) |  |

Maps a natural primary key (id) field.

A natural primary key field is optional. If you define one and its type is not `long long`, you must specialize Wt::Dbo::dbo_traits to match the type `V` as the IdType for this class. When not specified for a class, an auto-generated surrogate key field is used with the name specified by Wt::Dbo::dbo_traits::surrogateIdField(), which defaults to "id".

Unlike the default surrogate key, a natural id is not auto-generated and thus you need to give each object a unique value when creating a new object.

The id may be a composite type. In that case, you need to specialize Wt::Dbo::field().

template<class Action , class C >

void Wt::Dbo::id | ( | Action & | action,
|  | ptr< C > & | value,
|  | const std::string & | name,
|  | ForeignKeyConstraint | constraints,
|  | int | size = `-1`
| ) |  |

Maps a natural primary key (id) field that is a foreign key.

This overloaded method allows to specify constraints for the foreign key.

See also:
  hasMany()

## Variable Documentation

const ForeignKeyConstraint Wt::Dbo::NotNull

A constraint that prevents a `null` ptr.

A database constraint which prevents that a ptr references no object and has a value of `null`.

const ForeignKeyConstraint Wt::Dbo::OnDeleteCascade

A constraint that cascades deletes.

A database constraint which propagates deletes of the referenced object to also delete the object(s) that reference it.

Note:
  This constraint only affects the database schema creation.

const ForeignKeyConstraint Wt::Dbo::OnDeleteSetNull

A constraint that cascades deletes.

A database constraint which propagates deletes of the referenced object to also delete the objects that reference.

Note:
  This constraint only affects the database schema creation.

const ForeignKeyConstraint Wt::Dbo::OnUpdateCascade

A constraint that cascades updates.

A database constraint which propagates updates to the natural primary key in the referenced table.

Note:
  This constraint only affects the database schema creation. Currently it is not possible to update a natural Id of an already saved object through Dbo itself.

const ForeignKeyConstraint Wt::Dbo::OnUpdateSetNull

A constraint that cascades updates.

A database constraint which sets the value of the ptr to null when the referenced primary key changes.

Note:
  This constraint only affects the database schema creation. Currently it is not possible to update a natural Id of an already saved object through Dbo itself.

All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator