[Dbconfig-common-changes] dbconfig-common/doc Makefile, NONE,
1.1 dbconfig-common.html, 1.12, NONE dbconfig-common.sgml, NONE, 1.1
seanius at haydn.debian.org
seanius at haydn.debian.org
Tue Nov 15 16:53:32 CET 2005
- Previous message: [Dbconfig-common-changes] dbconfig-common/debian changelog, 1.81,
1.82 control, 1.10, 1.11 dbconfig-common.docs, 1.4, 1.5 rules,
1.12, 1.13
- Next message: [Dbconfig-common-changes] dbconfig-common/debian
dbconfig-common.docs, 1.5, 1.6
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
Update of /cvsroot/dbconfig-common/dbconfig-common/doc
In directory haydn:/org/alioth.debian.org/chroot/home/users/seanius/tmp/cvs-serv26264/doc
Added Files:
Makefile dbconfig-common.sgml
Removed Files:
dbconfig-common.html
Log Message:
new using debiandoc for dbconfig-common documentation. still a bit to do,
coming in a later commit.
--- NEW FILE: Makefile ---
# example Makefile for viewing/editing an encrypted file
TARGETS := dbconfig-common
#EXTENSIONS := xml dvi html info ps pdf txt tov tex
EXTENSIONS := html ps pdf txt
#default: xml dvi html info ps pdf txt tov tex
default: ${EXTENSIONS}
xml: ${foreach t,${TARGETS},${t}.xml}
dvi: ${foreach t,${TARGETS},${t}.dvi}
html: ${foreach t,${TARGETS},${t}.html}
info: ${foreach t,${TARGETS},${t}.info}
ps: ${foreach t,${TARGETS},${t}.ps}
pdf: ${foreach t,${TARGETS},${t}.pdf}
txt: ${foreach t,${TARGETS},${t}.txt}
tov: ${foreach t,${TARGETS},${t}.tov}
tex: ${foreach t,${TARGETS},${t}.tex}
clean: ${foreach f, ${TARGETS}, ${f}-clean}
%-clean:
rm -rf ${foreach ext,xml dvi html info ps pdf txt tov tex tpt, ${@:-clean=}.${ext}}
%.xml: %.sgml
debiandoc2docbookxml ${@:.xml=.sgml}
%.dvi: %.sgml
debiandoc2dvi ${@:.dvi=.sgml}
%.html: %.sgml
debiandoc2html ${@:.html=.sgml}
%.info: %.sgml
debiandoc2info ${@:.info=.sgml}
%.tex: %.sgml
debiandoc2latex ${@:.tex=.sgml}
%.ps: %.sgml
debiandoc2ps ${@:.ps=.sgml}
rm -f head.tmp body.tmp
%.pdf: %.sgml
debiandoc2pdf ${@:.pdf=.sgml}
rm -f ${@:.pdf=.tpt}
%.txt: %.sgml
debiandoc2text ${@:.txt=.sgml}
%.tov: %.sgml
debiandoc2textov ${@:.tov=.sgml}
--- dbconfig-common.html DELETED ---
--- NEW FILE: dbconfig-common.sgml ---
<!doctype debiandoc public "-//DebianDoc//DTD DebianDoc//EN">
<book>
<title>
<package>dbconfig-common</package> documentation
<author>
Sean Finney
<version>
$Revision: 1.1 $
<abstract>
<package>dbconfig-common</package> is an implementation of the "best practices for
database applications" draft, which provides debian packagers
with an easy, reliable, and consistant method for managing
databases used by debian packages.
<copyright>
Copyright © 2005 sean finney <email>seanius at debian.org</email>.
<p>This document is licensed under the
<url id="http://www.opensource.org/licenses/afl-2.1.php" name="Academic Free License, Version 2.1">
<toc sect1>
<chapt id="intro">Introduction
<p>
<package>dbconfig-common</package> can:
<list>
<item>support mysql and postgresql based applications
<item>create databases and database users
<item>access local or remote databases
<item>upgrade/modify databases when upstream changes
database structure
<item>remove databases and database users
<item>generate config files in many formats with the
database info
<item>import configs from packages previously managing
databases on their own
<item>prompt users with a set of normalized,
pre-translated questions
<item>handle failures gracefully, with an option to retry.
<item>do all the hard work automatically
<item>work for package maintainers with little effort
on their part
<item>work for local admins with little effort on
their part
<item>comply with an agreed upon set of standards for
behaviour
<item>do absolutely nothing if it is the whim of the
local admin
<item>perform all operations from within the standard
flow of debian package maintenance (no additional skill
is required of the local admin)
</list>
<chapt id="tryitout">Try it out!
<p>
if you're interested in trying it out, go ahead and check out
<ref id="develguide">, which will teach you how to get
your packages working with <package>dbconfig-common</package>.
<p>
if you'd like to see some basic examples of <package>dbconfig-common</package>
in action, check out the sample packages available in
<file>/usr/share/doc/dbconfig-common/examples</file>. in this
directory you'll find debian source directories to build the
binary packages, so you can see not only how the packages work
when they are installed, but also how they are built.
<p>
furthermore, there are two versions of the db-test series
of packages available in the above location; the second set
of packages (version 2.1) should illustrate the support for
upgrading provided by <package>dbconfig-common</package>.
<chapt id="develguide">Using <package>dbconfig-common</package> in your packages
<sect id="quickndirty">Quick and dirty: what to do
<p>
there are three things you will have to do as a package
maintainer if you want to use <package>dbconfig-common</package>: provide the
database code/scripts to setup the data base, source the
maintainer script libraries and launch <package>dbconfig-common</package>.
<package>dbconfig-common</package> 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 <package>dbconfig-common</package> is to make life easier for
both the local admin <em>and</em> the package maintainer :)
<sect1 id="hooks">putting hooks into the maintainer scripts
<p>
in the <var>postinst</var>, <var>prerm</var>, and
<var>postrm</var> scripts for your package, you
will need to source the libraries which perform
most of the work for you (you do not need to
do so in your <var>preinst</var> script). if you are
not currently using debconf in your package,
you will be now, and the debconf libraries
need to be sourced first. you will need to
depend on debconf explicitly, and either use
dh_installdebconf or otherwise install your
<var>config</var> script into your deb file
if you're not already doing so. for example,
here's an what it should look like in a <var>postinst</var>
script for an imaginary
<package>foo-mysql</package> package:
<example>
#!/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.mysql
dbc_go foo-mysql $@
# ... rest of your code ...
</example>
<p>
<var>dbc_go</var> is a function defined in
every maintainer script hook to execute the
appropriate code based on which maintainer
script is being run. note that it is passed
two arguments. <package>foo-mysql</package>,
the name of the package (there's sadly no
clean way to figure this out automatically),
and <var>$@</var> (the arguments which were
passed to the maintainer script).
<p>
note that if your package does not use debconf,
you will need to explicitly install the
<var>config</var> script in your package. the
easiest way to do so is to call dh_installdebconf
from <file>debian/rules</file>. XXX: add a note
about how to ignore the lintian warnings about
missing templates files.
<sect1 id="bootstrap">Supplying the data/code for your database
<p>
There are three directories in which you can
place code for installing the databases of
your package:
<list>
<item><file>/usr/share/dbconfig-common/data/PACKAGE/install/DBTYPE</file>
<item><file>/usr/share/dbconfig-common/data/PACKAGE/install-dbadmin/DBTYPE</file>
<item><file>/usr/share/dbconfig-common/scripts/PACKAGE/install/DBTYPE</file>
</list>
<p>
where <var>PACKAGE</var> is the name of the package,
<var>DBTYPE</var> is the type of data (mysql,
postgresql, et c).
<p>
The first directory is for the majority
of situations, in which the database can be
constructed from it's native language (SQL for
mysql/postgresql, for example). The data will
be fed to the underlying database using the
credentials of the database user. The second
directory is like the first directory, but will
be run using the credentials of the database
administrator. <em>Warning</em>: use of this
second directory should only be done when there
are excerpts of database code that <em>must</em>
be run as the database administrator (such as
some language constructs in postgresql) and should
otherwise be avoided. The third location is for
databases that require a more robust solution,
in which executable programs (shell/perl/python scripts,
or anything else) can be placed.
<p>
This code will only be executed on new installs
and reconfiguration of failed installs. In the
case of SQL databases, in the data directory you
would find the simple create and insert statements
needed to create tables and populate the database.
<em>You do not need to create the underlying
database, only populate it</em>. The scripts
directory contains shell/perl/python/whatever
scripts, which are passed the same arguments
as <var>dbc_go</var>. If you need database connection
information (username, password, etc) in your
scripts, you can source the <file>/bin/sh</file> format package
config file, or you can instruct <package>dbconfig-common</package>
to generate one in your programming language of
choice (see the advanced tips section).
<p>
if files exist in both data and scripts,
they will both be executed in an unspecified order.
<p>
that's it! the rest of what needs to be done
is handled by <package>dbconfig-common</package>, which should
keep all the work (and bugs) in one place.
happy packaging! Of course, it's recommended you
take a quick look through the rest of the document,
just to get an idea of other things that
<package>dbconfig-common</package> can do for
you in case you have special needs.
<sect id="advanced">Advanced usage.
<sect1 id="genconfig">Generating custom configuration files with database information
<p>
your database application will probably require
a username and password in order to function.
every package that uses <package>dbconfig-common</package> 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>
using <package>dbconfig-common</package>, you can do this with
little effort. in your <var>postinst</var> script, define
the variable <var>dbc_generate_include</var>
to a value that follows the form
<var>format:location</var> where <var>format</var>
is one of the supported output formats of
<var>dbconfig-generate-include</var> (list them with -h) and
location is the absolute location where you want
your config file to go. there are also some extra
variables <var>dbc_generate_include_owner</var>,
<var>dbc_generate_include_perms</var>, and
<var>dbc_generate_include_args</var> which do
what you would expect them to. <em>note: you
will be responsible for removing this file in
your <var>postrm</var> script</em>. when your scripts
are run, this environment variable will be
exported to your scripts, as well as a variable
<var>dbc_config_include</var> which has the same
value, but with the leading <var>format:</var>
stripped away for convenience.
<sect1 id="import"> Importing <package>dbconfig-common</package> into an existing package
<p>
If your package is already part of debian,
<package>dbconfig-common</package> provides some support
to load pre-existing settings from a
specified config by setting two variables:
<var>dbc_first_version</var> and
<var>dbc_load_include</var>.
<p>
<var>dbc_load_include</var> should be specified
in the <var>config</var> script and be of the format
<var>format:inputfile</var>. <var>format</var>
is one of the languages understood by
<var>dbconfig-load-include</var>, and <var>inputfile</var>
is either the config file in <var>format</var>
language, or a script file in <var>format</var>
language that otherwise determines the values
and sets them.
<p>
<var>dbc_first_version</var> should be specified
in both the <var>config</var> <em>and</em> <var>postinst</var> scripts,
and should contain the first version in which
<package>dbconfig-common</package> was introduced. when the package
is installed, if it is being upgraded from a
version less than this value it will attempt to
bootstrap itself with the values.
<sect1 id="updates">Database changes in new versions of your package
<p>
occassionaly, the upstream authors will modify the
underlying databases 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>
in order to cope with this, a second set of
directories exists for providing packagers ways
to modify the databases during package upgrades:
<list>
<item><file>/usr/share/dbconfig-common/data/PACKAGE/upgrade/DBTYPE/VERSION</file>
<item><file>/usr/share/dbconfig-common/data/PACKAGE/upgrade-dbadmin/DBTYPE/VERSION</file>
<item><file>/usr/share/dbconfig-common/scripts/PACKAGE/upgrade/DBTYPE/VERSION</file>
</list>
<p>
where <var>VERSION</var> is the version at
which the upgrade should be applied. when a
package upgrade occurs, all instances of
<var>VERSION</var> which are newer than the
previously installed version will be applied,
in order. there is also an automatically included
set of safeguards and behaviour provided by
<package>dbconfig-common</package>, 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.
<sect1 id="multidbtype">Packages that support multiple types of databases
<p>
sometimes, a particular package may support
multiple database types. this is common with perl
or php based web applications, which frequently
use some form of database abstraction layer
(pear DB for php, the DBD family for perl).
<p>
<package>dbconfig-common</package> 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 <var>config</var> script
with the types of databases your package supports.
for example, the <var>postinst</var> script would now look
like this:
<example>
#!/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 ...
</example>
<p>
The <var>config</var> script would contain an additional variable called
"dbc_dbtypes", which is a comma-seperated list of supported database
types:
<p>
<example>
#!/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 ...
</example>
<sect1 id="defaults">Hinting defaults and advanced control of configuration/installation
<p>
<package>dbconfig-common</package> 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 some these values and
set defaults that you feel are more appropriate,
as well as otherwise modify the behavior of some
parts of <package>dbconfig-common</package>.
<p>
the following table lists the variables you can
hint in your <var>config</var> script, as well as some other
variables you can use to have a finer level of
control over <package>dbconfig-common</package>. <em>you must use
these variables exactly (and only) where directed
in this table</em>.
<taglist>
<tag>dbc_dbuser (used in: <var>config</var>)
<item>name to use when connecting to
database (defaults to: package name)
<tag>dbc_dbname (used in: <var>config</var>)
<item>name of database resource to which
to connect (defaults to: package name)
<tag>dbc_dbtypes (used in: <var>config</var>)
<item>database types supported by the
package (defaults to: empty)
<tag>dbc_generate_include (used in: <var>postinst</var>)
<item>format:outputfile pair for
an extra config to be generated by
<var>dbconfig-generate-include</var>. (defaults to:
empty)
<tag>dbc_generate_include_owner (used in: <var>postinst</var>)
<item>set the owner:group of include files
generated by <var>dbconfig-generate-include</var>
(defaults to: empty)
<tag>dbc_generate_include_perms (used in: <var>postinst</var>)
<item>set the permissions of include files
generated by <var>dbconfig-generate-include</var>
(defaults to: empty)
<tag>dbc_generate_include_args (used in: <var>postinst</var>)
<item>arguments passed directly to
<var>dbconfig-generate-include</var> (defaults
to: empty)
<tag>dbc_first_version (used in: <var>config</var>,<var>postinst</var>)
<item>the first version in which
<package>dbconfig-common</package> was introduced in the
package (defaults to: empty)
<tag>dbc_load_include (used in: <var>config</var>)
<item>format:includefile pair for a config
to be read in by <var>dbconfig-load-include</var>
(defaults to: empty)
<tag>dbc_load_include_args (used in: <var>config</var>)
<item>arguments passed directly to
<var>dbconfig-load-include</var> (defaults to: empty)
</taglist>
<sect1 id="debugging"> Debugging problems with <package>dbconfig-common</package>
<p>
in the event that your package is having trouble
working with <package>dbconfig-common</package>, the first thing
you should try is to export and set the shell
variable <var>dbc_debug</var> to a nonempty
value before installing your package. this will
provide a slightly larger amount of information
about what's going on.
<p>
in the event that this does not provide
enough information, the next thing to do
will provide much, much, more information;
enough that you will probably want to redirect
stderr into a temporary output file. in the file
<file>/usr/share/dbconfig-common/dpkg/common</file>,
uncomment the <var>set -x</var> line near the
top of the file. this will show you all the
shell commands and logic as they are executed.
if you have a good idea of where the problem is
occurring, you can also insert your own <var>set
-x</var> lines elsewhere followed by <var>set
+x</var> lines to reduce the amount of input.
<chapt id="moreinfo">More Information (and how to help)
<p>
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
<url id="http://alioth.debian.org/projects/dbconfig-common" name="alioth project page">,
which is used primarily for the mailing list and cvs repository).
</p>
<p> XXX mention mailing lists
<p>
currently, there's a fair amount of work left to be done:
<list>
<item>more translators/translations are needed for the templates
<item>developers are needed to volunteer their packages with
<package>dbconfig-common</package>
<item>volunteers are needed to test the new packages
<item>support for other database formats would be nice
<item>more scheduled features are listed in
<file>/usr/share/doc/dbconfig-common/TODO</file>
</list>
</book>
- Previous message: [Dbconfig-common-changes] dbconfig-common/debian changelog, 1.81,
1.82 control, 1.10, 1.11 dbconfig-common.docs, 1.4, 1.5 rules,
1.12, 1.13
- Next message: [Dbconfig-common-changes] dbconfig-common/debian
dbconfig-common.docs, 1.5, 1.6
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
More information about the Dbconfig-common-changes
mailing list