Declare Perl DBD Dependencies with dh_perl_dbi

A missing runtime dependency on a DBD driver is the kind of bug dh_perl_dbi exists to prevent. It makes a Debian Perl package declare the DBI driver ABI dependency it needs, then lets you check that the generated package metadata actually 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.

This helper 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 it 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

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, keeping the other build dependencies the package already needs.

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.

• Sequence package in Build-Depends. It arranges for dh_perl_dbi to run after dh_perl; it does not replace the normal Perl dependency substitution.
• ${perl:Depends} in the binary Depends field. That is what actually protects users of the built package.

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.

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

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 you are 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, and sudo is for a package installation or another step that genuinely needs system access, not for this.

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

The exact build log includes other debhelper steps, and the binary package may land one directory above the source tree. Inspect the resulting archive rather than relying on the helper's presence 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 too; the check you need is that the appropriate perl-dbdabi-* entry is present and not hidden by a missing ${perl:Depends} field.

6. Diagnose the usual mistakes

• Dependency absent? Confirm 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.
• Build says the helper or sequence is unavailable? The build environment is missing the package that supplies it. 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.
• Package only uses DBI, no DBD binary interface? Remove this integration rather than adding a broad dependency as a precaution.
• Package genuinely loads DBD modules? Do not remove the generated ABI dependency: it is part of the package's compatibility contract.