Wt: Database Objects (Wt::Dbo)

Wt 4.10.4

Loading...
Searching...
No Matches
Namespaces | Classes | Enumerations | Functions | Variables
Database Objects (Wt::Dbo)

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

## Namespaces
namespace | Wt::Dbo::backend
| Namespace for Dbo backends.

## 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.
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())
| 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)
| 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)
| 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|OnDeleteCascade))
| 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::OnUpdateRestrict
| A constraint that restricts updates.
const ForeignKeyConstraint | Wt::Dbo::OnDeleteCascade
| A constraint that cascades deletes.
const ForeignKeyConstraint | Wt::Dbo::OnDeleteSetNull
| A constraint that cascades deletes.
const ForeignKeyConstraint | Wt::Dbo::OnDeleteRestrict
| A constraint that restricts deletes.

## 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
Wt::Dbo::field
void field(Action &action, V &value, const std::string &name, int size=-1)
Maps a database object field.
Wt
The namespace for Wt.
Definition strand.hpp:29

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.