README

DB2 for IBM iSeries Laravel Driver

This package lets you use Laravel's query builder and Eloquent with DB2 for IBM iSeries by extending the Illuminate Database component of the Laravel framework. It targets Laravel 12 exclusively and is actively maintained.

Lineage

This driver has three generations behind it — each fork picked up where the previous one had stalled:

cooperl22/laravel-db2 — the original driver.
BWICompanies/db2-driver — forked from (1), renamed the namespace and continued development.
beryildiz/db2-driver (this repository) — forked from (2). Rewritten for Laravel 12 compatibility (constructor and method signatures across the schema layer changed in Laravel 11/12 and made the previous version fatal on class load), with an expanded test suite, static analysis via Larastan, and the limitations below turned into explicit, documented exceptions instead of silently wrong SQL. See CHANGELOG.md for the full list of breaking changes and fixes.

Requirements

PHP ^8.2
IBM i 7.2 or later (for Schema::dropIfExists())
Laravel 12 (illuminate/* ^12.0) — this version supports exclusively Laravel 12, see CHANGELOG.md
PHP PDO_ODBC extension
IBM i Access ODBC Driver (Windows & Linux)

Installation

Install the package via composer:

composer require beryildiz/db2-driver

Add a new connection in database.php:

Note: You can specify the connection name, but the driver must be 'db2'

'myDB2Connection' => [
    'driver'        => 'db2',
    'driverName'    => '{IBM i Access ODBC Driver}',
    'host'          => env('DB_HOST'),
    'username'      => env('DB_USERNAME'),
    'password'      => env('DB_PASSWORD'),
    'database'      => env('DB_DATABASE'),
    'prefix'        => '',
    'schema'        => env('DB_SCHEMA'),
    'port'          => env('DB_PORT', 50000),
    'date_format'   => 'Y-m-d H:i:s', // or 'Y-m-d H:i:s.u' / 'Y-m-d-H.i.s.u'
    'offset_compatibility_mode' => true,
    'odbc_keywords' => [
        // optional, see the full default list below
    ],
    'options' => [
        PDO::ATTR_CASE             => PDO::CASE_LOWER,
        PDO::ATTR_EMULATE_PREPARES => false,
        PDO::ATTR_PERSISTENT       => false,
    ]
],

Note: Be sure to define the appropriate keys in .env.

odbc_keywords defaults (click to expand)

'odbc_keywords' => [
    'SIGNON'                => 3,
    'SSL'                   => 0,
    'CommitMode'            => 0,
    'ConnectionType'        => 0,
    'DefaultLibraries'      => '',
    'Naming'                => 1,
    'UNICODESQL'            => 0,
    'DateFormat'            => 5,
    'DateSeperator'         => 0,
    'Decimal'               => 0,
    'TimeFormat'            => 0,
    'TimeSeparator'         => 0,
    'TimestampFormat'       => 0,
    'ConvertDateTimeToChar' => 0,
    'BLOCKFETCH'            => 1,
    'BlockSizeKB'           => 32,
    'AllowDataCompression'  => 1,
    'CONCURRENCY'           => 0,
    'LAZYCLOSE'             => 0,
    'MaxFieldLength'        => 15360,
    'PREFETCH'              => 0,
    'QUERYTIMEOUT'          => 1,
    'DefaultPkgLibrary'     => 'QGPL',
    'DefaultPackage'        => 'A /DEFAULT(IBM),2,0,1,0',
    'ExtendedDynamic'       => 1,
    'QAQQINILibrary'        => '',
    'SQDIAGCODE'            => '',
    'LANGUAGEID'            => 'ENU',
    'SORTTABLE'             => '',
    'SortSequence'          => 0,
    'SORTWEIGHT'            => 0,
    'AllowUnsupportedChar'  => 0,
    'CCSID'                 => 1208,
    'GRAPHIC'               => 0,
    'ForceTranslation'      => 0,
    'ALLOWPROCCALLS'        => 0,
    'DB2SQLSTATES'          => 0,
    'DEBUG'                 => 0,
    'TRUEAUTOCOMMIT'        => 0,
    'CATALOGOPTIONS'        => 3,
    'LibraryView'           => 0,
    'ODBCRemarks'           => 0,
    'SEARCHPATTERN'         => 1,
    'TranslationDLL'        => '',
    'TranslationOption'     => 0,
    'MAXTRACESIZE'          => 0,
    'MultipleTraceFiles'    => 1,
    'TRACE'                 => 0,
    'TRACEFILENAME'         => '',
    'ExtendedColInfo'       => 0,
],

See DB2 Connection String Keywords for what each key does.

Limitations

This driver targets the query builder and Eloquent. Schema/migration support is functional but deliberately narrow — DB2 for IBM i differs substantially from the databases Laravel ships drivers for. Everything listed below fails with an explicit exception rather than producing silently wrong SQL.

Schema introspection — not supported

Schema::getTables(), getViews(), getTypes(), getColumns(), getIndexes(), getForeignKeys(), getSchemas() and therefore the db:show and db:table commands throw a RuntimeException. Use Schema::hasTable() and Schema::getColumnListing(), which are supported.

Dropping everything — not supported

Schema::dropAllTables(), dropAllViews() and dropAllTypes() throw a LogicException, which means migrate:fresh and db:wipe are unavailable. DB2 for IBM i has no global foreign-key switch and no DROP TABLE ... CASCADE, so a partial implementation would fail halfway through and leave the schema in an undefined state. Use migrate:refresh (which runs your down() methods) instead.

Other unsupported operations

Operation	Behaviour
`schema:dump`, `migrate --schema-path`	`BadMethodCallException` (no `getSchemaState()`)
`Schema::withoutForeignKeyConstraints()`	not supported by DB2 for i
`Schema::createDatabase()` / `dropDatabaseIfExists()`	`LogicException`
`upsert()`, `insertOrIgnore()`	`RuntimeException`
`inRandomOrder()`	emits `RANDOM()`; DB2 for i uses `RAND()`
JSON column operators (`where('col->key')`)	`RuntimeException`
`DB::pretend()` / raw SQL in the query log	unreliable — PDO_ODBC does not implement `quote()`

Unsupported column types

DB2 for IBM i has no equivalent that maps cleanly, so these throw a BadMethodCallException: json, jsonb, ulid, tinyInteger, mediumInteger, tinyText, year, ipAddress, macAddress, set, geometry, vector, computed.

Supported: char, string, text, mediumText, longText, bigInteger, integer, smallInteger, numeric, float, double, decimal, boolean, enum, date, dateTime, time, timestamp, binary, uuid.

Requirements and caveats

The schema key in your connection config is effectively required — hasTable() and getColumnListing() resolve unqualified table names against it.
Schema::dropIfExists() emits DROP TABLE ... IF EXISTS and therefore needs IBM i 7.2 or later.
$table->index($columns, 'name') honours the given index name. Releases before the Laravel 12 rewrite silently replaced it with a generated one, so index names may differ from what an older version of this package created.

Testing & Contributing

Issues and pull requests are welcome. Before opening a PR, make sure the following pass locally (all three are wired up as composer scripts and run in CI):

composer format    # vendor/bin/pint
composer analyse   # vendor/bin/phpstan analyse
composer test      # vendor/bin/pest

Since this package talks to a real IBM i host over ODBC, most tests are unit tests against mocked connections/grammars rather than integration tests — there is no CI database. If you find a case that isn't covered, a failing test is the most useful part of a bug report.

beryildiz / db2-driver

Maintainers

Package info

Statistics

Security