NAME

DBIO::Sybase::Storage - Base class for drivers using DBD::Sybase

VERSION

version 0.900007

DESCRIPTION

Base storage class for DBD::Sybase-based connections, and the class a schema declares: the DBIO::Sybase component and the -syb shortcut pin it. It has nothing of an engine itself. A connected storage is one of its subclasses: at the first use that needs the driver, the schema that declares this driver has said what the server is, and the storage becomes DBIO::Sybase::Storage::ASE without asking it ("_adapt_to_access_path"), never the class of another product.

If DBD::Sybase was compiled against FreeTDS, the FreeTDS fixups from DBIO::Sybase::Storage::FreeTDS are mixed in automatically.

METHODS

_adapt_to_access_path

The hook of "_adapt_to_access_path" in DBIO::Storage::DBI (core ADR 0059). A schema declares this driver by loading the DBIO::Sybase component or by the -syb shortcut, and both pin this class, which is no engine's. Core calls the hook at the first use that needs the driver -- not at connect -- with the name of the DBD the connect info leads through, and on Sybase the storage becomes DBIO::Sybase::Storage::ASE.

The server is not asked what it is. A schema that declared this driver has answered that question, and is taken at its word.

What the storage does ask is the client library, through the handle -- so the first use connects. DBIO::Sybase::Storage::ASE decides from it whether the connection takes placeholders: it turns auto_cast on, or moves on to DBIO::Sybase::Storage::ASE::NoBindVars. _init then mixes the FreeTDS class in.

The storage never becomes the class of another product, and that includes DBIO::MSSQL::Storage::Sybase, which inherits this class and which core's own check would therefore let pass. DBD::Sybase sends select @@version by itself at every login and keeps the answer (syb_server_version_string); when that names Microsoft SQL Server, the hook reports it through "_driver_mismatch" in DBIO::Storage::DBI -- a warning, an error with "driver_strict" in DBIO::Schema, nothing with "driver_warnings" in DBIO::Schema off -- and the storage becomes the ASE class all the same, unless that threw. A schema for Microsoft SQL Server declares DBIO::MSSQL. No other product is recognised, and none is asked for.

Three things the hook leaves alone:

  • A class that is not this one. A subclass of this class pinned by hand through "storage_type" in DBIO::Schema stays what it is: core requires the storage to remain an instance of the class that was declared. A storage pinned to DBIO::Sybase::Storage::ASE itself is of the class it was put in, but meets the server like the declared base does -- a server that names Microsoft SQL Server is reported through _driver_mismatch first, before anything is probed, and the storage stays the ASE class -- and then takes the placeholder decision the declared base takes: the same code, on the same connection, so it ends in the class the declared base ends in -- auto_cast on where the declared base turns it on (never across the board: under FreeTDS a connection that takes typeless placeholders gets none, CAST(? AS ..) dies there with Msg 12828), or the NoBindVars class. It is the one connection the storage uses anyway. A class below the ASE class, which could not become the NoBindVars class and stay itself, and a pinned DBIO::Sybase::Storage::ASE::NoBindVars are left as they are. The writer and the bulk storage DBIO::Sybase::Storage::ASE makes for itself decide nothing: their parent has decided, auto_cast is copied from it, and they go through the hook unchanged, so the hook can run any number of times.

  • Another DBD. On a DSN that leads through any other DBD the storage stays this class. If that DBD belongs to another driver, core reports it ("_driver_mismatch" in DBIO::Storage::DBI); a DBD nothing is registered for is not judged.

  • Storage layers. The storage connects before it leaves the class it was composed in, and core composes the same layers over the class it became. Under FreeTDS _init builds its FreeTDS class over the base of the composition and composes the layers again over it: the layers stay ahead of the methods of DBIO::Sybase::Storage::FreeTDS, so a layer that overrides a method the FreeTDS class has is asked first, and "composition_of" in DBIO::Storage::Composed knows the storage's class (base <class>::FreeTDS, the same layers). The same holds for DBIO::MSSQL::Storage::Sybase, which inherits _init (t/59-component-rebless.t).

A connection coderef names no DBD until it has run, so core hands the hook none. The hook then runs it -- one connection, the one the storage goes on using -- and reads the DBD off the handle. A schema connected without any connect info is never sent through driver determination and stays this class.

Read from the upstream source of DBD::Sybase (dbdimp.c, get_server_version called from syb_db_login), not from the 1.27 tarball: that the version string is fetched at login and reading the attribute sends nothing. Measured on 2026-10-07 against SAP ASE 16.0 SP02 with DBD::Sybase 1.27 on FreeTDS 1.3.17 (t/62-component-rebless-live.t): the attribute is set after the connect and names Adaptive Server Enterprise, and a declared storage works as the ASE class. Not verified: anything with the Open Client libraries. The mismatch is pinned against a handle that plays Microsoft SQL Server (t/59-component-rebless.t, t/92-pinned-ase-placeholders.t). Measured on 2026-10-25 against Microsoft SQL Server 2022 (16.0.4295) with DBD::Sybase 1.27 on FreeTDS 1.3.17: the attribute is set after the connect and begins Microsoft SQL Server 2022; the declared base and the storage pinned to the ASE class both warn (with driver_strict, throw) and both then die of Msg 195 (CHAINED is not recognized) in the first set, which is ASE's.

_bind_host_into_dsn

The HostBound seam of "_bind_host_into_dsn" in DBIO::Storage::DBI: how a DBIO::AccessBroker::HostBound view -- a host of its own per replicant, one set of credentials -- puts its host (and port) into a DSN that is already written.

DBD::Sybase takes its server address from the keys host= and port= (dbi:Sybase:host=<host>;port=<port>;database=...), which is the form core's default translates: they are replaced where they stand and put in front where they are missing, and the rest of the DSN stays as it is.

server=<name> is declined. It names an entry of the interfaces file or freetds.conf, not a host, so there is nothing to replace, and binding a host into such a DSN would leave the connection on the server the entry names -- the answer's. The view refuses the connection, and the message names the form and points at host=/port=, never the DSN (it may hold a password). Only a dbi:Sybase: DSN is looked at; any other DBD goes to the next class's seam. The classes this storage becomes inherit the seam, and so does DBIO::MSSQL::Storage::Sybase.

_connect_params_dsn

The DSN seam of "_connect_params_dsn" in DBIO::Storage::DBI (ADR 0057) for connection parameters that carry no DSN -- dbname, host and port, as DBIO::AccessBroker::Static answers them, or a connect-info hash without a dsn. Overridden because core's default form names the database with dbname=, which DBD::Sybase does not read: the connection would reach the server and stay in the login's default database, without an error.

dbi:Sybase:host=<host>;port=<port>;database=<dbname>

host and port go in as a pair, dbname as database=, and a part not given is left out -- nothing is put into the DSN that the parameters do not say:

  • without dbname there is no database=, and the server puts the session into the login's default database;

  • without host and port the DSN names no server, and DBD::Sybase connects to its default one: $DSQUERY, else the server called SYBASE.

Two combinations refuse, each error naming the ways out:

  • host without port. DBD::Sybase sets the server address only when it has both; a lone host is ignored and the connection goes to the default server, silently. No port is assumed: DBD::Sybase supplies none, and a server listens where it was configured to.

  • port without host. Ignored the same way; the port given would be dropped.

Both stay refusals and are not read as server=<host> (maintainer's decision): a lone host or port in a hand-written DSN is dropped by DBD::Sybase, and the connection goes to the server $DSQUERY names -- even for a host that does not exist -- so a parameter would be accepted and not honoured. server= names an entry of the interfaces file or freetds.conf, not a host, and a host is not such a name. A server known by name goes in as the whole DSN, as said below.

Anything these three parts cannot say goes in as the whole DSN: as dsn, or as a dbname that starts with dbi: (DBIO::AccessBroker::Static passes it on), which core takes as the DSN before this seam is asked. That is the way in for a server reached by name, dbi:Sybase:server=<name>;....

The classes this storage becomes inherit the seam, so a reconnect builds the same DSN: DBIO::Sybase::Storage::ASE, and DBIO::MSSQL::Storage::Sybase, which lists this class ahead of DBIO::MSSQL::Storage -- whose own override builds the same form.

How DBD::Sybase treats the keys is read from its documentation and from dbdimp.c of DBD::Sybase 1.27, and was connected with on 2026-10-05, against SAP ASE 16.0 SP02 with DBD::Sybase 1.27 built against FreeTDS 1.3.17 (t/60-connect-params-live.t). The forms above connect where this section says they do: host, port and dbname into the database named -- on the first connect, on a reconnect, and on the connection of the ASE writer storage; host and port alone into the login's default database; dbname alone to the server $DSQUERY names. dbname= in the place of database= connects without an error, into the login's default database. A lone host or port, in a DSN written by hand, is dropped and the connection goes to the $DSQUERY server. Not connected with: a DBD::Sybase built against the Sybase Open Client libraries.

That run also showed a limit of the host=...;port=... form under FreeTDS: a second statement while a result set is still being read is refused (Server name not found in configuration files). DBD::Sybase opens a connection of its own for it and looks the server up by name, and this form names none: the prepare of the second statement dies of that message. On the dbname-alone form the same statement runs. The second connection itself is made, and a $dbh->do goes through on it -- on another session of the server.

SEE ALSO

AUTHOR

DBIO & DBIx::Class Authors

COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors Portions Copyright (C) 2005-2025 DBIx::Class Authors Based on DBIx::Class, heavily modified.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.