AccessConverter

Converts Microsoft Access databases (.mdb, .mde, .accdb, .accde, .accdr) to MySQL/MariaDB dumps, SQLite and JSON, on Linux, Windows and macOS.

• Exact values, or a report that says otherwise. Every value round-trips exactly: currency and decimals keep their scale, dates keep their precision, bytes stay bytes, NULL stays NULL. Anything that can't be exported exactly is named in the conversion report, with a reason and a count.
• The schema, as far as the target can enforce it. Primary keys, unique and plain indexes, foreign keys with their cascade rules, NOT NULL, defaults, validation rules as CHECK constraints, and descriptions as comments. A constraint is written only when the data already satisfies it and the target enforces it no more strictly than Access did, so the data Access accepted always imports.
• Every Access version Jackcess reads: Access 97 through Microsoft 365, including password-protected and encrypted databases, and Access 97 files in any Windows code page (Greek, Cyrillic, Japanese, …).
• Verifiable. accessconverter verify reads the output back and compares its schema and every value with the Access database.

AccessConverter is built on Jackcess. The online converter at lytrax.io runs it.

Upgrading from 2.x? The command line, the outputs and the result format all changed: see Migrating from AccessConverter 2.

What changed in each release is in the changelog.

Runtime image (no Java needed). Download the zip for your platform from the releases, unzip it anywhere and run bin/accessconverter (bin\accessconverter.cmd on Windows):

Each holds its own Java runtime and never uses an installed one. On macOS, a zip downloaded with a browser is quarantined; clear that once with xattr -dr com.apple.quarantine accessconverter-<version>-macos-*. To pass JVM options (a larger heap, say), set ACCESSCONVERTER_JAVA_OPTS=-Xmx4g.

Jar. With Java 21 or later: java -jar accessconverter-<version>.jar ….

Locale. Java takes the encoding of file names and of standard output from the locale. Under a POSIX locale (LANG unset or C, common for services and cron jobs), a file whose name isn't ASCII can't be opened and non-ASCII text on standard output turns into ?. Run AccessConverter with a UTF-8 locale, such as LANG=C.UTF-8; the container image sets one.

Container. ghcr.io/clytras/accessconverter:3 works on the current directory, mounted at /data:

docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/data" ghcr.io/clytras/accessconverter:3 convert Shop.accdb --to sqlite

To build the image yourself, from a clone with nothing but Docker installed: docker build -t accessconverter ., then run it the same way with accessconverter in place of ghcr.io/clytras/accessconverter:3. The jar is compiled inside the build, identical byte for byte to the released one for the same version.

Checking a download. Every release has SHA256SUMS (sha256sum -c SHA256SUMS --ignore-missing) and a build-provenance attestation (gh attestation verify <file> --repo clytras/AccessConverter).

From source. ./mvnw -B package builds target/accessconverter-<version>.jar; ./mvnw -B verify also runs the tests.

accessconverter convert Shop.accdb --to sqlite            # Shop.sqlite3
accessconverter convert Shop.accdb --to mysql             # Shop.sql, for MySQL 8.0.13 or later
accessconverter convert Shop.accdb --to mariadb           # Shop.sql, for MariaDB 10.11 or later
accessconverter convert Shop.accdb --to json              # Shop.json
accessconverter inspect Shop.accdb                        # what's in the database, and what the conversion will say
accessconverter verify  Shop.accdb Shop.sqlite3           # compare an output with its source

Each conversion prints a summary and writes the conversion report next to the output (Shop.sqlite3.report.json).

accessconverter convert <input> --to sqlite|mysql|mariadb|json [-o <output>] [options]
accessconverter inspect <input> [--profile] [--format text|json] [-o <file>]
accessconverter verify  <input> [<output>] [options]

-h/--help on any command lists its options; -V/--version prints the version; -v/--verbose logs Jackcess's warnings and prints stack traces on errors.

A database that can't be read prints one line on standard error, error: <file>: <reason>, and nothing on standard output.

Prints what AccessConverter reads from a database: tables, columns with their types and properties, keys, indexes (with the hidden ones Access adds folded in), relationships, and the issues a conversion would report. It writes nothing else.

accessconverter verify Shop.accdb Shop.sqlite3
accessconverter verify Shop.accdb Shop.json
accessconverter verify Shop.accdb --jdbc-url jdbc:mariadb://localhost:3306/shop --jdbc-driver mariadb-java-client-3.5.10.jar --db-user root

verify plans the conversion again from the source and compares the output with it: every table, column type, key, index, foreign key, default and CHECK, and every value (exact decimals, dates at their precision, bytes by SHA-256). Give it the same options the conversion used, since they decide what the output should hold (--tables, --exclude-tables, --no-profile, --include-hidden, --add-primary-key, --sqlite-strict, --sqlite-nocase, --sqlite-metadata, --collation, --binary, --ole-extract, --include-version-history, --password, --charset). It exits 0 when the output matches and 2 when it doesn't, listing each difference.

A MySQL or MariaDB output is the database the dump was imported into:

Without an output, verify <input> prints the source side: each table's row count and a digest of its rows.

Every conversion writes a JSON report (<output>.report.json, or --report <file>); --format-result json prints the same report on standard output.

{
  "format": "accessconverter-report",
  "formatVersion": 1,
  "tool": "accessconverter 3.1.0",
  "command": "convert",
  "options": { "to": "mysql", "binary": "inline", "collation": "utf8mb4_0900_as_ci", "…": "…" },
  "source": { "file": "Shop.mdb", "fileFormat": "V1997", "codePage": 1253, "charset": "windows-1253" },
  "outcome": "success-with-warnings",
  "tables": [ { "table": "Customers", "rowsRead": 8, "rowsWritten": 8 } ],
  "issues": [
    { "code": "CHECK_VIOLATED_BY_DATA", "severity": "warning", "table": "Orders", "object": "Quantity",
      "message": "no CHECK for the validation rule >0: 2 existing rows violate it, as Access allows",
      "count": 1, "samples": [ "(17); (41)" ] }
  ],
  "timings": { "extractMillis": 48, "planMillis": 30, "profileMillis": 47, "writeMillis": 19 }
}

• outcome is success, success-with-warnings or failed, matching exit codes 0, 1 and 2.
• tables has the rows read from Access and written to the output for each table; they differ only for a table that failed.
• Each issue has a code (stable, for scripts), a severity, the table and object (a column, index or relationship) it concerns, a message for people, a count, and samples: the primary keys of a few affected rows ((17); (41), or row 5 in a table without one), so you can find them in Access.
• info issues are decisions made the way Access would want them (a hidden index folded into the primary key, a name made legal for the target). warning issues are where the output differs from Access: read these. error issues mean the conversion failed.

The warnings you are most likely to meet:

--to mysql writes a dump for MySQL 8.0.13 or later (tested on 8.0 and 8.4), --to mariadb one for MariaDB 10.11 or later (tested on 10.11, 11.4 and 11.8). Import it with the server's own client:

mysql   -u root -p shop < Shop.sql      # MySQL
mariadb -u root -p shop < Shop.sql      # MariaDB

The database must exist, or convert with --database shop to have the dump create and use it. The dump sets everything it needs for its own session and restores it at the end: utf8mb4, strict SQL mode (so nothing is ever silently truncated or rounded), and foreign-key checks. Each table is loaded in one transaction, then the secondary indexes, CHECKs and foreign keys are added, so the server validates every constraint against the data. An import that prints nothing succeeded.

• Collation. Tables use utf8mb4_0900_as_ci (MySQL) or utf8mb4_uca1400_as_ci (MariaDB): case-insensitive and accent-sensitive like Access. Where a primary-key or unique column holds text these collations would compare more strictly than Access (some control characters, compatibility forms), that column and its foreign keys use utf8mb4_bin instead and the report says so. --collation utf8mb4_bin is also safe, but compares case.
• Large values. A value of more than 16 MiB needs a larger max_allowed_packet on the server and the client (mysql --max-allowed-packet=1G); --binary files keeps the bytes out of the dump.
• Yes/No is BOOLEAN, 1 for Yes (Access stores -1).
• Random AutoNumbers. An AutoNumber whose New Values are Random gets a random DEFAULT, as in Access: new rows get random 32-bit keys, never a counter that could run out. The server doesn't report that key back: LAST_INSERT_ID() and the client calls built on it (PHP's lastInsertId(), …) return 0, so an application that needs the new key must select the row. As in Access, a drawn value that is already taken fails the insert with a duplicate-key error; the report says how often that happens at the table's size.
• Time() defaults are the time of day on Access's day zero, 1899-12-30, because that is how Access stores a time-only value; an application that expects a bare time reads that date. The same holds in SQLite.

Check an import with verify --jdbc-url (see verify).

The output is a finished SQLite database. Every conversion runs foreign_key_check on it; --verify also runs integrity_check and compares every value with the source.

• Foreign keys are only enforced when the connection asks for it. SQLite ignores foreign keys unless each connection runs PRAGMA foreign_keys = ON; first. The file has them; your application has to switch them on.
• Dates are ISO-8601 text (2024-01-02 03:04:05, plus .fff when there are milliseconds), which sorts and compares correctly and works with SQLite's date functions.
• Currency and Decimal are exact: NUMERIC when every value has at most 13 digits, otherwise text (reported as DECIMAL_STORED_AS_TEXT; CAST(col AS REAL) makes it numeric).
• Text comparison. Access compares text ignoring case; SQLite's default doesn't. CHECKs and foreign keys that depend on it compare with NOCASE where they must; --sqlite-nocase makes every text column COLLATE NOCASE. SQLite's NOCASE only folds ASCII letters, so a validation rule whose data only complies when Greek, Cyrillic or other letters are compared ignoring case becomes no CHECK, and the report says so.
• AutoNumbers are INTEGER PRIMARY KEY AUTOINCREMENT when they are the primary key. A Random AutoNumber counts upward here, from its largest value: SQLite can only generate a key for such a column in sequence, and its 64-bit counter never runs out (AUTONUMBER_RANDOM_SEQUENTIAL).
• --sqlite-metadata adds _access_columns (each column's Access type, length, precision, Required, descriptions, format, default and validation rule as Access wrote them, and what it became), _access_relationships (every relationship, enforced or not, and whether it became a foreign key) and _access_export (the AccessConverter version and the source file, format and code page).
• Every file says who wrote it without an extra table: PRAGMA application_id is 0x41434356 ("ACCV") and PRAGMA user_version is the layout version, 1. A MySQL/MariaDB dump names the producer in its first comment line, and JSON in its producer property. No output records a time unless --stamp is given.

JSON holds the whole database: the schema (tables, columns with every Access property, keys, indexes and all relationships, including those Access doesn't enforce) and every value, spelled exactly. The format is documented in docs/json-format.md and published as a JSON Schema, accessconverter-json-v1.schema.json. The output streams, so a database of any size converts in little memory, and --json-layout ndjson gives one file per table for tools that read a row per line.

Access allows tables without a primary key, and by default the output has none for them either: AccessConverter never invents a key. Applications and frameworks that need one on every table can ask for it:

accessconverter convert Shop.accdb --to sqlite --add-primary-key            # a column named id
accessconverter convert Shop.accdb --to mysql  --add-primary-key=row_id     # or any name

Each table without a primary key gets an AutoNumber column, first in the table, that numbers the rows 1, 2, 3, … in the order Access stores them: INTEGER PRIMARY KEY AUTOINCREMENT in SQLite, INT AUTO_INCREMENT PRIMARY KEY in MySQL/MariaDB, so new rows get the next number. When the table already has a column of that name, the new one is named id_2 (and so on). MySQL allows only one AUTO_INCREMENT column per table: an AutoNumber the table already has keeps its values but stops generating them. The report lists every table that got a key (PRIMARY_KEY_ADDED). Tables with a primary key are left as they are. JSON doesn't need keys, so the option applies to the SQL targets only. To verify such an output, pass the same option to verify.

Binary and OLE Object values are exported as their exact stored bytes by default, whatever they hold. That can't fail and loses nothing. --binary decides where the bytes go:

--ole-extract also decodes each OLE object: its kind (package, embedded, link, compound or raw), its name (the file name of a packaged file, the program of an embedded object, the path of a link), its content type (from the bytes, never from a name) and its content (the packaged file, or the object's own bytes). In SQL they are four extra columns, <column>__kind, __name, __mime and __content; in JSON the value becomes an object. The raw bytes are always kept.

Attachments and multi-value columns become child tables in SQLite and MySQL/MariaDB, <Table>_<Column>, linked to the parent column by Access's own id with a cascading foreign key: attachments with file_name, file_type, file_data, file_size, file_url, file_timestamp and file_flags, multi-value columns with value. In JSON they are arrays inside the row. Version history of append-only memos is only written with --include-version-history.

AccessConverter opens databases encrypted by Access 2007 and later (RC4 CryptoAPI and Agile encryption) and Microsoft Money files, which need their password. Encoded Access 97–2003 files, and the "database password" of Access 97–2003, need none: that password only guards the file inside Access, doesn't encrypt it, and is reported as PASSWORD_NOT_REQUIRED. The password is given one of three ways:

• --password=<password> on the command line;
• --password alone: it is asked for without echo. Put it after the input, or the input is taken as the password; without a console, the prompt goes to standard error and the password is read from the first line of standard input;
• the ACCESSCONVERTER_PASSWORD environment variable, which keeps the password out of the process list.

The password is never printed or written to the report. A missing or wrong password for an encrypted database exits 2 with error: <file>: ….

Access 97 stores text in the Windows code page of the database's sort order, not in Unicode. AccessConverter reads the code page from the file's header, so Greek, Cyrillic, Central European, Japanese, Chinese, Korean, Thai and other Access 97 files convert without any option; the report's source.charset says which charset was used. If a file was made on a system whose code page doesn't match its header, --charset windows-1253 (or any Java charset name) overrides it. Access 2000 and later store Unicode, and ignore --charset with a warning.

Every byte is decoded as Windows, and so Access, decodes it. A few code pages (Greek 1253, Hebrew 1255, Baltic 1257, Thai 874) leave some bytes undefined. Windows turns those into private-use characters (U+E000 to U+F8FF), which map back to the same byte but show as blank in most fonts, so AccessConverter writes the same characters and reports each column that holds one (TEXT_PRIVATE_USE). A byte no charset can decode is written as U+FFFD and reported as TEXT_UNDECODABLE.

• Queries, forms, reports, macros and VBA modules. Jackcess doesn't read them, and they have no equivalent in the targets.
• Linked tables. Their data lives in another database; they are listed in the report (and in JSON's schema). For a table linked to another Access file, convert that back-end file directly; an ODBC link's data lives on its server.
• Access security (user-level permissions and workgroup files).

• --linked resolve: convert linked Access tables together with the database that links them, instead of converting the back-end file separately.
• --progress: progress on standard error during long conversions.

AccessConverter is released under the Apache License, Version 2.0, from 3.0.1 on; versions 2.x and earlier were released under the MIT License. The runtime images and the container image bundle third-party software under its own licenses: see NOTICE.