Contents
Guide: Constraints
Overview
By default, BedquiltDB collections do not enforce any schema on the documents
they contain. The only demand BedquiltDB makes of a document is that it have a _id
field. While this looseness is useful, most of the time we have a good idea of the
"shape" of our data and would like to enforce at least some kind of schema.
BedquiltDB allows you to add constraints to a collection. Once the constraint is in place, any documents written to the collection are checked against the constraints to see if they are valid. If the data fits the constraints, the data is written as normal, otherwise an error is raised.
Adding Constraints to Collections
Constraints are added to a collection with the add_constraints operation.
A constraint specifies the field to be constrained, and in what ways the field should
be validated. Let's look at an example (in python):
python
db = pybedquilt.BedquiltClient(dbname='test')
db['users'].add_constraint({
'email': {
'$required': True,
'$notnull': True,
'$type': 'string'
},
'password_hash': {
'$required': True,
'$notnull': True,
'$type': 'string'
},
'name': {
'$required': True,
'$type': 'string'
},
'loginCount': {
'$type': 'number'
}
})
The only parameter to add_constraints operation is a json document specifying the
constraints to be added. The keys of the spec document are the fields to be
constrained, and the values are json objects describing the kind of validation
operations to be applied to that field.
There are three validations which can be applied, in any combination, to a field:
| Constraint | Effect |
|-------------------|--------------------------------------------------|
| $required | The field must be present in the document. |
| $notnull | If the field is present, it must not be null |
| $type | If the field is present, it must be of this type |
Both $required and $notnull accept boolean values, indicating that the constraint
should be enforced. Silly constraints such as {'$required': False} and
{'$notnull': False} are simply ignored.
The $type constraint accepts a string value describing the data-type that should
be enforced. Valid types are "string"', "number", "object",
"array", and "boolean".
The add_constraints operation is idempotent. If you add the same constraint twice,
the second operation simply does nothing. add_constraints returns a boolean value indicating whether any new constraints were applied to the collection.
Listing Constraints on a Collection
The list_constraints operation returns a list of strings describing the constraints
that are currently in effect on a collection. Example:
```python print db['users'].list_constraints()
=> ['email:required', 'email:notnull', 'email:type:string', ...]
```
This should only be used for database administration, as the format of the
data returned from list_collections is subject to change in future versions
of BedquiltDB.
Removing Constraints
To remove constraints from a collection, use the remove_constraints operation,
passing it the same constraint spec document that was used to create the constraints.
For example, to remove the constraints on the name field we added earlier,
we could do the following:
python
db['users'].remove_constraints({
'name': {
'$required': True,
'$type': 'string'
}
})
Just like add_constraints, remove_constraints is idempotent. If a constraint
does not already exist, then remove_constraints just does nothing.
The remove_constraints operation returns a boolean to indicate whether any of the
specified constraints were actually removed.