README

SQL Anywhere 17 database integration for Laravel applications.

This package provides a Laravel database connection, query grammar, schema grammar, and query processor for working with SAP SQL Anywhere 17 through PHP PDO/ODBC.

It is intended for Laravel applications that need to use SQL Anywhere while continuing to use Laravel's database layer, Query Builder, Eloquent ORM, migrations, and other standard database features.

Status: Early release

This package provides SQL Anywhere 17 database support for Laravel. It is currently tested with Laravel 12 and Laravel 13 and should be considered an early release while additional SQL Anywhere/Laravel compatibility testing is performed.

Features

The package currently provides:

SQL Anywhere 17 database connection for Laravel
PDO/ODBC connection support
SQL Anywhere query grammar
SQL Anywhere schema grammar
SQL Anywhere query processor
SQL Anywhere-compatible insertGetId() handling
SQL Anywhere-compatible TOP / START AT pagination syntax
SQL Anywhere-compatible EXISTS expressions
Laravel withExists() compatibility
PDO/ODBC nullable numeric value normalization
SQL Anywhere-compatible migration column types
SQL Anywhere identity/autoincrement support
SQL Anywhere schema introspection
Laravel Eloquent and Query Builder integration
Laravel migration support

The package is designed to minimize application-level changes. Developers should be able to continue using Laravel's normal database APIs instead of writing SQL Anywhere-specific code for every operation.

Requirements

Before installing the package, make sure the environment has:

PHP 8.2 or later
Laravel 12.x or 13.x
SQL Anywhere 17
SQL Anywhere 17 ODBC Driver
PHP PDO
PHP PDO ODBC extension
A running SQL Anywhere database server

For Windows installations, the SQL Anywhere ODBC driver must be correctly installed and available to PHP.

You can verify PDO ODBC with:

php -m

Look for:

PDO
pdo_odbc

Installation

Install the package using Composer:

composer require yondaime/laravel-sqlanywhere

Laravel package discovery should automatically register the package service provider.

After installation, configure the SQL Anywhere connection in your Laravel application's config/database.php.

Note: If your Packagist package name differs from yondaime/laravel-sqlanywhere, use the exact Composer package name registered on Packagist.

Configuration

Set the default database connection in your .env file:

DB_CONNECTION=sqlanywhere

Then configure the SQL Anywhere connection in:

config/database.php

Example:

'sqlanywhere' => [
    'driver' => 'sqlanywhere',
    'dsn' => env('DB_DSN'),
    'host' => env('DB_HOST', 'localhost'),
    'port' => env('DB_PORT', 2638),
    'database' => env('DB_DATABASE'),
    'username' => env('DB_USERNAME'),
    'password' => env('DB_PASSWORD'),
    'prefix' => '',
    'options' => [],
],

Then configure the connection in .env:

DB_DSN="odbc:driver=SQL Anywhere 17;eng=your_engine;dbn=your_database;commlinks=tcpip(host=localhost);CharSet=UTF-8;"
DB_HOST=localhost
DB_PORT=2638
DB_DATABASE=your_database
DB_USERNAME=your_username
DB_PASSWORD=your_password

The exact DSN depends on your SQL Anywhere server configuration. Replace the example database, engine, username, and password with your own values.

After changing configuration, Laravel's configuration cache may need to be cleared:

php artisan config:clear

If your application uses cached configuration:

php artisan config:cache

Example SQL Anywhere Connection

A typical SQL Anywhere 17 connection may look like:

Laravel
  ↓
SQL Anywhere Connection
  ↓
PDO
  ↓
ODBC
  ↓
SQL Anywhere 17 Driver
  ↓
SQL Anywhere Engine
  ↓
SQL Anywhere Database

For example:

DB_DSN="odbc:driver=SQL Anywhere 17;eng=your_engine;dbn=your_database;commlinks=tcpip(host=localhost);CharSet=UTF-8;"

The SQL Anywhere engine and database names depend on your environment.

Using Laravel's Database API

Once configured, applications can continue using Laravel's normal database APIs.

Query Builder

use Illuminate\Support\Facades\DB;

$users = DB::table('users')
    ->where('username', 'supadmin')
    ->get();

Eloquent

use App\Models\User;

$user = User::where('username', 'supadmin')->first();

Insert

DB::table('users')->insert([
    'name' => 'Administrator',
    'username' => 'admin',
    'password' => bcrypt('password'),
]);

Insert and retrieve identity

The package provides SQL Anywhere-specific handling for Laravel's insertGetId():

$id = DB::table('users')->insertGetId([
    'name' => 'Administrator',
    'username' => 'admin',
    'password' => bcrypt('password'),
]);

Internally, SQL Anywhere's identity mechanism is used instead of relying on PDO's lastInsertId() behavior.

SQL Anywhere PDO/ODBC Compatibility

SQL Anywhere 17 through PDO/ODBC has some driver-specific behavior that differs from Laravel's normal expectations.

The package includes compatibility handling for these cases.

Nullable Numeric Columns

In some query scenarios, SQL Anywhere/PDO_ODBC can return an empty string ("") for a nullable numeric database column whose actual value is NULL.

For example, a nullable SQL Anywhere column such as:

cgt_amount_paid DECIMAL(8,2) NULL

may be returned by PDO/ODBC as:

""

instead of:

NULL

This can cause Laravel's numeric casts to fail.

For example:

protected $casts = [
    'cgt_amount_paid' => 'decimal:2',
];

Laravel expects the database value to be a valid numeric value or null. An empty string can result in an exception such as:

Unable to cast value to a decimal.

The package detects affected nullable numeric columns using SQL Anywhere's sa_describe_query() metadata and normalizes empty-string values back to null before Laravel processes the result.

This allows nullable numeric Eloquent casts to behave correctly with SQL Anywhere/PDO/ODBC.

The normalization is limited to columns that SQL Anywhere reports as both:

nullable, and
numeric SQL Anywhere domains.

Other empty-string values are not automatically converted to null.

EXISTS Compatibility

SQL Anywhere does not accept the same SELECT-list EXISTS syntax generated by Laravel for certain Eloquent features.

Laravel can generate a SELECT expression similar to:

exists(
    select *
    from alert_reads
    where ...
) as "is_read"

SQL Anywhere requires a conditional expression instead.

The package converts SELECT-list EXISTS expressions into SQL Anywhere-compatible syntax:

case
    when exists (
        select *
        from alert_reads
        where ...
    )
    then 1
    else 0
end as "is_read"

This allows Laravel features such as withExists() to work with SQL Anywhere.

Example

Laravel application code can continue using:

$query->withExists([
    'reads as is_read' => fn ($query) =>
        $query->where('user_id', $userId),
]);

The package translates the generated SELECT-list EXISTS expression into a SQL Anywhere-compatible CASE WHEN EXISTS expression.

`whereExists()`

Normal whereExists() queries are also supported.

For example:

$alerts = Alert::query()
    ->whereExists(function ($query) {
        $query->from('alert_reads')
            ->whereColumn('alert_reads.alert_id', 'alerts.id');
    })
    ->get();

The package compiles the existence check into SQL Anywhere-compatible syntax.

Migrations

Laravel migrations can be used with the SQL Anywhere connection.

Example:

Schema::create('employees', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('username')->unique();
    $table->timestamps();
});

The package translates Laravel schema definitions into SQL Anywhere-compatible SQL.

For example, Laravel's:

$table->id();

is mapped to an SQL Anywhere identity column.

Pagination

SQL Anywhere uses different pagination syntax from MySQL.

For example, MySQL commonly uses:

LIMIT 10 OFFSET 20

The package's query grammar translates Laravel pagination operations into SQL Anywhere-compatible syntax using constructs such as:

TOP 10 START AT 21

This allows application code to continue using Laravel's normal query APIs.

Example:

$users = User::query()
    ->offset(20)
    ->limit(10)
    ->get();

The generated SQL uses SQL Anywhere's TOP / START AT syntax.

Identity / Auto-Increment Columns

SQL Anywhere uses identity columns for automatically generated numeric IDs.

The package maps Laravel's auto-incrementing primary key definitions to SQL Anywhere identity syntax.

Example:

Schema::create('users', function (Blueprint $table) {
    $table->id();
    $table->string('name');
});

The package handles the SQL Anywhere-specific identity definition while allowing the Laravel migration API to remain unchanged.

`insertGetId()`

One of the database-specific differences between SQL Anywhere and some databases supported by Laravel is retrieving the ID generated by an insert.

Instead of relying on:

$pdo->lastInsertId();

the SQL Anywhere processor retrieves the generated identity value using SQL Anywhere's identity mechanism:

SELECT @@identity AS id

This allows code such as:

$id = DB::table('permissions')->insertGetId([
    'name' => 'view_reports',
    'guard_name' => 'web',
]);

to work with SQL Anywhere.

SQL Syntax Compatibility

This package handles SQL generated by Laravel's database abstraction layer.

However, applications may contain raw SQL that was written specifically for MySQL.

For example, MySQL-specific SQL such as:

SUM(status = 'Completed')

may not work in SQL Anywhere.

The SQL Anywhere-compatible form is:

SUM(
    CASE
        WHEN status = 'Completed' THEN 1
        ELSE 0
    END
)

Therefore, applications using:

selectRaw()

or:

DB::raw()

should still review their SQL for database-specific syntax.

Important

This package does not automatically translate arbitrary MySQL SQL into SQL Anywhere SQL.

It provides compatibility for the Laravel database integration layer.

Application-specific raw SQL remains the responsibility of the application developer.

Architecture

The package integrates with Laravel at the database abstraction layer:

Laravel Application
        │
        ▼
Laravel Eloquent / Query Builder
        │
        ▼
SQL Anywhere Connection
        │
        ├── Query Grammar
        │
        ├── Schema Grammar
        │
        └── Query Processor
        │
        ▼
PDO
        │
        ▼
ODBC
        │
        ▼
SQL Anywhere 17
        │
        ▼
SQL Anywhere Database

The connection layer also provides SQL Anywhere/PDO-specific result normalization where required.

This approach allows applications to continue using Laravel's database APIs while database-specific behavior is handled by the package.

Why This Package?

Laravel provides database integrations for several major relational database systems.

SQL Anywhere applications may require database-specific connection, grammar, schema, processor, and PDO/ODBC compatibility behavior.

This package aims to provide those missing integration components for SQL Anywhere 17.

The objective is not to modify SQL Anywhere to behave like MySQL.

Instead, the package adapts Laravel's database layer so that Laravel can communicate with SQL Anywhere using SQL Anywhere-compatible behavior.

Testing

Testing is currently focused on SQL Anywhere 17.

The test suite is intended to cover:

Database connection
Query Builder
Eloquent queries
Inserts
Identity retrieval
Updates
Deletes
Pagination
Migrations
Schema inspection
Indexes
Foreign keys
Transactions
Aggregates
Date/time handling
EXISTS queries
withExists() queries
Nullable numeric columns
PDO/ODBC result handling

A SQL Anywhere 17 database server is required for integration tests.

For local package development:

composer install

Validate the Composer package definition:

composer validate

Run the test suite:

composer test

If the package provides a dedicated SQL Anywhere integration test environment, configure the required database connection before running those tests.

Known Limitations

This project is currently under development.

The following areas may require additional testing or implementation:

Complex database-specific queries
MySQL-specific raw SQL
JSON-specific operations
Advanced upsert behavior
Full-text search
Database-specific locking behavior
Advanced index operations
Stored procedures
SQL Anywhere-specific data types
Differences between SQL Anywhere versions
PHP PDO ODBC driver behavior
Laravel features that generate database-specific SQL

If you encounter a compatibility problem, please open an issue with:

Laravel version
PHP version
SQL Anywhere version
Operating system
Relevant Laravel code
Generated SQL
SQL Anywhere error message

Please remove passwords, connection credentials, and other sensitive information before submitting an issue.

Contributing

Contributions are welcome.

Before submitting a pull request:

Reproduce the issue with SQL Anywhere 17.
Add or update an automated test where appropriate.
Keep database-specific behavior inside the package rather than application-specific code.
Follow Laravel and PSR coding conventions.
Document compatibility changes.

Pull requests should explain:

What problem is being solved
Why the existing implementation does not work with SQL Anywhere
How the change works
Which SQL Anywhere version was tested

Development

Clone the repository:

git clone https://github.com/yondaime/laravel-sqlanywhere.git

Install dependencies:

composer install

Validate the Composer package:

composer validate

Run the test suite:

composer test

Test commands may change as the project's automated test infrastructure is established.

Versioning

This package follows semantic versioning where practical:

MAJOR.MINOR.PATCH

Example:

0.1.0

During early development, breaking changes may occur between minor releases.

Once the API and database integration stabilize, the package will move toward a stable 1.0.0 release.

License

This package is open-sourced software licensed under the MIT License.

Credits

Developed for Laravel applications requiring integration with SAP SQL Anywhere 17.

Special thanks to the Laravel, PHP, SQL Anywhere, PDO, and ODBC communities.

Disclaimer

Laravel is a trademark of Taylor Otwell.

SAP and SQL Anywhere are trademarks or registered trademarks of SAP SE or its affiliates.

This project is an independent community package and is not affiliated with, endorsed by, or sponsored by Laravel or SAP.

yondaime / laravel-sqlanywhere

Package info

Security

Statistics

README

Features

Requirements

Installation

Configuration

Example SQL Anywhere Connection

Using Laravel's Database API

Query Builder

Eloquent

Insert

Insert and retrieve identity

SQL Anywhere PDO/ODBC Compatibility

Nullable Numeric Columns

EXISTS Compatibility

Example

`whereExists()`

Migrations

Pagination

Identity / Auto-Increment Columns

`insertGetId()`

SQL Syntax Compatibility

Important

Architecture

Why This Package?

Testing

Known Limitations

Contributing

Development

Versioning

License

Credits

Disclaimer