EN

Installation and Configuration

AEOS Liquibase
Database refactoring tool

Version 13 24-08-2020
Installation and Configuration | AEOS Liquibase EN

Date Version Changes

Removed references to MySQL

24-08-2020 13
Removed section 'Manually updating an old AEOS version before 2.4.4'.

10-07-2018 12 Updated for AEOS 3.4.

15-11-2017 11 New template.

24-12-2015 10 Updated for AEOS 3.2.

30-10-2014 9 New logo, new header.

07-04-2014 8 Intermediate server removed.

FAQ updated, 'Wait for changelog lock' message added.

16-05-2013 7
Manual update database description altered.

19-07-2012 6 For Oracle: URL updated.

For MSSQL: URL updated.

29-03-2012 5 Use of Windows Authentication and Named Instance described.
FAQ updated, onFail message added.

17-01-2012 4 Chapter 2.6 updated.

22-11-2011 3 Layout changed, added items to make things more clear.

15-06-2011 2 Intermediate server added.

02-05-2011 1 Initial release, incl. small changes.

Manual version 13 2/10

Installation and Configuration | AEOS Liquibase EN

Contents
1. INTRODUCTION 4

2. FUNCTIONALITY 5
2.1 CHANGE SETS 5
2.2 USING THE AEOS SETUP.EXE 5
2.3 MANUALLY CREATING THE DATABASE 6
2.4 MANUALLY INITIALISING/UPDATING THE AEOS DATABASE 6
2.4.1 WINDOWS AUTHENTICATION 7
2.4.2 NAMED INSTANCE 7

3. FREQUENTLY ASKED QUESTIONS 8

Manual version 13 3/10

 Installation and Configuration | AEOS Liquibase EN

1. Introduction
Liquibase is a tool (written in Java) which can be used to upgrade several database types. Instead
of writing SQL statements for creating/modifying tables, views, insert, etc. for several SQL-
database types, you describe these actions in XML.
Using Liquibase, developers have to maintain only 1 set of files and don’t need knowledge of the
specific database script languages. Liquibase will generate from those files, database type
depending SQL scripts.
Due to these features we can now supply AEOS supporting the following database types:
• Microsoft SQL-Server
• Oracle
• PostgreSQL

Manual version 13 4/10

 Installation and Configuration | AEOS Liquibase EN

2. Functionality
This chapter describes the functionality of Liquibase.

2.1 Change sets

Each adaptation of the database structure is indicated in a change-set. This is important because
data concerning a change-set is stored in a separate table (databasechangelog) in the database.
Liquibase uses the data in this table to find out if the adaptation is already been carried out.
Example of a change-set:
<changeSet id="create_table_accessarea" author="evert">
<createTable tableName="accessarea">
<column name="objectid" type="BIGINT">
<constraints nullable="false" primaryKey="true" primaryKeyName=
"PK__accessarea__40F9A68C"/>
</column>
<column name="name" type="VARCHAR(50)">
<constraints nullable="false"/>
</column>
<column defaultValue="" name="description" type="VARCHAR(50)"/>
<column name="removaldate" type="DATETIME"/>
</createTable>
</changeSet>

The “databasechangelog” table doesn’t contain the SQL command that is executed. It contains a
reference to that command, by ID and filename. It also stores a checksum of the executed
command.
When Liquibase is updating the database, it check if the commands should be executed, using ID
and Filename. If not, Liquibase will check if the checksum of the SQL-command is still equal to the
already executed command. This should always be the same.
When a command cannot be executed, Liquibase will stop immediately. It will not go on with the
other commands. An error will be generated; this error contains the ID, filename and required
checksum when checksum fails. The problem must first be resolved before you can go on.

2.2 Using the AEOS setup.exe

The AEOS setup will automatically do all necessary steps;
1. Install the AEOS software
2. Create the database when needed
3. Update the database when needed
This way you don’t need to know anything about database characteristics.
After installation Liquibase log file (liquibase.log) will be created in .\AEOS\AEserver\sql_scripts\.

Manual version 13 5/10

Installation and Configuration | AEOS Liquibase EN

2.3 Manually creating the database

Manually here means not using the AEOS setup.
The AEOS setup normally will perform actions to create the database. For all database types
scripts needed by the setup will be deployed in the .\sql_scripts\<databasetype> directory.
You can use a tool like the Enterprise Manager to generate a database or you can use the scripts
which are installed by the AEOS setup (keep in mind that you have to change those scripts).

2.4 Manually initialising/updating the AEOS database

Manually here means not using the AEOS setup.
By introducing Liquibase no SQL-scripts are deployed by the setup for creating/updating the
database.
The AEOS setup deploys now an executable jar, aeosdb-liquibase.jar.
With this jar all actions are now performed on the database. It is possible to generate SQL scripts
for initialising or updating the database using that executable jar. In both cases a database
connection is required to determine the current state of the database.
Usage:
<j-path>java -jar <jarfile> -url <db.url> -u <user> -p <password> [options]
Options:
<j-path> The path to the java runtime environment, default C:\AEOS\jre\bin\
<jarfile> The executatble jar file, path might be needed.
<db.url> The db-url, how to connect to the database.
-ucf: provide a update changelog file (default: 'db.changelog-create.xml')
-sync: provide a sync file (default: null)
-v: provide a sync version (default: null)
-s: provide a schema (default: <the database default>)
-c: provide a context (e.g. 'unicode', default: 'default') (MSSQL only)
Required for oracle:
-ts: provide a tablespace for tables (set empty value for default)
-ts_indx: provide a tablespace for indexes (set empty value for default)

To initialise/update an AEOS database:

<j-path>java -jar aeosdb-liquibase.jar -u <username> -p <password> -url <connection-string>
e.g. for MSSQL:
<j-path>java -jar aeosdb-liquibase.jar -u nedap -p nedap –url
jdbc:sqlserver://localhost;portNumber=1433;databaseName=aeosdb

e.g. for Oracle

<j-path>java -jar aeosdb-liquibase.jar -u nedap -p nedap -url
jdbc:oracle:thin:@localhost:1521/aeosdb
e.g. for PostgreSQL
<j-path>java -jar aeosdb-liquibase.jar -u nedap -p nedap -url
jdbc:postgresql://localhost:5432/aeosdb

When creating a Unicode database for MSSQL you have to perform the action:

Manual version 13 6/10

Installation and Configuration | AEOS Liquibase EN

• Create unicode tables;

<j-path>java -jar aeosdb-liquibase.jar -c unicode -u ... -p ... -url ...

2.4.1 Windows authentication

This is only possible for MSSQL-Server databases.
The path to the ntlmauth.dll file need to be specified with -Djava.library.path=<dll-path>.
The parameters <-u nedap -p nedap> must be replaced with <-u *WinAuth* -p *WinAuth*>.
The total command looks like:
<j-path>java -Djava.library.path=<dll-path> -jar aeosdb-liquibase.jar -url
jdbc:sqlserver://localhost;portNumber=1433;databaseName=aeosdb <-u *WinAuth* -p *WinAuth*

2.4.2 Named Instance

This is only possible for MSSQL-Server databases.
Only the url has to be extended with < instanceName=instName> and the portNumber value has
to be removed.
The url will then look like:
-url jdbc:sqlserver://localhost;portNumber=;instanceName=<NAME>;databaseName=aeosdb;
<NAME> has to be replaced with the name of the named instance.

Manual version 13 7/10

 Installation and Configuration | AEOS Liquibase EN

3. Frequently asked questions

• Which java version is needed?
Java version 8 is required; the AEOS setup installs this version.
• Do I have to run SQL script before running the AEOS setup?
No, the AEOS setup will do all necessary steps to update the database.
• Do I have to install a jdbc driver?
No, in the Liquibase jar the 4 jdbc drivers are included.
• I want a Unicode Database; do I have to do something special?
In one of the windows in the AEOS-setup you can check a check-box, the setup will do all
necessary actions needed.
When you want to do this manually you will have to the next steps:
1. For PostgreSQL and Oracle create database which supported UTF8 and perform the next
Liquibase command:
<j-path>java -jar aeosdb-liquibase.jar -u <username> -p <password> -url <connection-
string>
2. For MSSQL create a database and perform the next Liquibase command:
• create unicode tables:
<j-path>java -jar aeosdb-liquibase.jar -c unicode -u ... -p ... -url ... (*)
• Can I generate SQL scripts that I want to use to update my database?
No, from AEOS version 3.4, this is not supported anymore.
• Can I generate update scripts manually (so not using the AEOS setup)?
No, from AEOS version 3.4, this is not supported anymore.
• Does Liquibase also handle the special scripts, such as WinXS2000–AEOS, Planon, AEOS-
WinXS2000, AEOS-LoXS?
Liquibase can only handle scripts for 'AEOS', all other scripts are not supported.
• onFail message in log file
In the log file a kind of error message might appear, such as:
INFO 26.03.12 13:55:liquibase: Marking ChangeSet: upgrade/db.changelog-
2.4.5.xml::update_Id_LookupServerDiscoverEvent_from_137_to_140::evert::(Checksum:3:d934f81ca825e93f
60d4dd2c5d5a0a8f) ran despite precondition failure due to onFail='MARK_RAN': db.changelog-create.xml :
SQL Precondition failed. Expected '1' got '0'
This is NOT an error, a statement is now 'conditionally' executed. Conditionally means
'depending on' a DB state. In the example above, it is not executed (Expected '1' got '0').
• Waiting for changelog lock.... in log file
When this message appears multiple times, Liquibase cannot update your database due to a
lock. This means that an update is currently proceeding. When this is not the case it could be
that a previous update crashed and left a lock on the database. This lock is stored in the table
databasechangeloglock, the contents is normaly as the picture below. Update the table when
needed.

Manual version 13 8/10

Installation and Configuration | AEOS Liquibase EN

Manual version 13 9/10

Copyright
Copyright © Nedap N.V. All rights reserved. The information in this document is subject
to change without notice, it is not to be reproduced in any way, in whole or in part,
without the written consent of Nedap N.V. Nedap AEOS is a registered trademark of
Nedap N.V. All trademarks referenced belong to their respective owners.

Disclaimer
Nedap N.V. has made every effort to ensure the accuracy of the information contained
in this document. However, Nedap N.V. makes no representations or warranties
whatsoever whether express or implied as to the accuracy, correctness, completeness
or fit-for-purpose or suitability for the purpose of this product. You use the products at
your own risk. Nedap N.V. excludes any liability to the maximum extent permitted by
applicable law for the damages caused by errors or failures made during the installation
or improper use of this product or by not applying the instructions stated in this
document.
Nedap N.V. reserves the right to make improvements or amendments to this document
and/or the products described therein at any time without any notification. The latest
version of this document can be found on portal.nedapsecurity.com. Please download
the latest version of this document and keep a copy for your own records.
This document can be published in various languages but only the English version will
prevail. Nedap N.V. assumes no responsibility for any errors due to translations into
other languages.

Nedap Security Management

P.O. Box 103
NL - 7140 AC Groenlo
+31 (0)544 471 111
info@nedapsecurity.com
www.nedapsecurity.com