NAME

DBIO::Oracle::Test::Conformance - Answers the shared conformance case table for the Oracle driver

VERSION

version 0.900007

SYNOPSIS

use DBIO::Oracle::Test::Conformance;
DBIO::Oracle::Test::Conformance->run('DDL');
done_testing;

DESCRIPTION

The driver's half of the shared case table of DBIO::Test::Conformance (core ADR 0060). Core owns the cases and the runner; this class says how to reach an Oracle server, how to install a declaration into it through DBIO::Oracle::Deploy, and how to read a fact back through DBIO::Oracle::Introspect.

The server is the one DBIO_TEST_ORA_DSN, DBIO_TEST_ORA_USER and DBIO_TEST_ORA_PASS name; without the DSN (or without DBD::Oracle) only the declarations are checked.

The namespace of a case is the user's own schema, cleaned up after the case. Oracle has no cheaper namespace: a schema is a user, and a new user is not this class's to create. "conformance_namespace" therefore records which objects the connected user owns before the case runs, and "conformance_cleanup" drops exactly the tables, views, sequences, triggers and indexes that are there afterwards, were not before, and whose names the declaration of the case gives (the table and view names, the shortened sequence and trigger names of its auto-increment columns, its index names -- taken from "declared_objects" in DBIO::Oracle::DDL, the one place those names are made), with DROP TABLE ... CASCADE CONSTRAINTS PURGE, so nothing lands in the recycle bin. Any other new object (a table another session of the user made while the case ran, an index on a table that was there before) is left alone and reported with diag. An object that was there before is never touched, nor is an object of another user, and nothing server-wide is changed. Oracle commits around every DDL statement, so a case cannot be rolled back; the cleanup is the only way back, and a cleanup that cannot drop an object of its case fails the case. Two runs against the same user at once would still meet on the names of the cases: one run per database at a time (house rule 1 of live testing).

The diff postcondition is asked ("conformance_diff_is_empty"): after a case is installed, a diff of the live schema against the same declaration is empty, as far as the objects of the case go. It builds the declaration in a temporary user (DBIO::Oracle::Deploy), so the connected user needs CREATE USER and DROP USER.

The class names no storage class and never decides the driver: the schema class of a case loads the Oracle component, as an application does.

METHODS

conformance_live_available

True when DBIO_TEST_ORA_DSN is set and DBD::Oracle loads.

conformance_connect

Loads the Oracle schema component into the case's schema class and connects with the DBIO_TEST_ORA_* variables, and nothing else: the ISO date and timestamp formats are the driver's own default for every connection ("Date and timestamp formats" in DBIO::Oracle::Storage), so the case ddl-default-expression reads a date as the string it expects without this class setting anything.

The long-value length and the client character set are the driver's own defaults as well ("LOB length and character set" in DBIO::Oracle::Storage): the Bind cases that read a long text back and send non-ASCII text need nothing set here, nor an NLS_LANG.

conformance_namespace

Records the objects the connected user owns, as the token for "conformance_cleanup".

conformance_install

Installs the declaration with $schema->deploy, the public entry point, which hands over to "install" in DBIO::Oracle::Deploy.

ddl-view-declared runs like every other case: the runner builds its view definition from the identifiers it quotes (conformance_quote_ident), by default the quote character of the SQL maker, " here. The definition therefore names the table as the driver creates it, quoted and as the result class spells it. A definition a user writes by hand is still sent as written (t/75-conformance-ddl-extra-live.t).

conformance_cleanup

Drops what the case created, and only that: the objects the user owns now, did not own when "conformance_namespace" looked, and whose names the declaration of the case gives ("declared_objects" in DBIO::Oracle::DDL) -- its tables, its views, the shortened sequence and trigger names of its auto-increment columns, and its indexes, an index only when it is on one of the case's own tables. Views go first, then tables (CASCADE CONSTRAINTS PURGE), sequences, triggers and indexes that are still there. Every other new object (one that another session of the same user made while the case ran, an index on a table that was there before) is left alone and reported with diag. A case that failed before the namespace was recorded has created nothing and drops nothing. Where the case's own connection is no longer usable, the objects are dropped through a connection of their own. An object of the case that cannot be dropped is an error: it would be the next case's residue.

conformance_diff_is_empty

True when the diff of the installed schema against the same declaration ("diff" in DBIO::Oracle::Deploy, the desired state built in a temporary user) holds no operation on one of the case's own tables or views, the names given by "declared_objects" in DBIO::Oracle::DDL. The diff is of the whole schema of the user, so an operation on a table that was there before the case (and would be dropped) is not the case's and does not count. A diff that holds operations of the case is told with diag, as its summary.

A table in another schema (a source schema.table) is asked too, by the name schema.table the diff gives it: "diff" in DBIO::Oracle::Deploy builds the desired state with a temporary user for each such schema.

conformance_upgrade

Connects the target schema class (loading the Oracle component, as an application does) to the same server as the installed one and runs "upgrade" in DBIO::Oracle::Deploy's two halves -- diff, then apply -- on it, with allow_destructive => 1: the cases of the table are about what the diff does (a dropped column, a changed type), the guard that holds a destructive diff back has its own cases (diff-deploy-destructive-guard, run through "conformance_deploy"). The desired state is built in a temporary user, so the connected user needs CREATE USER and DROP USER.

The diff is of the whole schema of the connected user, and that user is shared with whatever else lives in it: an operation on a table that neither the installed nor the target declaration names ("declared_objects" in DBIO::Oracle::DDL) would drop somebody else's table. Such an operation is left out of what is applied and told with diag; nothing but the objects of the case is written. A refusal of the diff is thrown from here as it came. When the upgrade fails, what the target declaration already created is removed again before the error goes on, since the runner's cleanup works from the installed declaration.

conformance_deploy

The deploy object over the target schema, for the deploy cases of the Diff list (table version 4): the target class is connected as "conformance_upgrade" connects it, and the runner calls apply and upgrade on the object it gets back. It is a DBIO::Oracle::Test::Conformance::Deploy, a DBIO::Oracle::Deploy that differs in one method only: its diff leaves out, and tells with diag, the operations on a table that neither the installed nor the target declaration names (the diff is of the whole schema of the connected user, and the user is shared; an apply with allow_destructive would drop somebody else's table). apply and upgrade are the ones of DBIO::Deploy::Base, as the check inherited of the runner requires. When the connect fails the error goes on as it is; the objects of the installed declaration are the runner's cleanup.

conformance_answered_through

The table versions the answers were written against, per area: { DDL => 2, Diff => 4, Bind => 1 }, every list as it stands (version 2 of the Diff list splits U13 into diff-constraint-changed and diff-fk-action-changed). Each case of the three lists is answered: correctly, or by a refusal or deviation of "conformance_refusals".

Version 3 of the Diff list replaces diff-column-dropped-with-index by diff-indexed-column-dropped; it runs.

Version 4 of the Diff list adds the deploy cases (diff-deploy-*): they run through "conformance_deploy", which hands the runner the DBIO::Oracle::Deploy object, so apply and upgrade are the base class's.

conformance_refusals

The cases Oracle does not answer by running to the expected result: four server refusals and one deviation; the other fifteen of the twenty cases are correct, ddl-qualified-source-name among them where the server has the user it names (below). A refusal is thrown by DBIO::Oracle::DDL as a DBIO exception before the server is asked, naming the table and the column of the declaration.

ddl-enum-value-apostrophe (server)

Oracle has no ENUM type. An enum column is refused, not written as a type the server rejects.

ddl-ident-special-chars (server)

An Oracle name may hold any character but the double quote and NUL, quoted or not. The table and the column of the case hold a double quote.

ddl-qualified-source-name (answered; pending, without the user)

A table name with a dot is schema.table, and on Oracle a schema is a user: the case installs other.t as "other"."t" (the schema exactly as spelled) and reads it back through DBIO::Oracle::Introspect for the user other. That needs a user of that exact name (a lower-case, quoted one) and the connected user's ANY privileges ("TABLES IN ANOTHER SCHEMA" in DBIO::Oracle::DDL); the driver creates no user. Where the server has no user other the install is refused ("install" in DBIO::Oracle::Deploy), which this method then declares as a refusal because the declaration is waiting for that user and is not wrong; with the user the declaration disappears and the case runs (the maintainer's test database makes the user other, see maint/k8s/oracle.yaml). The diff postcondition is asked of it as of every case ("conformance_diff_is_empty"), the desired state being built with a temporary user for other. Its objects are removed from the schema afterwards, by the same rule as the user's own.

ddl-type-size-bit (server)

Oracle has no BIT type; the bit column of the case is refused.

ddl-index-on-unique-columns (server)

A unique constraint and an index over exactly the same columns are one index for Oracle (ORA-01408). The declaration is refused with a message that names both and says to declare the key once.

ddl-default-digit-string (deviation)

Not a refusal. The column is CHAR(5) with the default '007'. The default is written as the string (DEFAULT '007', never the number 7: that is what the case guards), and Oracle stores a CHAR(n) value blank-padded to n, so the row reads back as '007 '. That is the type's definition; the driver does not trim values it reads (a ChopBlanks on the handle is the application's own choice). Declared as a deviation with the fact the runner sees, so that any other result, the number 7 included, is still a failure.

The Diff list (table version 4): twenty-three cases, three of them declared, twenty run through correctly -- the three diff-deploy-* cases among them, which run through "conformance_deploy" (the new table with its keys and indexes, expression defaults, the default changed and removed, a view added, dropped or with a new definition (DBIO::Oracle::Diff::View), a column dropped with its index and the unique key it is part of, and the foreign key dropped, added to a new unique constraint or changed in its action and the unique constraint changed, among them; the last needed the fixes described in "DESCRIPTION" in DBIO::Oracle::Diff). The declared ones, every refusal thrown by the driver before the server is asked (DBIO::Oracle::Diff, "_refuse_unfillable" in DBIO::Oracle::Deploy):

diff-column-added-not-null-populated (server)

Oracle adds a NOT NULL column without a default only to an empty table (ORA-01758), and a default for the rows would be a value the driver makes up (not '': that is NULL). The deploy looks at the table before the first statement and refuses when it holds rows.

diff-not-null-over-nulls (server)

A column cannot become NOT NULL over a NULL (ORA-02296); refused when the table holds one, before the first statement.

diff-column-type-change (server)

Oracle changes the datatype of a column only while it is empty, but for a few conversions (ORA-01439; ORA-22858 and ORA-22859 for the LOB types): CHAR and VARCHAR2 into each other and into the national types, those into each other, DATE and TIMESTAMP, NUMBER into FLOAT. The list is measured on 23ai ("_refuse_unfillable" in DBIO::Oracle::Deploy); the deploy refuses any other change between the types it knows when the column holds a value, and leaves a type it does not know to the server.

The Bind list: ten cases, eight run through correctly and two are declared deviations. bind-question-mark-in-literal runs: its literal SQL compares a varchar(20) column, and the driver rewrites no comparison of literal SQL. The long text of the cases is read in full and the characters outside the client character set survive, with nothing set by the application ("LOB length and character set" in DBIO::Oracle::Storage), and bind-non-ascii runs: a string without the UTF-8 flag is upgraded for a character column, a binary column is left alone ("Strings without the UTF-8 flag" in DBIO::Oracle::Storage).

bind-empty-string (deviation)

Oracle has no empty string: for every type but a LOB, '' is NULL, so the nullable integer column of the case takes it. The text column holds '' as an empty LOB, reads it back and finds it (DBIO::Oracle::Storage::LOBSupport).

bind-numeric-exact (deviation)

The value is exact; what differs is its text. A NUMBER(20,4) is read as the shortest text of the number: 1234567890123456.789 for ...7890, .0001 for 0.0001.

The case ddl-view-declared is not in this list: it is answered correctly. Oracle reads unquoted names in upper case and the driver creates every table as the result class spells it, quoted, so a view definition has to quote its names; the runner builds the definition of the case that way ("conformance_install"). A definition a user writes is the user's own SQL and the driver does not guess at it: an unquoted one fails at the server with ORA-00942, a quoted one (SELECT "id", "name" FROM "base", in any shape of FROM and JOIN) is created and works (t/75-conformance-ddl-extra-live.t).

conformance_fact

Reads one fact through DBIO::Oracle::Introspect, for the connected user's schema (or, for table_in_namespace, the user named by the namespace); the vocabulary is the one of "Facts" in DBIO::Test::Conformance. An index is counted as Oracle holds it: the explicit indexes the introspection reports plus one for each unique constraint, which Oracle backs with an index of its own.

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.