Laravel Db2 Laravel Package

Getting Started

easi-power/laravel-db2 gives Laravel a first-class connection driver for IBM DB2 (LUW, z/OS) and IBM i / AS400, so you can use the query builder, Eloquent, and much of the schema builder against systems that Laravel doesn't support out of the box.

1. Install the package and a PHP extension. You need either ibm_db2 or pdo_odbc compiled/available in the runtime that serves the app (php -m | grep -i -E 'ibm_db2|odbc'). This is the single most common install failure — composer will succeed while the connection still refuses to open.
2. Add a connection in config/database.php using one of the package's driver names (db2, db2_odbc, db2_ibmi_odbc, db2_ibmi_ibmdb2 — confirm the exact string against the package README for your version). Host, database, username, password, and for IBM i the library list (i5_libl) or naming convention (i5_naming) options.
3. Smoke-test before modelling anything. DB::connection('ibmi')->select('select 1 from sysibm.sysdummy1'), or on IBM i, select * from qsys2.tables fetch first 5 rows only. If that works, everything else is ordinary Laravel.
4. First real use case is almost always read-only reporting: an Eloquent model with protected $connection = 'ibmi'; pointed at an existing ORDERS/CUSTOMERS table, exposed through a controller or a queued export.

v14.3.0 adds an OpenVMS RMS driver (via a COBOL gateway) alongside the existing DB2/IBM i drivers. It is a genuinely different beast: RMS files are record-oriented flat files, not a SQL database, and the gateway is the translation layer. Treat it as an ingestion source rather than a primary application database, and confirm the registered driver name and required gateway host/port options in the README before wiring it into config/database.php.

Implementation Patterns

Keep the legacy system as a non-default connection. Leave DB::connection() pointing at MySQL/Postgres and reach for the DB2 connection explicitly (Model::on('ibmi'), DB::connection('ibmi')->table(...)). This keeps migrations, sessions, and queues on infrastructure you control.

Eloquent models need honesty about keys and timestamps. Most IBM i tables have composite or non-incrementing keys and no created_at/updated_at:

protected $connection = 'ibmi';
protected $table = 'ORDERS';
protected $primaryKey = 'ORDNO';
public $incrementing = false;
protected $keyType = 'string';
public $timestamps = false;

Use raw SQL where the dialect bites. The query builder covers most reads, but DB2/IBM i specific syntax (FETCH FIRST n ROWS ONLY, WITH UR isolation clauses, SYSIBM.SYSDUMMY1) is best expressed with selectRaw/whereRaw rather than fighting the grammar.

Read with cursor() or chunkById() for large extracts. Offset pagination against a DB2 table with millions of rows will fall over; keyset pagination on the primary key is the reliable pattern.

Migrations: create is fine, alter is where it hurts. Use the schema builder for greenfield tables, but expect to drop to DB::statement() for anything involving constraints, identity columns, or reorganizing existing files. Many teams only use the package to read and manage DDL out-of-band.

Transactions work via DB::connection('ibmi')->transaction(fn () => ...), but verify journaling/commitment control is enabled on the IBM i side — without it, rollback silently does nothing.

For the new OpenVMS RMS driver, the practical pattern is a scheduled job that reads a record set through the gateway and normalises it into your own database. Expect fixed-width or delimited records, EBCDIC-derived text, and packed/zoned decimal fields that need decoding in a cast or accessor:

protected $casts = ['AMOUNT' => 'decimal:2']; // after unpacking in an accessor

Run these imports on a queue with an explicit timeout, and store a watermark (last record key or file timestamp) so re-runs are idempotent.

Testability: hide the connection behind a repository interface and bind a SQLite/array fake in tests. Hitting a real DB2 box in CI requires a containerised db2_community image plus the ibm_db2 extension — worth doing for one integration suite, not for every test.

Gotchas and Tips

• Driver name vs. extension mismatch. db2_ibmi_ibmdb2 requires the ibm_db2 extension; the _odbc variants require pdo_odbc with a configured DSN. Choosing the wrong combination produces connection errors that look like network problems.
• php artisan config:clear after every config edit, especially in containerised deploys where config:cache runs at build time and bakes in stale credentials.
• IBM i identifier case. Unquoted identifiers fold to upper case; quoted ones don't. Mixing quoted and unquoted names in the same model is a reliable source of "table not found".
• Library lists matter. A table visible in one job's library list is invisible to another. Pin i5_libl in the connection config rather than relying on the user profile default.
• Long-running workers leak connections. Call DB::purge('ibmi') in a Queue::looping hook or after N jobs; DB2 gateways often cap concurrent sessions.
• Unsupported Laravel features: schema:dump, some upsert/insertOrIgnore paths, JSON column types, and full-text search helpers. Check before designing around them.
• Date/time handling. DB2 timestamp precision and IBM i's DATE/TIME separation can produce surprising Carbon values; cast explicitly and normalise timezone at the boundary.
• Debugging: DB::connection('ibmi')->enableQueryLog() plus DB::getQueryLog() gives you the SQL and bindings; the underlying ODBC/ibm_db2 error text is usually in the exception message — read it verbatim, it names the SQLCODE.
• The COBOL gateway is a new, niche surface. Assume it needs its own deployment, credentials, and network path; that it may be single-threaded or slow; that it offers no transactional semantics across multiple file reads. Put a health check on it, log raw responses on failure, and keep the decode logic isolated so a gateway quirk doesn't leak into your domain model. Since this driver is brand new in v14.3.0, pin the version and exercise it in a staging environment before trusting it in production.

Extension points: the package registers its drivers through the DB service provider, so a custom Connection/Connector subclass bound in your own provider (via DatabaseManager::extend) is the clean way to add retry, logging, or a bespoke DSN builder without forking.