[Dbconfig-common-devel] dbconfig-common/doc dbapp-policy.html,1.4,1.5 dbconfig-common-design.html,1.3,1.4 dbconfig-common-using.html,1.4,1.5 dbconfig-common.html,1.4,1.5

Update of /cvsroot/dbconfig-common/dbconfig-common/doc
In directory haydn:/org/alioth.debian.org/chroot/home/users/seanius/tmp/cvs-serv26326/doc

Modified Files:
	dbapp-policy.html dbconfig-common-design.html 
	dbconfig-common-using.html dbconfig-common.html 
Log Message:
the next version is underway.  i there's a bit more that needs to be
done, but there's been enough done that i want to get it into cvs
before i accidentally rm -rf something important.

as soon as i finish the support for include file generation, and give
everything a final go-through with testing, i'll make another upload
to experimental and an announcement to d-d.


Index: dbapp-policy.html
===================================================================
RCS file: /cvsroot/dbconfig-common/dbconfig-common/doc/dbapp-policy.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5

--- dbapp-policy.html	1 Dec 2004 06:42:20 -0000	1.4
+++ dbapp-policy.html	23 Feb 2005 05:39:59 -0000	1.5
@@ -64,15 +64,16 @@
 <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.
+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".  with this in mind, directions on installing and
-upgrading the database should be included in the documentation for
-the package.
+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.
 </p>
 
 <table border="1">
@@ -80,73 +81,61 @@
 	<th>question
 	<th>priority
 	<th>default
-	<th>db specific?
 	<th>notes
 <tr>
 	<td>automatically configure database?
 	<td>high
 	<td>yes
-	<td>no
 	<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>no
 	<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>yes
 	<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>no
 	<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>yes
 	<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>yes
 	<td>client-server apps only. 
 <tr>
 	<td>database user's password?
 	<td>low
 	<td>random or none at all
-	<td>yes
 	<td>client-server apps only. 
 <tr>
 	<td>automatically upgrade database?
 	<td>high
 	<td>yes
-	<td>no
 	<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>no
 	<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>no
 	<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>no
 	<td>only ask during package removal.  
 </table>
 
@@ -168,71 +157,46 @@
 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 maintainer scripts access to the values.  
+guaranteeing that all maintainer scripts have access to the values.  
+</p>
 
 <p>
 anything requiring creating or modifying files should be addressed
-in the post-configuration.  post-configuration should be idempotent,
-such that re-installation and re-configuration can work as the admin
-would expect from a nice package.
-
-<pre>
-<code>
-pre-configuration (package.config $newversion):
-  DEBCONF INPUT: package/configure-automatically
-  if admin has opted out 
-    exit
-  DEBCONF INPUT: package/database-name
-  if package can use multiple databases
-    DEBCONF INPUT: package/database-type
-  if database-type is a client/server (mysql, postgresql, etc)
-    DEBCONF INPUT: package/method
-    if package/method == local socket
-      if database is not installed yet, exit (run again before postinst)
-    else if package/method == tcp/ip or tcp/ip + ssl
-      DEBCONF INPUT: package/host
-      if package/host == new host
-        DEBCONF INPUT: package/newhost (will be added to hosts list)
-    DEBCONF INPUT: package/admin_user
-    DEBCONF INPUT: package/admin_pass
-    DEBCONF INPUT: package/admin_pass2
-    if paswords don't match, repeat
-    DEBCONF INPUT: package/app_user
-    DEBCONF INPUT: package/app_password
-    DEBCONF INPUT: package/app_password2
-
-(package is unpacked)
-
-package (re-)configuration (package.postinst configure $oldversion):
-  if admin has opted out
-    exit
-  attempt to create app user with admin credentials
-    if local and failed because of auth credentials, try again
-    else if local and failed for some other reason
-      DEBCONF NOTE: inform user of problem
-    else if remote and failed
-      DEBCONF NOTE: inform user of problem
-      DEBCONF INPUT: package/try-again (give them a chance to go do something)
-      if try-again == yes
-        try again!
-      else 
-        DEBCONF NOTE: how to fix situation (sql code)
-    else
-      create database with app user credentials
-    if local and failed
-      DEBCONF NOTE: inform user of problem (shouldn't happen)
-    else if remote and failed
-      DEBCONF NOTE: inform user of problem (more likely to happen)
-</code>
-</pre>
+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.
+</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>
-before a package is upgraded, it makes a backup of itself.  the backup
-is performed early, ahead of the new package being unpacked, in case
-the package specifically needs tools/data from the old package not
-present or incompatible in the new package.
+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?
 
 <p>
 all upgrading involving modifying contents or format of the database

Index: dbconfig-common-design.html
===================================================================
RCS file: /cvsroot/dbconfig-common/dbconfig-common/doc/dbconfig-common-design.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- dbconfig-common-design.html	25 Jan 2005 14:48:20 -0000	1.3
+++ dbconfig-common-design.html	23 Feb 2005 05:39:59 -0000	1.4
@@ -1,3 +1,4 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html>
 <head>
 <title>
@@ -124,36 +125,21 @@
 <h3> global and per-package configuration </h3>
 <hr>
 <ul>
-<li> * /etc/dbconfig-common/sources
 <li> /etc/dbconfig-common/config
 <li> /etc/dbconfig-common/$package.conf
 </ul>
-<br>
-<i>
-* == not yet implemented
-</i>
 <hr>
 
 <p>
-sources contains a listof known/previously used database resources.  these
-will probably be in a url format similar to the dsn's used in many
-applications.  for example:
-
-<pre>
-<code>
-mysql://dbuser:secretpass@localhost/somedb
-pgsql://anotheruser:passpass@dbserver:1337/anotherdb
-</code>
-</pre>
-
-<p>
 config contains the default global settings to be used during configuration.
+</p>
 
 <p>
 $package.conf contains the per-package settings for database applications.
 these settings are fed into debconf, so whether if debconf is set to
 non-interactive mode these will be the authoritative values, otherwise
 they will serve as pre-seeded defaults.
+</p>
 
 <p>
 all of these files (with the exception of the as-of-yet-non-existant
@@ -165,6 +151,7 @@
 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.
+</p>
 
 </body>
 </html>

Index: dbconfig-common-using.html
===================================================================
RCS file: /cvsroot/dbconfig-common/dbconfig-common/doc/dbconfig-common-using.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- dbconfig-common-using.html	25 Jan 2005 14:48:20 -0000	1.4
+++ dbconfig-common-using.html	23 Feb 2005 05:39:59 -0000	1.5
@@ -1,3 +1,4 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html>
 <head>
 <title>
@@ -27,10 +28,21 @@
 is curious in how dbconfig-common works or want to possibly work on
 dbconfig-common itself, you should read the <a href="dbconfig-common-design.html">technical reference</a> for dbconfig-common.
 
-<p>
-this document is divided into two sections: 
-<a href="#quickndirty">"quick and dirty"</a>, and 
-<a href="#advanced">"advanced usage"</a>.
+<h3> table of contents </h3>
+
+<ul>
+<li><a href="#quickndirty">quick and dirty: what to do</a>
+  <ul>
+  <li><a href="#hooks">putting hooks into the maintainer scripts</a>
+  <li><a href="#bootstrap">supplying the data/code for your databases</a>
+  </ul>
+<li><a href="#advanced">advanced usage</a>.
+  <ul>
+  <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>
+  </ul>
+</ul>
 
 <a name="quickndirty">
 <h3> quick and dirty: what to do </h3>
@@ -44,6 +56,7 @@
 logic, et c.  after all, the goal of dbconfig-common is to make life
 easier for both the local admin <i>and</i> the package maintainer :)
 
+<a name="hooks">
 <h4> putting hooks into the maintainer scripts </h4>
 
 <p>
@@ -71,12 +84,13 @@
 </pre>
 
 <p> <code>dbc_go</code> is a function defined in every maintainer
-script include to execute the appropriate code based on which
+script hook to execute the appropriate code based on which
 maintainer script is being run.  note that it is passed two
 arguments. <code>foo-mysql</code>, the name of the package (there's
 sadly no clean way to figure this out automatically), and <code>$@</code>
-the arguments which were passed to the maintainer script.
+(the arguments which were passed to the maintainer script).
 
+<a name="bootstrap">
 <h4> supplying the data/code for your databases </h4>
 
 <p>
@@ -85,8 +99,8 @@
 the majority of situations, in which the database can be constructed
 from it's native language (SQL for mysql/postgresql, for example),
 and the second is for databases that require a more robust solution,
-in which executable shell scripts can be placed.  these directories can
-be found under the following format:
+in which executable shell scripts (or anything else) can be placed.
+these directories can be found under the following format:
 
 <ul>
 <li>/usr/share/dbconfig-common/data/PACKAGE/install/DBTYPE
@@ -102,12 +116,27 @@
 order.  Note: if the database in question already exists, dbconfig-common
 will not process any installation code/data.
 
+<p>
+that's it!  the rest of what needs to be done is handled by dbconfig-common,
+which should keep all the work (and bugs) in one place.  happy packaging!
+
+<a name="advanced">
+<h3> advanced usage </h3>
+</a>
+
+<a name="updates">
 <h4> database changes in new versions of your package </h4>
 <p>
 occassionaly, the upstream authors will modify the underlying databases
-between versions of their software.  in order to cope with this, a second
-set of directories exists for providing packagers ways to modify the
-databases during package upgrades:
+between versions of their software.  for example, in mysql applications
+column names may change, move to new tables, or the data itself may need
+to be modified in newer upstream versions of a package.
+</p>
+
+<p>
+in order to cope with this, a second set of directories exists for
+providing packagers ways to modify the databases during package upgrades:
+</p>
 
 <ul>
 <li>/usr/share/dbconfig-common/data/PACKAGE/upgrade/DBTYPE/VERSION
@@ -122,28 +151,28 @@
 by dbconfig-common, so as the packager you shouldn't need to worry about
 most of the error-handling.
 
-<p>
-that's it!  the rest of what needs to be done is handled by dbconfig-common,
-which should keep all the work (and bugs) in one place.  happy packaging!
-
-<a name="advanced">
-<h3> advanced usage </h3>
-</a>
 
+<a name="multidb">
 <h4> packages that support multiple types of databases </h4>
 
 <p>
 sometimes, a particular package may support multiple database types.  this is
-quite common with perl or php based web applications.  dbconfig-common provides
-support for such applications in a relatively straightforward fashion, allowing
-the local admin to select which database type to use when configuring
-a database for a package
+common with perl or php based web applications, which frequently use some
+form of database abstraction layer (pear DB for php, DBD::MySQL for perl).
+</p>
+
+<p>
+dbconfig-common provides support for such applications in a relatively
+straightforward fashion, allowing the local admin to select which database
+type to use when configuring a database for a package
+</p>
 
 <p>
 to take advantage of this feature, you will want to use the "generic"
 maintainer script hooks, and additionally hint the debconf pre-config
 script with the types of databases your package supports.  for example,
 the postinst script would now look like this:
+</p>
 
 <pre>
 <code>
@@ -183,6 +212,37 @@
 </code>
 </pre>
 
+<a name="defaults">
+<h4> hinting other defaults to the configuration process </h4>
+
+<p>
+dbconfig-common has a set of pre-defined default values for most of the
+questions with which it prompts the user, most of which are variations
+on the name of the package.  however, as a packager you can override
+these values and set defaults that you feel are more appropriate.  the
+following table lists the variables you can hint in your config
+script. <b>do not set these variables in anything other than the
+.config script</b>
+</p>
+
+<table>
+<tr>
+<th>variable name
+<th>purpose
+<th>default value
+<tr>
+<td>dbc_dbuser
+<td>name to use when connecting to database
+<td>package name
+<tr>
+<td>dbc_dbname
+<td>name of database resource to which to connect
+<td>package name
+<tr>
+<td>dbc_dbtypes
+<td>database types supported by the package
+<td>empty
+</table>
 
 </body>
 </html>

Index: dbconfig-common.html
===================================================================
RCS file: /cvsroot/dbconfig-common/dbconfig-common/doc/dbconfig-common.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- dbconfig-common.html	25 Jan 2005 14:48:20 -0000	1.4
+++ dbconfig-common.html	23 Feb 2005 05:39:59 -0000	1.5
@@ -1,3 +1,4 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html>
 <head>
 <title>
@@ -47,7 +48,8 @@
 <ul>
 <li><a href="dbapp-policy.html">best practices</a> for database application packages in debian.  this document should be required reading for developers who want to package applications that use an underlying database.
 <li><a href="dbconfig-common-using.html">developers guide</a> for using dbconfig-common with debian packages.  this should hopefully make life easier for
-both the debian packager as well as the local admin.
+both the debian packager as well as the local admin.  there is both a simple
+"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>
 



