# dbconfig-common

## technical reference

copyright © 2004 sean finney <seanius@debian.org>

this document is licensed under the Academic Free License, Version 2.1

### abstract

this document is a technical reference for developers who are curious regarding how dbconfig-common works. before reading this document, it's highly recommended that you read the best practices for database applications draft, as the implementation design is based on rationale detailed in that document. if you are a developer looking to use dbconfig-common in your packages, you should read using dbconfig-common in debian packages first, as it will probably contain the information in which you're interested in a more condensed and accessible form.

### global maintainer script includes

- /usr/share/dbconfig-common/dpkg
- /usr/share/dbconfig-common/dpkg/$script
- /usr/share/dbconfig-common/dpkg/$script.$dbtype

for every maintainer script (.config, .postinst, et c) there are hunks 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 a generic script and a database-specific script. that is, you will find scripts named:

- /usr/share/dbconfig-common/dpkg/postinst
- /usr/share/dbconfig-common/dpkg/postinst.mysql

these scripts are sourced (not executed), so the lines in the package maintainer scripts should look like this

    #!/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 code ...

Note the arguments passed when sourcing the script.

### per-package database installation code

- /usr/share/dbconfig-common/data/$package/install/$dbtype
- /usr/share/dbconfig-common/data/$package/install-dbadmin/$dbtype
- /usr/share/dbconfig-common/scripts/$package/install/$dbtype

  the skeletons for the underlying databases are found under this directory, in per-package subdirectories, underneath which are files specific to each of the individual supported database types. these scripts do not need to include the code necessary for creating database users or the databases themselves (this is taken care of elsewhere), only the data used to create the necessary tables and/or otherwise populate the database is needed here.

  ### per-package database upgrade code

- /usr/share/dbconfig-common/data/$package/upgrade/$dbtype
- /usr/share/dbconfig-common/scripts/$package/upgrade/$dbtype
- /usr/share/dbconfig-common/data/$package/upgrade/$dbtype/$vers
- /usr/share/dbconfig-common/scripts/$package/upgrade/$dbtype/$vers

  upgrades are probably the most complicated part of this common infrastructure. often in the life of a database application the underlying database needs to be altered in some way. in this implementation, for every file that matches the form

      /usr/share/dbconfig-common/data/$package/upgrade/$dbtype/$vers

  if $vers is more recent than the most recently configured version of the package (as passed to $2 in the postinst), then they are applied, in sorted order.

  ### global and per-package configuration

  - /etc/dbconfig-common/config
  - /etc/dbconfig-common/$package.conf

  config contains the default global settings to be used during configuration.

  $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.

  all of these files are in a shell-script include format, such that they can be easily read and written by the common configuration scripts. they're generated and maintained via ucf, so this setup should be fairly friendly to the admin who wants to manually edit the files.