[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


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>




More information about the Dbconfig-common-changes mailing list