Topics
Text configuration
Newt DB provides a Python API for creating database connections. You can also use the ZODB text configuration API. Text configuration is usually the easiest way to configure a database, especially when you need non default options.
An example
Configuration strings can be included in configuration files by themselves or as parts of larger configurations. Here is 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>How the syntax works
The syntax 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 behaviour.
The newtdb element
The newtdb element 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.
The newt element
The newt element wraps a RelStorage postgresql element to provide a Newt PostgreSQL adapter that stores JSON data in addition to normal database data.
An optional transformation option may be provided to supply a data transformation function. The data transformation topic shows the option in context.
History free or history preserving
A keep-history option is used to request history free storage. History free storage only keeps current data and discards transaction metadata. History preserving storage keeps past data records until they are packed away and allows time travel to view data in the past. History preserving storage is much slower and requires more maintenance.
Newt DB works with either history free or history preserving storage, but history free storage is recommended and is the default for the Python API.
Required import. The %import newt.db directive loads the configuration schema for Newt DB. Without it the newtdb and newt elements are unknown.
Where the other options live
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.
The ZConfig documentation describes the underlying configuration language, including how values are typed and how larger files are assembled.