NAME
DBIO::Sybase::Deploy - Deploy and upgrade Sybase ASE schemas via test-deploy-and-compare
VERSION
version 0.900007
DESCRIPTION
DBIO::Sybase::Deploy orchestrates schema deployment and upgrades for Sybase ASE using the test-deploy-and-compare strategy.
For upgrades it:
- 1. Introspects the live database from the ASE system catalog
- 2. Deploys the desired schema (from DBIO classes) to a temporary database
- 3. Introspects the temporary database the same way
- 4. Computes the diff between the two models using DBIO::Sybase::Diff
Transactional DDL -- not used, and not merely unavailable
DBIO::Sybase::Storage::ASE declares _use_transactional_ddl(0), so "_execute_ddl" in DBIO::Deploy::Base never brackets this driver's DDL in $storage->txn_do and core emits its one-time notice, non-transactional DDL on DBIO::Sybase::Deploy. The notice is correct and is not a defect to be silenced.
What ASE does here is not what the shared description of that notice suggests. It has no implicit COMMIT on DDL: whether create table may sit in a multi-statement transaction is the per-database ddl in tran option, which is off unless a system administrator turned it on for that database, and with it off the server rejects the statement rather than committing around it. A capability is one class-level answer given before any connection, so the only answer true on every ASE is 0; the reasoning, the manual it comes from and what a runtime probe would and would not buy are written out above the declaration in DBIO::Sybase::Storage::ASE.
For "apply" and "install" that means: core splits $diff->as_sql (or the install DDL) on ;, drops comment-only fragments, and runs the rest through $dbh->do on the live connection one after another, each standing on its own as the connection's AutoCommit lets it. A failure part way therefore leaves everything before it applied. Nothing here is subtle about that: an index change renders as DROP INDEX t.i followed by CREATE UNIQUE INDEX i ON t (...), two fragments, and a failure between them leaves the index dropped and not rebuilt. Recovery is to re-run "upgrade" -- "diff" is recomputed against live state, so the second run picks up only what is left.
The temporary database is unaffected either way. Its schema is deployed through a handle this Deploy opened itself, which core leaves unbracketed whatever the capability says, and its CREATE DATABASE / DROP DATABASE never reach _execute_ddl at all -- _create_temp_db and _drop_temp_db issue them directly on a handle with AutoCommit, because ASE forbids those two inside a transaction unconditionally (ADR 0005). Both also run from master -- ASE refuses CREATE DATABASE anywhere else (Msg 1809) -- and the handle is switched back to the database it was in afterwards, also when the statement fails, because it is the live handle the rest of "diff" and "apply" go on to use. A failed temp deploy is recovered by dropping the whole database.
Neither method ends a transaction that is not its own. Given a handle whose AutoCommit is off, _create_temp_db and _drop_temp_db refuse with a DBIO::Exception naming the method and the reason, before any statement runs -- no COMMIT, no USE master, no query, no change to the handle's error handler -- so the transaction stands as it was. They neither send COMMIT nor switch AutoCommit on (which in DBI commits an open transaction as well); the caller hands them a handle with AutoCommit.
The temporary database is dropped more than once if need be
ASE refuses DROP DATABASE while anything is in the database, with Msg 3702 ("Cannot drop or replace the database '...' because it is currently in use." -- live, ASE 16.0 SP02). "diff" drops its temporary database the moment core has closed the session the schema was deployed through, and a client session is not all that can be in a database: the server's own checkpoint process was observed inside one that no client was connected to. What is in the way then leaves by itself. So _drop_temp_db answers Msg 3702, and no other error, by trying again -- 40 tries in all, a quarter of a second apart, which is ten seconds (_drop_in_use_tries, _drop_in_use_wait).
A database still in use after that stays where it is. _drop_temp_db dies of the server's error, "_build_target_model" in DBIO::Deploy::Base::TempDatabase catches it, and "diff" returns its result all the same: nothing reports the database left behind. It is named _dbio_tmp_<pid>_<time>_<n> (time is in minutes since the epoch, which keeps the name within the 30 characters ASE allows; n counts the temporary databases of the process, so two in the same minute differ) and is dropped by hand, from master:
use master
drop database _dbio_tmp_12345_29856533_1
The size of the temporary database
The temporary database is made with the size the schema to be deployed into it needs, not with the server's default database size -- the size of model, 24 MB on the server this was measured on (ASE 16.0 SP02, 16K pages), with 686 of its 1536 pages free, which a schema of 38 tables and 15 further indexes (the whole of DBIO::Test::Schema) did not fit into. Nothing about it is asked of the administrator: CREATE DATABASE is sent with ON default = 'NNM', the size calculated as follows.
A table takes an extent of 8 pages, and so do its primary key and every further index (measured). So the schema needs
(2 * tables + other indexes) * 8 pages
where the tables and the indexes are those DBIO::Sybase::DDL writes -- a view is no table, a table two sources map to counts once, and a unique column, a unique constraint and a declared index are one index each, not again where they repeat the columns of one already written. What the formula leaves out (system tables, the log) was 45 pages on 36 tables and the formula alone hit 688 of the 733 pages needed, so a quarter and 64 pages are added. The pages model has in use are in the new database from the start and are added, the sum is taken in the server's page size (@@maxpagesize), rounded up to the next 4 MB, and the database is never smaller than model. DBIO::Test::Schema, measured: 38 tables and 15 other indexes, 32 MB, of which the install used 783 pages and left 415 free.
Setting the size
The attribute temp_db_size replaces the calculation ("temp_db_size"): given, the database has that size, the server is not asked about model, and the size is not a minimum -- one that is too small is created as it is and the deploy dies of the errors below. A server without the room for the database (Msg 1810: the default device has less free than the size, or none) is not a deploy that can go on: _create_temp_db dies naming the size it asked for, temp_db_size, and the server's message. Room is made on the server (disk init, sp_diskdefault), which this class does not do.
A schema too large for the temporary database
What becomes of a schema that does not fit is a database option. A database copied from model does not have abort tran on log full, and without it ASE does not refuse the statement that finds the database full: it suspends the session until somebody frees log space (master..sysprocesses shows it sleeping, with the command LOG SUSPEND). In a database that exists for one deploy nobody does, so "diff" and "upgrade" never returned -- without an error, and with nothing on the client to end it. _create_temp_db therefore sets the option, from master, before anything is deployed:
exec sp_dboption '_dbio_tmp_12345_29856533_1', 'abort tran on log full', true
The procedure runs the checkpoint that puts the option into effect itself. _create_temp_db then reads sysdatabases to see that it is set; a database it could not be set on is dropped again and the error raised, and nothing is deployed into it.
With the option, the statement that finds the database full dies of the server's error, and "diff" with it:
Server message number=1105 severity=17 ... text=Can't allocate space for
object 'syslogs' in database '_dbio_tmp_12345_29856533_1' because
'logsegment' segment is full/has no free extents. If you ran out of space
in syslogs, dump the transaction log. Otherwise, use ALTER DATABASE to
increase the size of the segment.
Msg 7412 ("Space available in segment 'logsegment' has fallen critically low in database '...'") may stand before it, and a second Msg 1105 and Msg 2761, naming the table that was being created, after it. The database it names is the temporary one, and its advice does not apply: by the time the error arrives that database has been dropped. What the error means is that the desired schema needs more room than the temporary database has -- with the calculated size only where the schema is larger than the calculation allows for, and with a temp_db_size set too small as a matter of course. The live handle is back in its own database, and the live database was only read -- "upgrade" dies in "diff", before "apply" (live, ASE 16.0 SP02; t/71-temp-db-log-full-live.t).
Data-copying ALTER TABLE
Dropping a column, changing a column's stored type (INT to BIGINT) and adding a NOT NULL column make ASE copy the table, and in a database without the select into/bulkcopy/pllsort option ASE refuses that with Msg 11052 ("Neither the 'select into' nor the 'full logging for alter table' database options are enabled for database '...'. ALTER TABLE with data copy cannot be done." -- live, ASE 16.0 SP02). The full logging for alter table option the message also names takes effect only in a database whose log has its own device; in one with mixed data and log segments -- what a plain CREATE DATABASE gives -- ASE sets it and ignores it. The option that works on every database is select into/bulkcopy/pllsort, set by a system administrator from master and followed by a checkpoint of the database:
use master
exec sp_dboption 'mydb', 'select into/bulkcopy/pllsort', true
use mydb
checkpoint
It is a precondition of "apply" and "upgrade" for any diff containing such a change, and it is the administrator's to set: it permits minimally logged operations, after which the transaction log cannot be dumped until the next full database dump. This class neither sets it nor checks for it. Without it, "apply" runs the diff up to the first data-copying statement, which fails; since the run is not transactional (above), everything before that statement stays applied. After the option is set, "upgrade" recomputes the diff against that state and applies the rest. Which statements copy is listed in "DATA-COPYING ALTERS NEED A DATABASE OPTION" in DBIO::Sybase::Diff::Column.
ATTRIBUTES
temp_db_size
DBIO::Sybase::Deploy->new(schema => $schema, temp_db_size => '64M');
The size of the temporary database, as CREATE DATABASE ... ON default = 'NNM' takes it: a whole number and optionally the unit K, M, G or T (a number alone is megabytes). Not given, the size is calculated from the schema ("The size of the temporary database"). Given, it is the size of the database: the calculation does not run, the server is not asked about model, and the size is not a minimum -- one smaller than the schema needs is created as it is, and the deploy dies of Msg 1105. Anything else is refused.
METHODS
install
$deploy->install;
Generates DDL via "install_ddl" in DBIO::Sybase::DDL and executes each statement against the connected database. Suitable for fresh installs. Inherited from DBIO::Deploy::Base.
diff
my $diff = $deploy->diff;
Computes the difference between the live database and the desired state. Deploys the desired schema to a temporary database, introspects both, and returns a DBIO::Sybase::Diff object.
_check_before_apply
The Sybase check of a diff against the live tables, run by "apply" in DBIO::Deploy::Base (and so by "upgrade" in DBIO::Deploy::Base) once the diff is released and before its first statement: a column that becomes NOT NULL in a table that holds a NULL in it is refused with a DBIO::Exception naming table and column (Msg 515 otherwise, half way through the batch). Nothing has been executed when it throws. diff, as_sql and summary stay reads and do not look.
apply
Inherited from "apply" in DBIO::Deploy::Base, with its allow_destructive and dry_run arguments: a diff with a drop or a possibly lossy column change ("lossy" in DBIO::Sybase::Diff::Column) runs with allow_destructive => 1 only. The Sybase check is "_check_before_apply".
upgrade
my $diff = $deploy->upgrade;
my $diff = $deploy->upgrade(allow_destructive => 1);
Inherited from "upgrade" in DBIO::Deploy::Base: "diff" then "apply", with the same arguments. Returns the diff object if changes were applied, or undef if the database was already up to date.
SEE ALSO
DBIO::Sybase - schema component
DBIO::Sybase::Introspect - reads live database state
DBIO::Sybase::Diff - compares two introspected models
DBIO::DuckDB::Deploy - reference implementation
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.