Hi, As promised, I send the converted dbapp-policy documentation to this bug. Credits go to Osamu, any bug is mine. Paul
<?xml version='1.0' encoding='utf-8'?>
<!-- -*- DocBook -*- -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [
<!-- Include entity definition file by uncommenting the following -->
<!-- <!ENTITY % versiondata SYSTEM "version.ent"> %versiondata; -->
]>
<book lang="en">
<title>Best practices for packaging database applications</title>
<bookinfo>
<authorgroup>
<author><personname>Sean Finney</personname></author>
</authorgroup>
<releaseinfo></releaseinfo>
<pubdate><!-- put date --></pubdate>
<abstract>
<para>
This draft describes a set of guidelines and best practices to be implemented
by the maintainers of database application packages. Pending a final draft,
desire, and acceptance by the developer community at large, this may serve as
the foundation for an official policy--or it may simply remain as it is.
</para>
</abstract>
<copyright><year>2005</year><holder>sean finney seanius@debian.org</holder></copyright>
<legalnotice>
<para>
This document is licensed under the <ulink
url="https://spdx.org/licenses/AFL-2.1.html";>Academic Free License, Version
2.1</ulink>
</para>
</legalnotice>
</bookinfo>
<chapter id="dbapps"><title>Database Applications</title>
<section id="scope"><title>Scope</title>
<para>
In this document a "database application" is any program that relies on some
form of data storage outside the scope of the program's execution. This is
primarily intended to encompass applications which rely on a relational
database server or their own persistent storage mechanism, though effectively
is a much larger set of applications. In the future this scope may have to be
narrowed to avoid ambiguity and be more effective as a policy.
</para>
</section>
<section id="terminology"><title>Terminology</title>
<para>
For the purposes of this document, there are two types of databases:
<emphasis>persistent</emphasis> and <emphasis>cached</emphasis>.
</para>
<para>
<emphasis>Persistent</emphasis> databases contain data that can not be entirely
reconstituted in the case that the database is removed. Also included are
databases that if removed would cause serious denial of service (making a
system unstable/unusable) or security concerns. Applications using this
category of databases are the primary focus of this document. Examples:
</para>
<itemizedlist>
<listitem>
<para>
relational database servers providing storage to other applications.
</para>
</listitem>
<listitem>
<para>
web applications using a relational database
</para>
</listitem>
<listitem>
<para>
openldap's slapd databases
</para>
</listitem>
<listitem>
<para>
rrd files containing accumulated/historical data.
</para>
</listitem>
</itemizedlist>
<para>
<emphasis>Cached</emphasis> databases are a specific group of databases which
upon their removal could be sufficiently regenerated, and could be removed
without causing serious denial of service or security concerns. Examples
include:
</para>
<itemizedlist>
<listitem>
<para>
debconf responses
</para>
</listitem>
<listitem>
<para>
locate database
</para>
</listitem>
<listitem>
<para>
caching nameserver data
</para>
</listitem>
<listitem>
<para>
apt's list of available packages
</para>
</listitem>
</itemizedlist>
</section>
<section id="placement"><title>Placement of databases</title>
<para>
Both persistent and cached databases fall under already defined guidelines in
the FHS; persistent data must be placed under
<filename>/var/lib/packagename</filename>, and cached data under
<filename>/var/cache/packagename</filename>, respectively <footnote><para> or
an equivalently compliant location </para> </footnote>. The remainder of this
document primarily addresses the former.
</para>
</section>
<section id="installationissues"><title>Installation related issues</title>
<para>
The following descriptions are divided into different parts, based on the
action being performed. For each process, the acceptable behavior of database
application packages is outlined.
</para>
<section id="preconfiguration"><title>Automatic Database Configuration/Prompting</title>
<para>
It must always be assumed that the local admin knows more than any automated
system. He/She must be given the ability to opt out of any "assistance" on the
part of the package maintainer. Packages providing any such automated
assistance may do so by default if and only if the opt-out debconf prompt is
equal to or greater than priority high. With this in mind, directions for
manually installing (and upgrading if relevant) the database must be included
in the documentation for the package.
</para>
</section>
<section id="installation"><title>Database Installation</title>
<para>
For packages providing automated assistance, database
installation/configuration should be considered as part of the package
installation process. A failure to install a database should be considered a
failure to install the package and should result in an error value returned by
the relevant maintainer script. Packages may provide a "try again" option to
re-attempt configuration. Any such "try again" features here or elsewhere
mentioned in this document must have a default negative response value,
otherwise infinite loops could occur for noninteractive installs.
</para>
<para>
To properly handle package reinstallation and reconfiguration, any automated
assistance must allow for a package to be reinstalled at the same version
without removing or overwriting existing application data. Package
reconfiguration may do so.
</para>
</section>
<section id="upgrading"><title>Database Upgrading</title>
<para>
Occasionally a new upstream version of an application will require
modifications to be made to the application's underlying database. If an
automated system is to assist in such an upgrade, it should be considered as a
part of the package upgrade process; failure to upgrade the database should be
considered a failure to upgrade the package. This is the only way to safely
guarantee the chance to reattempt the upgrade with respect to the underlying
database.
</para>
<para>
Furthermore, any automated system that makes modifications to a database during
upgrade must provide the ability to back-up the database before proceeding.
Packages may perform such backups automatically, or prompt the admin via
debconf. Failure to back up the database should also be considered a failure
in the upgrade process of the whole package. As in the case of installation,
automated assistance may provide a "try-again" feature to re-attempt the
upgrade, but ultimately in the case of failure should cause a non-zero exit
value to be returned to dpkg.
</para>
<para>
<emphasis>Note</emphasis>: if the database in question supports transactional
operations, it is recommended to do so.
</para>
</section>
<section id="removing"><title>Database Removal</title>
<para>
A package should consider databases in a spirit similar to configuration files
or log files; they are something to which the administrator may have some need
even when the software that created it is no longer present.
</para>
<para>
Packages may provide support for removing underlying databases, but it is
highly recommended that the administrator is prompted with a chance to preserve
the data before doing so.
</para>
</section>
</section>
<section id="tools"><title>Build-time and run-time tools</title>
<para>
While not essential, a set of common tools for packaging and configuring these
applications can make the life of the maintainer as well as the administrator
much easier.
</para>
<section id="dbc"><title><systemitem role="package">dbconfig-common</systemitem></title>
<para>
<systemitem role="package">dbconfig-common</systemitem> is a common framework
for packaging database applications. More information can be found in the
<ulink
url="https://www.debian.org/doc/manuals/dbconfig-common/";>dbconfig-common
section</ulink> of the Debian documention for maintainers, or under
<filename>/usr/share/doc/dbconfig-common</filename>.
</para>
</section>
</section>
<section id="related"><title>Related threads/discussions</title>
<itemizedlist>
<listitem>
<para>
<ulink url="http://lists.debian.org/debian-devel/2004/10/msg00340.html";>RFC:
best practice creating database</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="http://lists.debian.org/debian-devel/2004/10/msg00962.html";>RFC:
common database policy/infrastracture</ulink>
</para>
</listitem>
</itemizedlist>
</section>
</chapter>
</book>
Attachment:
signature.asc
Description: OpenPGP digital signature