mdbtools and the long business of reading Access files on Linux

Reading Access files without a Windows box

MDB Tools is a set of programs to help you extract data from Microsoft Access files in various settings, and the project description says it plainly, read Access databases on Unix-like systems. The topics carry the format names, mdb and accdb, and the ODBC driver tag is there because the driver is one of the components.

The problem it solves is one that recurs in data work. Access is a format that outlived its tool, because a great many organisations still have years of operational data sitting in .mdb or .accdb files, and the tools to read those files are Windows tools. Moving that data to a Linux analytics box or a PostgreSQL loader means either running a Windows machine in the middle or finding something that parses the format natively. This is that something.

The implementation is C, and the repository layout says the project is serious software rather than a weekend script. There is a configure.ac, a Makefile.am, an autotools build with an m4/ directory of macros, a tests/ directory, a test_script.sh and a test_sql.sh, an api_docx/ directory for the API documentation, build-aux/, and CI on both GitHub Actions and AppVeyor. There is also an oss-fuzz integration, which is the badge at the top of the README and a meaningful signal for a parser of a binary format: fuzzing a file format parser is how you find the crashes that a malformed Access file would otherwise cause in someone else's tool.

The audience is an engineer or data engineer who has to get data out of Access files on a Unix host, whether by hand, from a shell script, or through a driver.

A library, a SQL engine, and eleven utilities

The components section of the README divides the project into three parts, and the division is the design.

libmdb is the core library that allows access to MDB files programmatically, with the complete API declared in include/mdbtools.h.in. libmdbsql builds on libmdb to provide a SQL engine, described as Jet, since that is the name Access used for its own query engine, and its API is in include/mdbsql.h. The third part is the command line utilities, and the table of them is the most useful page in the README for a new user.

The utilities split by job. mdb-ver prints the version, JET 3 or 4, of an mdb file, which is the first thing you want to know about a file you have been given. mdb-schema prints DDL for a table. mdb-export exports a table to CSV or SQL, mdb-json exports a table to JSON, and mdb-sql is a simple SQL engine, also used by the ODBC driver and by gmdb. mdb-tables is a dump of table names to be used with shell scripts, and mdb-count is a row count for shell scripts and ETL pipelines. mdb-queries lists and prints the queries stored in the database, which is how you find out that a .accdb file contains saved queries you could execute rather than just tables.

Four entries are marked deprecated, mdb-hexdump, mdb-array, mdb-header and mdb-parsecsv, and the list also names several debugging tools that are not installed on the host system, prcat, prkkd, prtable, prdata and prole, for dumping catalogs, design view data, table definitions and OLE columns. Those are the tools you use when the parser is confused, which is a sign the project expects to be extended by people who need to understand the file format.

Writing is experimental, and the README says where the line is

The src/util directory also builds mdb-import, which imports CSV data into an existing table, and the README handles it with unusual care. Write support in libmdb is experimental, for example tables with indexes are not handled correctly, so mdb-import is not installed and has no installed man page. You should run it from the build tree at src/util/mdb-import, at your own risk, and only on a copy of your database.

That is a clear boundary and a reasonable one. A parser for a binary file format that has no official documentation is already a reverse engineering effort, and write support multiplies the failure modes, because a bad write corrupts data rather than merely failing to read it. The indexed table caveat is the specific one to check, since a table with an index is a normal thing to have.

The distinction between the read tools and the write tool is also reflected in the packaging. The read utilities are installed with man pages, and mdb-import is not, so the default install gives you a way to look at an Access file and a way to move data out of it, and nothing that will modify one.

For a team, the practical reading is that MDB Tools is a safe extraction tool and an unsafe migration tool. A one way pipeline, Access to CSV to a real database, is what the project is built for.

The ODBC driver and the driver manager choice

The ODBC component is a driver for use with the unixODBC or iODBC driver manager, and the README names the payoff directly, that it allows one to use MDB files with PHP for example. That is the case that justifies the component existing, because it turns an Access file into something an ordinary application can query through a standard interface rather than a file you have to export first.

The driver manager is a real choice rather than a detail. The build needs unixodbc-dev, version 2.2.10 or above, or iODBC, and the configure flags are mutually exclusive, with --with-unixodbc specifying the location of the unixODBC driver manager and --with-iodbc doing the same for iODBC. The installed artefacts are a driver at /usr/local/lib/odbc/libmdbodbc.so and a Unicode capable variant at /usr/local/lib/odbc/libmdbodbcW.so.

The second half of the dependency is the SQL engine, because the ODBC driver needs it. The SQL engine is built on bison and flex, and if either is missing or bison is too old, configure prints a warning and disables the SQL engine, and fails if the ODBC driver was requested. That is a sensible failure mode, since an ODBC driver without a query engine is not much of a driver.

The GUI is a separate project. gmdb2 is the Gnome MDB file viewer and debugger, recently ported to GTK+3 and moved to its own repository at mdbtools/gmdb2, so the C library and the tooling live here and the desktop application does not.

Building it, and the macOS bison problem

Installing a released package is the easy path. Debian has apt install mdbtools, macOS has brew install mdbtools, and MacPorts has port install mdbtools. Building from source needs a few more steps, and the README is precise about them.

You need libtool, automake, autoconf 2.64 or later and pkg-config, whose pkg.m4 macros are needed when generating configure. GNU gettext is explicitly not required, because the gettext macros used for iconv detection are included in the m4/ directory, and if autopoint happens to be installed, autoreconf -i will run it and refresh those files with the system copies.

The generated build needs the configure script, which a Git clone does not have:

autoreconf -i -f
./configure
make

The SQL engine needs bison 3.0 or later and flex, and the ODBC driver needs unixodbc-dev or iODBC as described earlier. Building man pages needs GNU awk.

The macOS note is the one that will bite you, and it is a good example of a portability problem stated precisely rather than vaguely. The system bison on macOS is 2.3, so a newer one has to be installed, for example with Homebrew or MacPorts, and configure pointed at it, in the form YACC=/opt/homebrew/opt/bison/bin/bison ./configure. Without that, the SQL engine is disabled and the tool set is quietly smaller than the documentation implies.

There is also a cross compilation recipe for Windows, with ./configure --host=x86_64-w64-mingw32 --disable-shared --enable-static, which is how a Unix project of this kind reaches the platform its data format comes from.

GLib is optional, and the two ODBC drivers cannot coexist

Two configure details are worth knowing before you build.

The first is GLib. By default MDB Tools is linked against the copy of GLib that pkg-config returns, and you can point at a different GLib installation with the GLIB_CFLAGS and GLIB_LIBS environment variables. Or you can disable GLib entirely with the --disable-glib flag, in which case MDB Tools uses an internal implementation of GLib's functions. For a library that will be deployed on many machines, the ability to drop the external dependency is useful, and the ability to build without it is what makes a static, self contained build possible.

The second is the ODBC driver manager, where --with-unixodbc and --with-iodbc are mutually exclusive. That is a constraint of the driver manager rather than of the parser, but it is the kind of thing that produces a confusing configure failure rather than an obvious one, so it is good that the README says it in one sentence.

A complete install is a single additional flag, with ./configure --with-unixodbc=/usr/local, and the README notes that this requires bison, flex and unixODBC to be present.

After a successful build the library is in src/libmdb, as libmdb.so or libmdb.a depending on the configuration, and the utilities are in src/util. Installation is a make install run as root, to /usr/local by default.

Two licences in one tree, and a stable tag on a moving branch

The licence arrangement is the kind of detail that matters if you are linking against this code. Files in libmdb, libmdbsql and libmdbodbc are licensed under LGPL, while the utilities and the GUI program are under the GPL, with the texts in COPYING.LIB and COPYING respectively. So a proprietary application can link the libraries under the LGPL terms, while the command line tools are copyleft.

The version history explains the shape of the project. v1.0.0-beta7 was published on 2021-09-29, v1.0.0 on 2021-10-24 and v1.0.1 on 2024-12-26, so the 1.0 line has been stable for years, with the beta phase in front of it. The default branch is dev, and the last push was on 2026-10-18, so development continues on a branch that is not the released tag.

That is a sensible arrangement for a tool whose upstream dependency, the Access file format, effectively stopped changing years ago but which still gets ported to new platforms and rebuilt against new toolchains.

For an adopter, the practical judgement is simple. If you need to read Access data on Linux, this is the tool that does it, the utilities cover the common cases, and the ODBC driver covers the rest. If you need to write to those files, the project itself does not promise that, and the copy first instruction in the README is there for a reason.

Editorial conclusion

Adopt mdbtools if you have Access or.accdb files on a machine that does not run Windows, and you need to read them, script against them or expose them to another application through ODBC. Do not adopt it as a migration tool you can trust with writes, because the write support is experimental and the README says so in plain language. Verify three things first: that the SQL engine builds in your environment, since a missing or old bison silently disables it and a missing one fails the ODBC build outright, that you point configure at a newer bison on macOS, where the system version is 2.3, and that you copy the database before running mdb-import, because the tool handles indexed tables incorrectly. The last push was on 2026-10-18 on the dev branch and the newest release is v1.0.1 from 2024-12-26.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. mdbtools/mdbtools on GitHub
4. README
5. Releases