[Dbconfig-common-devel] dbconfig-common/doc dbapp-policy.html,1.5,1.6 dbconfig-common-design.html,1.4,1.5 dbconfig-common-using.html,1.5,1.6 dbconfig-common.html,1.5,1.6
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-serv14274
Modified Files:
dbapp-policy.html dbconfig-common-design.html
dbconfig-common-using.html dbconfig-common.html
Log Message:
documentation updates
Index: dbapp-policy.html
===================================================================
RCS file: /cvsroot/dbconfig-common/dbconfig-common/doc/dbapp-policy.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- dbapp-policy.html 23 Feb 2005 05:39:59 -0000 1.5
+++ dbapp-policy.html 3 Mar 2005 22:25:46 -0000 1.6
@@ -5,6 +5,7 @@
</head>
<body>
<h1>best practices for database applications</h1>
+<p>version 20050228-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>
@@ -189,55 +190,56 @@
<h3>upgrading</h3>
<p>
-before a package is upgraded, it should make a backup of any database
-in the case of error. the backup should be performed early, ahead of
-the new package being unpacked. this ensures that the versions of the
-software necessary to interact with the previous version of the database
-are present, since newer versions of the tools might not necessarily
-be compatible. this also helps the error to occur as soon as possible,
-giving the most flexibility for upgrading. XXX i don't think i'm doing this,
-is it even feasible?
+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".
+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 critical priority message informing him/her of what needs to be
-done.
+a note informing him/her of what needs to be done.
<p>
-when upgrades fail, the package should backup the new but broken database,
-drop the old database, and re-initialize it from the pre-upgrade backup.
-the package configuration should be considered failed, and the admin notified
-that they need to reconfigure/downgrade. this way, the admin can "try
-again" by reconfigure the package with dpkg-reconfigure, or downgrade
-to the previous version (since the old database will still be in place).
+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.
+
+<p>
+a failed database upgrade
+should constitute a failed package upgrade, and must cause dpkg to exit
+with a non-zero status.
<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.
-<pre>
-<code>
-package pre-upgrading (new-package.preinst upgrade $oldversion):
- if admin has opted out
- exit
- backup database to file
-
-(new package's files are then unpacked)
-
-new package configuration (new-package.postinst configure $oldversion):
- if admin has opted out
- DEBCONF NOTE: database must be updated manually, details...
- exit
+<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>inform admin, exit with error status
+ <ul>
+</ul>
perform upgrade
if error
backup failed database
@@ -250,52 +252,17 @@
<h3>removal</h3>
<p>
a package should consider databases in a spirit similar to configuration
-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 <i>purged</i>, 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.
-
-<p>
-the current approach is that data should be left on the system in
-its pristine form when the package is removed, but when the package
-is purged the database should either provide an "offline" copy of
-itself or delete itself. perhaps this could be combined with a
-hook in package installation that looked for the existance of a
-similar file.
-
-<p>
-as in the previous situations, if the local admin has opted out of
-assistance from the package maintainer's scripts, no actions should
-be performed.
-
-<p>
-for example, a mysql web application would not touch its database
-when it was removed, but if purged would dump the sql code
-into a temporary file, remove the database, and inform the admin on its
-way out. an openldap server would leave its database in place on
-removal, but would dump itself into an ldif file on the way out. other
-packages might just copy their raw database files into a temporary
-location on their way out.
+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
+still up for some debate, and will probably evolve.
-<pre>
-<code>
-package removal (package.postrm)
- if admin has opted out
- exit
- if database can be stored in offline format
- dump database into temporary location
- DEBCONF NOTE: where the data is stored
- remove database
-</code>
-</pre>
-
<h2>build-time and run-time tools</h2>
<p>
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 adminsitrator much easier. <i><b>note: this is probably
-the portion of the document most subject to change</b></i>
+as well as the adminsitrator much easier.
</p>
<p>
Index: dbconfig-common-design.html
===================================================================
RCS file: /cvsroot/dbconfig-common/dbconfig-common/doc/dbconfig-common-design.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- dbconfig-common-design.html 23 Feb 2005 05:39:59 -0000 1.4
+++ dbconfig-common-design.html 3 Mar 2005 22:25:46 -0000 1.5
@@ -142,15 +142,10 @@
</p>
<p>
-all of these files (with the exception of the as-of-yet-non-existant
-sources file) are in a shell-script include format, such that they
+all of these files are in a shell-script include format, such that they
can be easily read and written by the common configuration scripts.
-this means they will not be flagged as conffiles. currently when these
-files are regenerated, they are sourced, and later replaced with a new
-template, substituting in new values for the old ones if appropriate. this
-means that all comments and extranneous shell stuff is removed.
-later this may perhaps be managed by something like ucf, which provides a
-little more flexibility for situations like this.
+they're generated and maintained via ucf, so this setup should be fairly
+friendly to the admin who wants to manually edit the files.
</p>
</body>
Index: dbconfig-common-using.html
===================================================================
RCS file: /cvsroot/dbconfig-common/dbconfig-common/doc/dbconfig-common-using.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- dbconfig-common-using.html 23 Feb 2005 05:39:59 -0000 1.5
+++ dbconfig-common-using.html 3 Mar 2005 22:25:46 -0000 1.6
@@ -38,6 +38,7 @@
</ul>
<li><a href="#advanced">advanced usage</a>.
<ul>
+ <li><a href="#genconfig"> generating config files in other languages </a>
<li><a href="#updates"> database changes in new versions of your package </a>
<li><a href="#multidb"> packages that support multiple types of databases </a>
<li><a href="#defaults"> hinting other defaults to the configuration process </a>
@@ -109,12 +110,19 @@
<p>
where PACKAGE is the name of the package, DBTYPE is the type of data
-(mysql, postgresql, et c). in the case of sql databases, you would find
-the simple create and insert statements needed to create and populate
-the database. this code will only be executed on new installs. if files
-exist in both data and scripts, they will both be executed in an unspecified
-order. Note: if the database in question already exists, dbconfig-common
-will not process any installation code/data.
+(mysql, postgresql, et c). this code will only be executed on new
+installs. in the case of sql databases, in the data directory you
+would find the simple create and insert statements needed to create
+and populate the database. the scripts directory contains
+shell/perl/python/whatever scripts, which are passed the same arguments
+as dbc_go. if you need database connection information (username,
+password, etc), you can source the /bin/sh format package config file,
+or you can instruct dbconfig-common to generate one in your programming
+language of choice (see the advanced tips section).
+
+if files exist in both data and scripts,
+they will both be executed in an unspecified order.
+</p>
<p>
that's it! the rest of what needs to be done is handled by dbconfig-common,
@@ -124,6 +132,29 @@
<h3> advanced usage </h3>
</a>
+<a name="genconfig">
+<h4> generating config files in other programming languages </h4>
+
+<p>
+your database application will probably require a username and password
+in order to function. every package that uses dbconfig-common already
+has a /bin/sh includable format config file, but it may be more convenient
+to have something in the native language of the package. for example,
+packaging a php/mysql web app would be a lot easier if there were already
+a file existing with all the information in php includable format.
+</p>
+
+<p>
+using dbconfig-common, you can do this with little effort. in your postinst
+script, define the variable <code>dbc_generate_include</code> to a value
+that follows the form <code>format:location</code> where <code>format</code>
+is one of the supported output formats of dbconfig-generate-include (list
+them with -h) and location is the absolute location where you want
+your config file to go. <b>note: you will be responsible for moving this
+file in your postrm script</b>.
+
+</p>
+
<a name="updates">
<h4> database changes in new versions of your package </h4>
<p>
@@ -151,6 +182,10 @@
by dbconfig-common, so as the packager you shouldn't need to worry about
most of the error-handling.
+<p>
+as with installation, scripts will be passed the same cmdline arguments
+as were passed to dbc_go.
+</p>
<a name="multidb">
<h4> packages that support multiple types of databases </h4>
Index: dbconfig-common.html
===================================================================
RCS file: /cvsroot/dbconfig-common/dbconfig-common/doc/dbconfig-common.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- dbconfig-common.html 23 Feb 2005 05:39:59 -0000 1.5
+++ dbconfig-common.html 3 Mar 2005 22:25:46 -0000 1.6
@@ -32,6 +32,7 @@
<li>access local or remote databases
<li>upgrade/modify databases when upstream changes database structure
<li>remove databases and database users
+<li>generate config files in many formats with the database info.
<li>prompt users with a set of normalized, pre-translated questions
<li>do all the hard work automatically
<li>work for package maintainers with little effort on their part
@@ -52,6 +53,26 @@
"crash course", and a section for advanced usage.
<li><a href="dbconfig-common-design.html">detailed description</a> of how dbconfig-common works. for the curious/hackers.
</ul>
+
+<h3>help out!</h3>
+
+<p>
+currently, there's a fair amount of work left to be done:
+</p>
+
+<ul>
+<li>translators 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
+</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>.
+</p>
</body>
</html>