[Dbconfig-common-devel] dbconfig-common/doc dbconfig-common-design.html,1.2,1.3 dbconfig-common-using.html,1.3,1.4 dbconfig-common.html,1.3,1.4
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-serv26038/doc
Modified Files:
dbconfig-common-design.html dbconfig-common-using.html
dbconfig-common.html
Log Message:
big commit, this brings in all the latest code i've been working on.
support for postgresql is slightly more tested, and seems to work
on remote and local hosts. more decisions still need to be made regarding
authentication/connections methods, but things have gotten stable enough
to make a new release before trudging onwards :)
sean
Index: dbconfig-common-design.html
===================================================================
RCS file: /cvsroot/dbconfig-common/dbconfig-common/doc/dbconfig-common-design.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- dbconfig-common-design.html 1 Dec 2004 06:42:20 -0000 1.2
+++ dbconfig-common-design.html 25 Jan 2005 14:48:20 -0000 1.3
@@ -42,8 +42,8 @@
of shell code which can be included by package maintainers. this way
whatever the "best practices" are deemed to be, the latest version of
this package and their scripts will implement it transparently for the
-packages which use them. for each maintainer script, there is (or will
-be, anyway) a generic script and a database-specific script. that is,
+packages which use them. for each maintainer script, there is a generic
+script and a database-specific script. that is,
you will find scripts named:
<ul>
@@ -62,17 +62,15 @@
# source debconf stuff
. /usr/share/debconf/confmodule
# source dbconfig-common stuff
-. /usr/share/dbconfig-common/dpkg/postinst.mysql foo-mysql $@
+. /usr/share/dbconfig-common/dpkg/postinst.mysql
+dbc_go foo-mysql $@
# ... rest of code ...
</code>
</pre>
<p>
-Note the arguments passed when sourcing the script. <b>TODO:</b>
-really, the maintainer script being executed could also be derived from
-the source scriplet, so perhaps the line would be the same in every
-maintainer script.
+Note the arguments passed when sourcing the script.
<h3> per-package database installation code </h3>
<hr>
@@ -93,7 +91,7 @@
<p>
this code should not assume that it has administrative control over
-anything other than the database in question (that is, it is run
+anything other than the database in question (that is, it may be run
as the database user, not the database admin)
<h3> per-package database upgrade code </h3>
@@ -149,21 +147,24 @@
</pre>
<p>
-config will contain the default settings to be used during per-package
-configuration.
+config contains the default global settings to be used during configuration.
<p>
-$package.conf will contain the per-package settings for database applications.
-while changing these settings might not be all that practical, Debconf Is Not A Registry(TM) so these should be stored somewhere on the filesystem.
+$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>
-all of these files will probably be of the 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. perhaps managed
-by something like ucf, or perhaps there will be something up at the top of
-the file informing the user that their settings will be preserved but
-formatting and commenting lost, or perhaps there will be a begin/end
-debconf clause.
+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
+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.
</body>
</html>
Index: dbconfig-common-using.html
===================================================================
RCS file: /cvsroot/dbconfig-common/dbconfig-common/doc/dbconfig-common-using.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- dbconfig-common-using.html 30 Nov 2004 21:13:46 -0000 1.3
+++ dbconfig-common-using.html 25 Jan 2005 14:48:20 -0000 1.4
@@ -27,16 +27,22 @@
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>.
+
+<a name="quickndirty">
<h3> quick and dirty: what to do </h3>
+</a>
<p>
-there are two things you will have to do as a package maintainer if you
-want to use dbconfig-common: source the maintainer script libraries and
-provide the database code/scripts to create the database. dbconfig-common
-will take care of everything else, include all debconf related questions,
-database/database-user creation, upgrade/remove/purge 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 :)
+there are three things you will have to do as a package maintainer if you
+want to use dbconfig-common: provide the database code/scripts to setup the database, source the maintainer script libraries and launch dbconfig-common.
+dbconfig-common will take care of everything else, include all debconf
+related questions, database/database-user creation, upgrade/remove/purge
+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 :)
<h4> putting hooks into the maintainer scripts </h4>
@@ -56,17 +62,20 @@
# source debconf stuff
. /usr/share/debconf/confmodule
# source dbconfig-common stuff
-. /usr/share/dbconfig-common/dpkg/postinst.mysql foo-mysql $@
+. /usr/share/dbconfig-common/dpkg/postinst.mysql
+dbc_go foo-mysql $@
# ... rest of your code ...
</code>
</pre>
-<p> note that the script 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.
+<p> <code>dbc_go</code> is a function defined in every maintainer
+script include 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.
<h4> supplying the data/code for your databases </h4>
@@ -116,6 +125,64 @@
<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>
+
+<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
+
+<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:
+
+<pre>
+<code>
+#!/bin/sh
+# postinst maintainer script for foo-mysql
+
+# source debconf stuff
+. /usr/share/debconf/confmodule
+# source dbconfig-common stuff
+. /usr/share/dbconfig-common/dpkg/postinst
+dbc_go foo-mysql $@
+
+# ... rest of your code ...
+
+</code>
+</pre>
+
+and the config script would contain an additional variable called
+"dbc_dbtypes", which is a comma-seperated list of supported database
+types:
+
+<pre>
+<code>
+#!/bin/sh
+# config maintainer script for foo-mysql
+
+# source debconf stuff
+. /usr/share/debconf/confmodule
+# we support mysql and pgsql
+dbc_dbtypes="mysql, pgsql"
+# source dbconfig-common stuff
+. /usr/share/dbconfig-common/dpkg/config
+dbc_go foo-mysql $@
+
+# ... rest of your code ...
+
+</code>
+</pre>
+
</body>
</html>
Index: dbconfig-common.html
===================================================================
RCS file: /cvsroot/dbconfig-common/dbconfig-common/doc/dbconfig-common.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- dbconfig-common.html 1 Dec 2004 06:42:20 -0000 1.3
+++ dbconfig-common.html 25 Jan 2005 14:48:20 -0000 1.4
@@ -26,6 +26,7 @@
dbconfig-common can:
<ul>
+<li>support mysql and postgresql applications
<li>create databases and database users
<li>access local or remote databases
<li>upgrade/modify databases when upstream changes database structure
@@ -36,7 +37,9 @@
<li>work for local admins with little effort on their part
<li>comply with an agreed upon set of standards for behaviour
<li>do absolutely nothing if it is the whim of the local admin
-<li>reconfigure the database of a package via dpkg-reconfigure
+<li>perform all operations from within the standard flow of debian
+ package maintainance (no additional skill is required of the local
+ admin)
</ul>
<h3>more information</h3>