Skip to main content

Database metadata

ZPA analyzes source files, so by default it knows only the objects declared in them. Tables, views, synonyms, object types and many packages usually live only in the database. When ZPA can connect to an Oracle database, it reads their definitions before the analysis and uses them to resolve names that the source files alone can't answer:

  • %TYPE and %ROWTYPE anchors on tables and views get the column types from the dictionary;
  • names reached through private and public synonyms are followed to their targets;
  • calls to packages, standalone subprograms and object type methods of the database bind to their signatures, and their results get the declared type;
  • rules that need column details can check them, such as NullTestOnNotNullColumn, which needs to know which columns can never be null;
  • the database version is used for conditional compilation when you don't set it.

Without a connection the analysis works as before; references to database objects simply stay unresolved. Tables and synonyms created by CREATE TABLE and CREATE SYNONYM statements in the analyzed files are read the same way, with or without a connection.

What ZPA reads​

ZPA reads the data dictionary once per analysis, before analyzing any file, in a read-only transaction. It queries only ALL_* views, so the user only sees the objects it owns or has privileges on. A user with read access to the analyzed schemas is enough; it never needs to modify anything.

You choose what to read:

  • Schemas: every table, view, column, synonym, object type and subprogram signature owned by each listed schema.
  • Relations: only the listed tables and views, as SCHEMA.RELATION, for when reading a whole schema is too much.
  • Public synonyms: read by default. Without them, a name that could resolve through a public synonym stays unresolved.
InformationDictionary views
Tables, views and columnsALL_ALL_TABLES, ALL_VIEWS, ALL_TAB_COLS
Objects and synonymsALL_OBJECTS, ALL_SYNONYMS
Object types, with their supertypesALL_TYPES, ALL_TYPE_ATTRS, ALL_TYPE_METHODS, ALL_METHOD_PARAMS, ALL_METHOD_RESULTS
Parameters and results of package and standalone subprogramsALL_ARGUMENTS

Oracle Database 11.2 and newer are supported. Each dictionary query times out after 60 seconds.

Configure the connection​

ZPA doesn't ship the Oracle JDBC driver. Download ojdbc17.jar from Oracle's JDBC downloads page, which also lists the database versions each driver supports, and point ZPA to it. The password is never written in the configuration: ZPA reads it from an environment variable, ZPA_ORACLE_PASSWORD by default, and rejects a URL that contains credentials.

Set the connection as analysis parameters, in sonar-project.properties or with -D on the scanner command line. They are not server settings, so they don't appear in the SonarQube administration pages.

sonar.zpa.oracle.url=jdbc:oracle:thin:@//db.example.com:1521/ORCLPDB1
sonar.zpa.oracle.user=ZPA_READER
sonar.zpa.oracle.schemas=HR,SALES
sonar.zpa.oracle.driverPath=drivers/ojdbc17.jar
export ZPA_ORACLE_PASSWORD=...
sonar-scanner
ParameterDescriptionDefault
sonar.zpa.oracle.urlJDBC URL of the database. Enables metadata reading.
sonar.zpa.oracle.userDatabase user.
sonar.zpa.oracle.passwordEnvName of the environment variable that holds the password.ZPA_ORACLE_PASSWORD
sonar.zpa.oracle.schemasComma-separated schemas to read completely.
sonar.zpa.oracle.relationsComma-separated SCHEMA.RELATION tables and views to read individually.
sonar.zpa.oracle.publicSynonymsRead every public synonym: true or false.true
sonar.zpa.oracle.driverPathPath to the JDBC driver JAR, relative to the project base directory.

The URL needs the user and at least one schema or relation. When the URL is not set, nothing connects, and setting any other connection parameter is an error.

Schema and relation names, here and in the compilation schema, are read as Oracle reads identifiers: HR and hr both name the schema HR; write a name stored in lowercase in double quotes ("hr").

A configuration error, a missing driver, a connection failure or a failed dictionary query stops the analysis; ZPA never continues with partial metadata. Error messages and logs never show the URL or the password. The ZPA CLI exits with code 2 for configuration errors and 3 for connection and dictionary failures.

Compilation schema​

Oracle resolves an unqualified name in the schema where the unit is compiled. Tell ZPA which schema that is, so that a name like employees finds HR.EMPLOYEES and a unit created without an owner can be reached by a name qualified with that schema. These settings also work without a database connection.

# Schema of every unit created without an owner
sonar.zpa.oracle.compilationSchema=HR
# Or one schema per folder: glob=SCHEMA pairs, relative to the project base directory; the first match wins
sonar.zpa.schemaPaths=src/hr/**=HR,src/sales/**=SALES

Files that match no pattern use the compilation schema.