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...
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::MSSQLServer
	A Microsoft SQL Server 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::JsonSerializer
	An action to serialize objects to JSON. 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::AbstractQuery
	An abstract dynamic database query. 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. More...
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. More...
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. More...
template<class Action , class C >
void	Wt::Dbo::belongsTo (Action &action, ptr< C > &value, const std::string &name=std::string())
	Maps the "One"-side (foreign key) of a ManyToOne or OneToOne relation. More...
template<class Action , class C >
void	Wt::Dbo::belongsTo (Action &action, ptr< C > &value, const std::string &name, ForeignKeyConstraint constraints)
	Maps the "One"-side (foreign key) of a ManyToOne or OneToOne relation. More...
template<class Action , class C >
void	Wt::Dbo::belongsTo (Action &action, ptr< C > &value, ForeignKeyConstraint constraints)
	Maps the "One"-side (foreign key) of a ManyToOne or OneToOne relation. More...
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. More...
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. More...
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|OnDeleteCascade))
	Maps the "Many"-side of a ManyToMany relation. More...

Variables
const ForeignKeyConstraint	Wt::Dbo::NotNull
	A constraint that prevents a null ptr. More...
const ForeignKeyConstraint	Wt::Dbo::OnUpdateCascade
	A constraint that cascades updates. More...
const ForeignKeyConstraint	Wt::Dbo::OnUpdateSetNull
	A constraint that cascades updates. More...
const ForeignKeyConstraint	Wt::Dbo::OnUpdateRestrict
	A constraint that restricts updates. More...
const ForeignKeyConstraint	Wt::Dbo::OnDeleteCascade
	A constraint that cascades deletes. More...
const ForeignKeyConstraint	Wt::Dbo::OnDeleteSetNull
	A constraint that cascades deletes. More...
const ForeignKeyConstraint	Wt::Dbo::OnDeleteRestrict
	A constraint that restricts deletes. More...

Detailed Description

An implemenation of an Object Relational Mapping layer.

For an introduction, see the tutorial.

Enumeration Type Documentation

RelationType

enum Wt::Dbo::RelationType

Type of an SQL relation.

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

Function Documentation

belongsTo() [1/3]

template<class Action , class C >

void Wt::Dbo::belongsTo	(	Action &	action,
		ptr< C > &	value,
		const std::string &	name,
		ForeignKeyConstraint	constraints
	)

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()

belongsTo() [2/3]

template<class Action , class C >

void Wt::Dbo::belongsTo	(	Action &	action,
		ptr< C > &	value,
		const std::string &	name = std::string()
	)

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 starts with a >, the > is omitted and the name is used literally, instead of name + "_" + (C's primary key(s)), e.g. if the primary key of C is id, then the name foo translates to a column with the name foo_id, and the name >foo translates to a column with the name foo.

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()

belongsTo() [3/3]

template<class Action , class C >

void Wt::Dbo::belongsTo	(	Action &	action,
		ptr< C > &	value,
		ForeignKeyConstraint	constraints
	)

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()

field()

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.

hasMany() [1/2]

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|OnDeleteCascade)
	)

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, e.g. if joinId is foo and the primary key is id, then this side of the join table will be named foo_id. If joinId is left blank, the value will be table name + "_" + (primary key(s)) of the current class. If joinId starts with >, the > is omitted, and the joinId is used literally (the primary key of the current class is not appended), e.g. >foo maps to the column name foo.

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

See also

belongsTo()

hasMany() [2/2]

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()

hasOne()

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. If the name starts with >, the > is discarded, and the name is used literally, instead of name + "_" + (C's primary key(s)).

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

See also

belongsTo()

id() [1/2]

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()

id() [2/2]

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().

Variable Documentation

NotNull

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.

OnDeleteCascade

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.

OnDeleteRestrict

const ForeignKeyConstraint Wt::Dbo::OnDeleteRestrict

A constraint that restricts deletes.

A database constraint which restricts deletes of the referenced object to also restrict deletion of the objects that reference.

Note

This constraint only affects the database schema creation.

OnDeleteSetNull

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.

OnUpdateCascade

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.

OnUpdateRestrict

const ForeignKeyConstraint Wt::Dbo::OnUpdateRestrict

A constraint that restricts updates.

A database constraint which restricts 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.

OnUpdateSetNull

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.