[Dbconfig-common-devel] dbconfig-common/doc dbapp-policy.html,1.7,1.8 dbconfig-common.html,1.9,1.10
seanius@haydn.debian.org
seanius@haydn.debian.org
Update of /cvsroot/dbconfig-common/dbconfig-common/doc
In directory haydn:/org/alioth.debian.org/chroot/home/users/seanius/tmp/cvs-serv19687/doc
Modified Files:
dbapp-policy.html dbconfig-common.html
Log Message:
this is it...
Index: dbapp-policy.html
===================================================================
RCS file: /cvsroot/dbconfig-common/dbconfig-common/doc/dbapp-policy.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- dbapp-policy.html 17 Mar 2005 00:47:49 -0000 1.7
+++ dbapp-policy.html 12 Jul 2005 03:39:31 -0000 1.8
@@ -1,257 +1,136 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
-<title>best practices for packaging database applications</title>
+<title>Best practices for packaging database applications</title>
</head>
<body>
-<h1>best practices for database applications</h1>
-<p>version 20050228-1</p>
+<h1>Best practices for database applications</h1>
+<p>version 20050711-1</p>
<p>copyright © 2004 sean finney <seanius@debian.org></p>
-<p>this document is licensed under the <a href="http://www.opensource.org/licenses/afl-2.1.php">Academic Free License, Version 2.1</a>
+<p>This document is licensed under the <a href="http://www.opensource.org/licenses/afl-2.1.php">Academic Free License, Version 2.1</a>
<h2>abstract</h2>
<p>
-this draft describes a set of guidelines and best practices to be
+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
+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.
-<h2>database applications</h2>
+<h2>Database applications</h2>
<p>
-in this document a database application is any program that relies
+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
+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
+In the future this scope may have to be narrowed to avoid ambiguity
and be more effective as a policy.
-<h2>database types and placement</h2>
+<h2>Database types and placement</h2>
<p>
-for the purposes of this policy, there are two types of databases: persistent
-and cached.
+For the purposes of this document, there are two types of databases:
+"persistent" and "cached".
+
<p>
-<b>persistant</b> databases contain data that can not be entirely
-reconstituted in the case that the database is removed. also included
+<b>Persistant</b> 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
-(makes a system unstable/unusable) or security concerns.
-this category applies to most database applications.
-examples:
+(making a system unstable/unusable) or security concerns.
+Applications using this category of databases are the primary focus of
+this document. Examples:
<ul>
<li>relational database servers providing storage to other applications.
-<li>slapd databases
-<li>webblog entries
+<li>web applications using a relational database
+<li>openldap's slapd databases
<li>rrd files containing accumulated/historical data.
</ul>
<p>
-<b>cached</b> databases are a specific group of databases which upon their
-removal could be completely regenerated, and could be removed without causing
-a serious denial of service or security concern. examples include:
+<b>Cached</b> 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:
<ul>
-<li>debconf
+<li>debconf responses
<li>locate database
<li>caching nameserver data
<li>apt's list of available packages
</ul>
-<p>both of these database types fall under already defined guidelines in
-the FHS. persistant data must be placed under /var/lib/packagename, and
-cached data under /var/cache/packagename, respectively. the remainder
+<p>Both of these database types fall under already defined guidelines in
+the FHS; persistant data must be placed under /var/lib/packagename, and
+cached data under /var/cache/packagename, respectively. The remainder
of this document primarily addresses the former.
<h2>configuration</h2>
-<p> all information required for configuration must be obtained automatically,
-or via debconf. there should be a consistent scheme for how/when these
-questions are asked. some of these questions may have input, choices,
-or output that is dependant on the database type. see the table below
-for a list of example questions.
-</p>
-
<p>
-no matter what, it must be assumed that the local admin knows more than
-any automated system, so he/she must be given the ability to opt out
-of any "assistance" on the part of the package maintainer. with this
-in mind, directions on installing and upgrading the database must be
-included in the documentation for the package.
+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 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.
</p>
-<table border="1">
-<tr>
- <th>question
- <th>priority
- <th>default
- <th>notes
-<tr>
- <td>automatically configure database?
- <td>high
- <td>yes
- <td>the local admin must have a way of opting out of "assistance"
-<tr>
- <td>what database type?
- <td>medium
- <td>maintainer script should determine reasonable default
- <td>only applicable for apps that support multiple database types.
-<tr>
- <td>what how to connect (unix socket, tcp/ip, etc)
- <td>low
- <td>maintainer script should determine reasonable default
- <td>depends on the default for the database provider package. in some cases it may not be appropriate to ask at all.
-<tr>
- <td>remote host
- <td>high
- <td>
- <td>only prompted if user has selected a connection method requiring it
-<tr>
- <td>database administrative user/password?
- <td>high
- <td>possibly determinable in maintainer script
- <td>client-server apps only. if possible to automatically determine this, no need to ask. it should either not be stored or user should be able specify they don't want this stored.
-<tr>
- <td>database name / database user?
- <td>low
- <td>package name
- <td>client-server apps only.
-<tr>
- <td>database user's password?
- <td>low
- <td>random or none at all
- <td>client-server apps only.
-<tr>
- <td>automatically upgrade database?
- <td>high
- <td>yes
- <td>the local admin must have a way of opting out of "assistance". only ask if there are upgrades that actually need to be applied.
-<tr>
- <td>back up database before upgrade?
- <td>low
- <td>true
- <td>only ask during upgrades. user should be notified where to find backups and possibly how to restore.
-<tr>
- <td>automatically deconfigure/remove database?
- <td>high
- <td>yes
- <td>the local admin must have a way of opting out of "assistance". only ask during removal.
-<tr>
- <td>purge database?
- <td>high
- <td>true
- <td>only ask during package removal.
-</table>
-
-<h2>overview of installation/etc process</h2>
+<h2>Overview of package installation/upgrade/removal processes</h2>
<p>
-the following descriptions are divided into different parts, based on
-the action being performed. for each process, a description and its
-rationale is followed by a block of pseudo code giving a more concrete
-description of the process.
-
-lines starting with <code>DEBCONF INPUT:</code> are points when the admin
-may possibly be prompted for some information (depending on priorities).
-lines starting with <code>DEBCONF NOTE:</code> are points where the
-admin may need to be notified of problems or other important information.
+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.
-<h3>installation</h3>
+<h3>Database installation</h3>
<p>
-package installation is broken into two steps, preconfiguration
-and configuration. with the exception of a "try again" question,
-all installation related questions should be asked in the preconfiguration
-stage. this keeps all questions asked in the same time, as well as
-guaranteeing that all maintainer scripts have access to the values.
+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.
</p>
<p>
-anything requiring creating or modifying files should be addressed
-in the post-configuration. post-configuration should behave exactly
-the same every invocation (though it may take different actions based
-upon the input from the admin). re-installation and re-configuration
-should work just as the admin would expect from any other package. if
-the admin wishes to reconfigure/reinstall the database for the package,
-the should not need to do anything other than reconfigure/reinstall
-the package that provides the database.
+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.
</p>
-<ul>
-<li>config script is unpacked
-<li>pre-configuration (package.config $newversion)
- <ul>
- <li>admin prompted with offer for assistance
- <li>if they answer postively, get all necessary information
- </ul>
-<li>package is unpacked
-<li>package (re-)configuration (package.postinst configure $oldversion)
- <ul>
- <li>if admin has opted out, exit
- <li>else create database, user, config files
- <li>if failure occurs, either exit w/error or provide a way to try again
- </ul>
-</ul>
-
-<h3>upgrading</h3>
-<p>
-if a package upgrade requires modification to the underlying database, the
-admin must be given the oppurtunity to back up the database. the backup
-should be performed early, ahead of the new package being unpacked if
-possible.
-
-<p>
-all upgrading involving modifying contents or format of the database
-should be taken care of in the postinst script. this is the only point
-the maintainer scripts can have access to the necessary data/tools from
-the new version, and the only way to reliably provide the user with a
-way to "try again" (dpkg-reconfigure).
-
-<p>
-additionally, if the local admin has previously opted out of assistance
-in installing/configuring the database for this package, no upgrades
-should be attempted. instead, the local admin should be provided with
-a note informing him/her of what needs to be done.
-
+<h3>Database upgrading</h3>
<p>
-when upgrades fail, the package should not attempt any further action
-to remedy the situation. because it's quite possible that there
-is a problem outside of the package's control (full disk, for example),
-the only safe thing to do is gracefully fail, and inform the admin.
-anything else might risk further loss of data.
+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,
+which is the only way to safely guarantee the chance to reattempt the
+upgrade.
<p>
-a failed database upgrade
-should constitute a failed package upgrade, and must cause dpkg to exit
-with a non-zero status.
+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.
<p>
<b>note</b>: if the database in question supports transactions, placing
-each upgrade script within a transaction makes upgrades much
-less likely to break things.
-
-<ul>
-<li>new package's files are then unpacked
-<li>new package configuration (new-package.postinst configure $oldversion):
- <ul>
- <li>inform admin of upgrade, give chance to backup database.
- <li>if admin has opted out
- <ul>
- <li>provide details of what must be done
- </ul>
- <li>perform upgrade
- <li>if error occurred
- <ul>
- <li>DEBCONF NOTE: stuff is broken, man! reconfigure or downgrade!
- <li>exit with error status
- </ul>
- </ul>
-</ul>
-</code>
-</pre>
+each upgrade script within a transaction will make upgrades much more
+robust.
-<h3>removal</h3>
+<h3>Database removal</h3>
<p>
-a package should consider databases in a spirit similar to configuration
+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 not present.
-however, when a package is removed, there should be an avenue for
-the data to disappear. exactly how both these needs should achieved is
+have some need even when the software that created it is no longer present.
+However, when a package is removed, there should be an avenue for
+the data to disappear. Exactly how both these needs should achieved is
still up for some debate, and will probably evolve.
<h2>build-time and run-time tools</h2>
@@ -263,8 +142,7 @@
<h3>dbconfig-common: a common framework for packaging database applications</h3>
<p>
-a work in-progress project of such nature can be found at
-sean finney's
+a work in-progress project of such nature can be found at the
<a href="http://people.debian.org/~seanius/policy/dbconfig-common.html">
dbconfig-common</a> page.
</p>
Index: dbconfig-common.html
===================================================================
RCS file: /cvsroot/dbconfig-common/dbconfig-common/doc/dbconfig-common.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -d -r1.9 -r1.10
--- dbconfig-common.html 11 Jul 2005 04:23:01 -0000 1.9
+++ dbconfig-common.html 12 Jul 2005 03:39:31 -0000 1.10
@@ -27,7 +27,7 @@
dbconfig-common can:
<ul>
-<li>support mysql and postgresql applications
+<li>support mysql and postgresql based applications
<li>create databases and database users
<li>access local or remote databases
<li>upgrade/modify databases when upstream changes database structure
@@ -49,7 +49,12 @@
<h3>try it out!</h3>
<p>
-work-in-progress packages can be found out the following uris:
+as of mid-july, dbconfig-common has been uploaded to debian's unstable
+archive. if you're interested in trying it out, go ahead and check
+out the <a href="dbconfig-common-using.html">developers guide</a>, which
+will teach you how to get your packages working with dbconfig-common. if
+you'd like to see some basic examples of dbconfig-common in action, check
+out the sample packages available at the following uris:
</p>
<pre>
@@ -64,8 +69,6 @@
</p>
<dl>
-<dt>dbconfig-common
-<dd>the common framework package
<dt>db-test-mysql
<dd>a sample mysql using package.
<dt>db-test-pgsql
@@ -99,17 +102,19 @@
</p>
<ul>
-<li>translators are needed for the templates
+<li>more translators/translations are needed for the templates
<li>developers are needed to volunteer their packages with dbconfig-common
<li>volunteers are needed to test the new packages
<li>support for other database formats would be nice
+<li>more scheduled features are listed in /usr/share/doc/dbconfig-common/TODO
</ul>
<p>
-if you're interested in helping out, or just want to keep
-tabs on the state of the project, i've started an alioth site
-(used primarily for the mailing list and cvs repository) <a
-href="http://alioth.debian.org/projects/dbconfig-common">here</a>.
+if you're interested in helping out, or just want to keep tabs on the
+state of the project, you are invited to check out the dbconfig-common
+<a href="http://alioth.debian.org/projects/dbconfig-common">alioth
+project page</a>, which is used primarily for the mailing list and
+cvs repository).
</p>
</body>