Register an ODBC Driver Safely in odbcinst.ini

An application cannot find its ODBC driver, and the fix almost always lives in one small file: odbcinst.ini. You will add a named driver entry to /etc/odbcinst.ini, check that its shared-library paths are real, and know how an application refers to the entry. The examples use unixODBC 2.3.12, matching the unixodbc-common package and installed odbcinst.ini(5) manual on this machine.

• Time: about fifteen minutes if the driver package is already installed.
• You need: shell access, the driver library supplied by your database vendor, and permission to edit the system configuration.
• Note: editing /etc/odbcinst.ini needs elevated privileges. Do not guess a driver path from a blog post: library locations differ between distributions, architectures and driver packages.

1. Check the installed files and package version

Start with read-only checks. This confirms the configuration file you are about to change and records the local unixODBC version:

$ ls -l /etc/odbcinst.ini
$ dpkg-query -W -f='${Package} ${Version}\n' unixodbc-common unixodbc 2>/dev/null || true
$ command -v odbcinst || true

On this host the package version is 2.3.12-1ubuntu0.24.04.1. The odbcinst command is not present here, because the command-line utility is packaged separately from the installed manual. If it is available on your system, the manual recommends it for installing a template; otherwise, a careful manual edit is just as valid.

$ test -r /path/to/vendor-driver.so && echo "driver library is readable"
$ file /path/to/vendor-driver.so

Replace the placeholder with the path supplied by your driver package. A readable file is not proof every dependency loads, but a missing file guarantees failure later.

2. Preserve the current configuration

Before making a system-wide change, create a timestamped backup. This is an elevated command, because the file belongs under /etc:

$ sudo cp --preserve=mode,ownership,timestamps /etc/odbcinst.ini \
    "/etc/odbcinst.ini.backup.$(date +%Y%m%d-%H%M%S)"

Record the backup name, or list it explicitly:

$ ls -l /etc/odbcinst.ini.backup.*

Do not use shell redirection directly on the live file: a failed command or a mistyped path can truncate it. The backup is your recovery point if an application later stops finding a driver.

3. Add one named driver section

Use an editor with elevated privileges and add a section whose name is stable and easy to type. That section name is the value an ODBC data-source configuration will later use as its Driver value:

[Example Vendor ODBC]
Description = Example Vendor ODBC driver
Driver      = /path/to/vendor-driver.so
Setup       = /path/to/vendor-setup.so
FileUsage   = 1

For example:

$ sudoedit /etc/odbcinst.ini

• Description is a human-readable label.
• Driver names the actual driver library.
• Setup names the optional setup library used by configuration tools. Keep FileUsage only when the driver documentation supplies it, and copy the driver-specific value exactly. Some drivers instead need architecture-specific Driver64 or Setup64 entries.

Do not copy the PostgreSQL paths from the manual as if they were universal. Its example uses /usr/lib/psqlodbcw.so and /usr/lib/libodbcpsqlS.so, but your distribution may install different names or multi-architecture paths.

4. Validate the section before using it

Read back only the relevant section and check every referenced file. None of these commands change configuration:

$ awk '/^\[Example Vendor ODBC\]/{show=1} show{print} show && /^\[/{seen++} seen > 1{exit}' /etc/odbcinst.ini
$ test -r /path/to/vendor-driver.so && echo "driver path OK"
$ test -r /path/to/vendor-setup.so && echo "setup path OK"

The section output should contain the name you chose and the paths you intended. If a setup library is not supplied by the vendor, remove that line rather than invent one. A driver manager may load the driver later, when an application connects, so this check catches configuration mistakes but is not a complete connection test.

When odbcinst is installed, its template workflow is the documented alternative. Put the same section in a separate template file, then run the command as an administrator:

$ sudo odbcinst -i -d -f /path/to/template.ini

That command changes the system driver registry. Review the template first and keep the backup. Do not run it repeatedly without checking what it adds.

5. Refer to the driver from a data source

An ODBC data-source configuration refers to the section by name, not by repeating the shared-library path:

[Reporting]
Driver = Example Vendor ODBC

The name must match the section header exactly, including spaces and capitalisation. The driver section belongs in odbcinst.ini; a data-source section belongs in odbc.ini or the application-specific configuration. Keeping those roles separate makes a missing driver easier to diagnose.

6. Enable tracing only for a bounded investigation

The special [ODBC] section controls unixODBC driver tracing. Enable it only when you need diagnostic output, and choose a path that is not writable by multiple users:

[ODBC]
Trace = Yes
TraceFile = /var/tmp/odbc-trace.log

Trace is enabled by a value containing 1, y, yes or on, in any case. TraceFile does nothing unless tracing is enabled; if omitted, the documented default is /tmp/sql.log. Traces can contain connection details and query data, so protect the file and remove the setting after the incident.

To undo this diagnostic change, edit the section, remove or disable both lines, then remove the trace file only after checking that no process is still writing it. Do not leave tracing enabled on a busy or sensitive system.

Common failures and recovery

• Driver not found. The Driver value is a path, not a package name. Check it with ls -l and compare it with the vendor package contents.
• Data source cannot find the driver. Check that its Driver value is the exact section name, not the library path.
• Setup errors. A setup library and a driver library are separate files. Follow the vendor template and do not point both keys at an arbitrary shared object.
• Unexpected behaviour after an edit. Restore a known-good backup with sudo cp --preserve=all /etc/odbcinst.ini.backup.YYYYMMDD-HHMMSS /etc/odbcinst.ini, replacing the placeholder with the exact backup file you created.