[Dbconfig-common-changes] [dbconfig-common] r232 - trunk/doc
Sean Finney
seanius at costa.debian.org
Thu May 25 12:58:55 CEST 2006
Author: seanius
Date: 2006-05-25 10:58:54 +0000 (Thu, 25 May 2006)
New Revision: 232
Removed:
trunk/doc/dbconfig-common-using.html
Modified:
trunk/doc/dbconfig-common.sgml
Log:
removed stale documentation, moved documentation to the right place
Deleted: trunk/doc/dbconfig-common-using.html
===================================================================
--- trunk/doc/dbconfig-common-using.html 2006-05-24 22:43:34 UTC (rev 231)
+++ trunk/doc/dbconfig-common-using.html 2006-05-25 10:58:54 UTC (rev 232)
@@ -1,421 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html>
-<head>
-<title>
-using dbconfig-common in debian packages
-</title>
-</head>
-<body>
-
-<h1>
-dbconfig-common
-</h1>
-<h2>
-packager's reference
-</h2>
-<p>copyright © 2004 sean finney <seanius at debian.org></p>
-<p>this document is licensed under the <a href="http://www.opensource.org/licens
-es/afl-2.1.php">Academic Free License, Version 2.1</a>
-
-<h3> abstract </h3>
-
-<p>
-this document is a packager's reference for developers who want to use
-dbconfig-common to help them manage databases used by the debian
-packages they maintain. before reading this document, it's
-highly recommended that you read the <a href="dbapp-policy.html">best practices for database applications</a> draft, as the implementation design is based on
-rationale detailed in that document. if you are a developer who
-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.
-
-<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="#genconfig"> generating config files in other languages </a>
- <li><a href="#import"> importing dbconfig-common into an existing package </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 defaults and advanced control of configuration/installation </a>
- <li><a href="#debugging"> debugging problems with dbconfig-common </a>
- </ul>
-</ul>
-
-<a name="quickndirty">
-<h3> quick and dirty: what to do </h3>
-</a>
-
-<p>
-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 :)
-
-<a name="hooks">
-<h4> putting hooks into the maintainer scripts </h4>
-
-<p>
-in the postinst, prerm, and postrm 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 preinst 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 <code>config</code> script into your deb file if you're
-not already doing so. for example, here's an what it should look like
-in a postinst script for an imaginary "foo-mysql" package:
-
-<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.mysql
-dbc_go foo-mysql $@
-
-# ... rest of your code ...
-
-</code>
-</pre>
-
-<p> <code>dbc_go</code> 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. <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>
-note that if your package does not use debconf, you will need to
-explicitly install the <code>config</code> script in your package.
-the easiest way to do so is to call dh_installdebconf from
-<code>debian/rules</code>.
-
-<a name="bootstrap">
-<h4> supplying the data/code for your databases </h4>
-
-<p>
-there are three directories in which you can place code for
-installing the databases of your package. 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.
-<b>Warning</b>: use of this second directory should only be done when
-there are excerpts of database code that <i>must</i> 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 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
-<li>/usr/share/dbconfig-common/data/PACKAGE/install-dbadmin/DBTYPE
-<li>/usr/share/dbconfig-common/scripts/PACKAGE/install/DBTYPE
-</ul>
-
-<p>
-where PACKAGE is the name of the package, DBTYPE is the type of data
-(mysql, postgresql, et c). 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.
-<b>you do not need to create the underlying database, only populate it</b>.
-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) in your scripts, 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).
-</p>
-
-<p>
-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,
-which should keep all the work (and bugs) in one place. happy packaging!
-
-<a name="advanced">
-<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. there are
-also some extra variables <code>dbc_generate_include_owner</code>,
-<code>dbc_generate_include_perms</code>, and
-<code>dbc_generate_include_args</code> which do what you would expect
-them to. <b>note: you will be responsible for removing this file in
-your postrm script</b>. when your scripts are run, this environment
-variable will be exported to your scripts, as well as a variable
-<code>dbc_config_include</code> which has the same value, but with the
-leading <code>format:</code> stripped away for convenience.
-</p>
-
-<a name="import">
-<h4> importing dbconfig-common into an existing package </h4>
-
-<p>
-if your package is already part of debian, dbconfig-common provides some
-support to load pre-existing settings from a specified config by setting
-two variables: <code>dbc_first_version</code> and <code>dbc_load_include</code>.
-</p>
-
-<p>
-<code>dbc_load_include</code> should be specified in the config script
-and be of the format <code>format:inputfile</code>. <code>format</code> is
-one of the languages understood by dbconfig-load-include, and
-<code>inputfile</code> is either the config file in <code>format</code>
-language, or a script file in <code>format</code> language that otherwise
-determines the values and sets them.
-</p>
-
-<p>
-<code>dbc_first_version</code> should be specified in both the config
-<i>and</i> postinst scripts, and should contain the first version in
-which dbconfig-common 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.
-</p>
-
-<a name="updates">
-<h4> database changes in new versions of your package </h4>
-<p>
-occasionally, 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>
-
-<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
-<li>/usr/share/dbconfig-common/data/PACKAGE/upgrade-dbadmin/DBTYPE/VERSION
-<li>/usr/share/dbconfig-common/scripts/PACKAGE/upgrade/DBTYPE/VERSION
-</ul>
-
-<p>
-where VERSION is the version at which the upgrade should be applied.
-when a package upgrade occurs, all instances of VERSION which are newer
-than the previously installed version will be applied, in order. there
-is also an automatically included set of safeguards and behavior provided
-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>
-
-<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, 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>
-#!/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-separated 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>
-
-<a name="defaults">
-<h4> hinting defaults and advanced control of configuration/installation </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 some
-these values and set defaults that you feel are more appropriate, as well
-as otherwise modify the behavior of some parts of dbconfig-common.
-
-<p>
-the following table lists the variables you can hint in your config
-script, as well as some other variables you can use to have a finer level
-of control over dbconfig-common. <b>you must use these variables exactly
-(and only) where directed in this table</b>
-</p>
-
-<table>
-<tr>
-<th>variable name
-<th>location(s) specified
-<th>purpose
-<th>default value
-<tr>
-<td>dbc_dbuser
-<td>config
-<td>name to use when connecting to database
-<td>package name
-<tr>
-<td>dbc_dbname
-<td>config
-<td>name of database resource to which to connect
-<td>package name
-<tr>
-<td>dbc_dbtypes
-<td>config
-<td>database types supported by the package
-<td>empty
-<tr>
-<td>dbc_generate_include
-<td>postinst
-<td>format:outputfile pair for an extra config to be generated by dbconfig-generate-include.
-<td>empty
-<tr>
-<td>dbc_generate_include_owner
-<td>postinst
-<td>set the owner:group of include files generated by dbconfig-generate-include
-<td>empty
-<tr>
-<td>dbc_generate_include_perms
-<td>postinst
-<td>set the permissions of include files generated by dbconfig-generate-include
-<td>empty
-<tr>
-<td>dbc_generate_include_args
-<td>postinst
-<td>arguments passed directly to dbconfig-generate-include
-<td>empty
-<tr>
-<td>dbc_first_version
-<td>config,postinst
-<td>the first version in which dbconfig-common was introduced in the package
-<td>empty
-<tr>
-<td>dbc_load_include
-<td>config
-<td>format:includefile pair for a config to be read in by dbconfig-load-include
-<td>empty
-<tr>
-<td>dbc_load_include_args
-<td>config
-<td>arguments passed directly to dbconfig-load-include
-<td>empty
-<tr>
-<td>dbc_pgsql_createdb_encoding
-<td>postinst
-<td>specifies encoding for created postgres databases (same as createdb -E)
-<td>empty
-<tr>
-<td>dbc_sql_substitutions
-<td>postinst
-<td>if nonempty, specifies that sql files should be piped through a template substitution filter (dbconfig-generate-include -f template) before being executed.
-<td>empty
-<tr>
-<td>dbc_default_authmethod_user
-<td>config
-<td>if set to "password", dbconfig-common will set the default postgres
-authentication method to "password" (not using a local unix id).
-unless your postgres application uses a local unix account, you probably
-want to set this.
-<td>ident
-</table>
-
-<a name="debugging">
-<h4> debugging problems with dbconfig-common
-</a>
-
-<p>
-in the event that your package is having trouble working with
-dbconfig-common, the first thing you should try is to export and set the
-shell variable <code>dbc_debug</code> 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 <code>/usr/share/dbconfig-common/dpkg/common</code>, uncomment the
-<code>set -x</code> 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 <code>set -x</code> lines elsewhere followed by <code>set +x</code>
-lines to reduce the amount of input.
-
-</body>
-</html>
Modified: trunk/doc/dbconfig-common.sgml
===================================================================
--- trunk/doc/dbconfig-common.sgml 2006-05-24 22:43:34 UTC (rev 231)
+++ trunk/doc/dbconfig-common.sgml 2006-05-25 10:58:54 UTC (rev 232)
@@ -404,6 +404,23 @@
<tag>dbc_load_include_args (used in: <var>config</var>)
<item>arguments passed directly to
<var>dbconfig-load-include</var> (defaults to: empty)
+ <tag>dbc_pgsql_createdb_encoding (used in: <var>postinst</var>)
+ <item>specifies encoding for created
+ postgres databases (defaults to:
+ empty/system default)
+ <tag>dbc_sql_substitutions (used in: <var>postinst</var>)
+ <item>if nonempty, specifies that
+ sql files should be piped through
+ a template substitution filter
+ (<var>dbconfig-generate-include -f
+ template</var>) before being executed.
+ (defaults to: empty)
+ <tag>dbc_authmethod_user (used in <var>config</var>)
+ <item>if set to "password", dbconfig-common
+ will set the default postgres
+ authentication method for the package's
+ database user to "password" (defaults
+ to: empty)
</taglist>
<sect1 id="debugging"> Debugging problems with <package>dbconfig-common</package>
More information about the Dbconfig-common-changes
mailing list