Declare Perl DBD dependencies with dh_perl_dbi

You will make a Debian Perl package declare the DBI driver ABI dependency it needs, then check that the generated package metadata contains it. Allow about 20 minutes for a small package that already has a working debian/ directory. The examples use the installed libdbi-perl package, version 1.643-4ubuntu0.1.

dh_perl_dbi is for packages that use a DBD module through DBI's binary interface. It adds a dependency to the ${perl:Depends} substitution. It is not a general dependency helper for every Perl program and is not needed merely because code uses the DBI Perl module.

1. Check whether this helper applies

Inspect the package's Perl code and its dependencies first. Use this helper when the package uses a database driver such as a DBD module and the driver must remain compatible with the DBI binary interface. A package that only imports or calls DBI, without using a DBD binary interface, should not add this helper just for that reason.

The installed program is a debhelper command, so it normally runs as part of a package build rather than as a standalone application:

$ command -v dh_perl_dbi
/usr/bin/dh_perl_dbi
$ dpkg-query -W -f='${Package} ${Version}\n' libdbi-perl
libdbi-perl 1.643-4ubuntu0.1

Checkpoint: you should have a package directory containing debian/control and debian/rules. Do not run the helper directly from an arbitrary source tree and expect it to discover a package.

2. Add the modern sequence package

The simplest integration is to build-depend on dh-sequence-perl-dbi. Add it to the existing Build-Depends field in debian/control. Keep the other build dependencies already required by the package.

Source: example-perl-dbd
Section: perl
Priority: optional
Maintainer: Package Maintainers <[email protected]>
Build-Depends: debhelper-compat (= 13),
 dh-sequence-perl-dbi,
 libdbi-perl
Standards-Version: 4.7.0

Package: example-perl-dbd
Architecture: all
Depends: ${perl:Depends}, ${misc:Depends}
Description: Example Perl package using a DBD module
 An example package description.

The important parts are the sequence package in Build-Depends and ${perl:Depends} in the binary package's Depends field. The sequence package arranges for dh_perl_dbi to run after dh_perl; it does not replace the normal Perl dependency substitution.

Package names in Build-Depends are build-time requirements. They make the helper available while building. The dependency added through ${perl:Depends} is runtime package metadata, which is what protects users of the built package.

3. Keep the rules file on the standard debhelper path

With the sequence package selected, a normal debhelper rules file is enough:

#!/usr/bin/make -f
%:
	dh $@

Make the file executable if it is not already:

$ chmod +x debian/rules
$ sed -n '1,12p' debian/rules
#!/usr/bin/make -f
%:
	dh $@

Checkpoint: do not add both the sequence package and an unrelated, duplicate invocation unless you have a specific reason. Running the same dependency step twice does not make the dependency more correct and can make build logs harder to interpret.

4. Use the legacy addon form only when required

Older packaging arrangements can enable the addon explicitly in debian/rules:

#!/usr/bin/make -f
%:
	dh $@ --with perl_dbi

The installed manual documents this form and also documents the sequence package as the alternative available since libdbi-perl 1.642-1. For a new package, prefer one consistent form. If maintaining an older branch that already uses --with perl_dbi, change it as a separate, tested packaging update rather than mixing both forms in one change.

The word perl_dbi in --with perl_dbi is the debhelper addon name. It is not the name of a Perl module to add to the package's runtime dependencies.

5. Build and inspect the generated dependency

Build the package with your ordinary Debian build command. Building from a source tree can execute maintainer scripts and compile code, so review the package before using elevated privileges. A normal unprivileged build is preferred; use sudo only for a package installation or another step that genuinely needs system access.

$ dpkg-buildpackage -us -uc
...
dh_perl_dbi ...
...

The exact build log includes other debhelper steps, and the command may produce the binary package one directory above the source tree. Inspect the resulting Debian archive rather than relying only on the presence of the helper in the log:

$ dpkg-deb -f ../example-perl-dbd_*.deb Package Version Depends
Package: example-perl-dbd
Version: 0.1-1
Depends: perl-dbdabi-94, perl-base (>= 5.38.2-3.2ubuntu0.6), ...

On this installed release, the helper's executable adds perl-dbdabi-94 to perl:Depends. The manual describes that value as a perl-dbdabi-* dependency because the ABI suffix is release-specific. Your package may show other automatically generated Perl dependencies as well. The check you need is that the appropriate perl-dbdabi-* entry is present and is not hidden by a missing ${perl:Depends} field.

6. Diagnose the usual mistakes

If the dependency is absent, first confirm that the binary stanza, not only the source stanza, contains Depends: ${perl:Depends}. Then check that dh-sequence-perl-dbi is in Build-Depends, or that the rules file uses the documented --with perl_dbi form. Rebuild after changing either file; an old .deb cannot show the effect of a new rules file.

If the build says that dh_perl_dbi or its sequence package is unavailable, the build environment is missing the package that supplies the helper. Fix the declared build environment through the normal package source and rebuild. Do not copy /usr/bin/dh_perl_dbi into the source tree: its behaviour depends on debhelper's Perl libraries and substitution machinery.

If the package only uses DBI and no DBD binary interface, remove this integration rather than adding a broad dependency as a precaution. Conversely, do not remove the generated ABI dependency from a package that really loads DBD modules. That dependency is part of the package's compatibility contract.