Text Configuration¶
Newt DB provides a Python API for creating database connections. You can also use ZODB’s text configuration API. Text configuration usually provides the easiest way to configure a database, especially if you need to provide non-default options. Configuration strings can be included in configuration files by themselves or as parts of larger configurations.
Here’s an example text configuration for Newt DB:
%import newt.db
<newtdb>
<zodb>
<relstorage>
keep-history false
<newt>
<postgresql>
dsn dbname=''
</postgresql>
</newt>
</relstorage>
</zodb>
</newtdb>
The syntax used is based on the syntax used by web servers such as Apache. Elements, in angle brackets identify configuration objects with name-value pairs inside elements to specify options. Optional indentation indicates containment relationships and element start and end tags must appear on their own lines.
Newt DB provides two configuration elements: newtdb
and newt
.
These elements augment existing elements to provide extra behavior.
- newt
Wraps a RelStorage
postgresql
element to provide a Newt Postgres database adapter that stores JSON data in addition to normal database data.An optional
transformation
option may be provided to provide a data-transformation function. See the Data transformation topic.- newtdb
- Wraps a
zodb
element to provide a Newt database rather than a normal ZODB database. The Newt database provides extra APIs for searching and transaction management.
Some things to note:
- An
%import
directive is used to load the configuration schema for Newt DB. - A
keep-history
option is used to request a history-free storage. History-free storages only keep current data and discard transaction meta data. History-preserving storages keep past data records until they are packed away and allow “time-travel” to view data in the past. History-preserving storages are much slower and require more maintenance. Newt DB works with either history-preserving or history-free storages, but history-free storages are recommended and are the default for the Python API.
The RelStorage documentation provides information on the options for the relstorage element and for the postgresql element.
The ZODB documentation provides information on the options for the zodb element.