Skip to main content

Configuration: Database repositories


Your AVIX server will need restarting, if you make any changes to configuration files.

If you intend to make use of a relational database management system (DBMS) as the back-end for AVIX data, you need to configure the AVIX server with the necessary connection information. 

A server repository represents the connection to a certain database, which in turn exists in a DBMS on an accessible host. At the time of writing, AVIX supports the following database systems:

If you are looking for information on how to set up a MS SQL Server database for AVIX purposes, see the document "MS SQL SERVER FOR AVIX"

REPOSITORIES.XML configuration file

By default, the AVIX server will pick up the repositories configuration from an XML file called repositories.xml, residing in the root directory of the AVIX server. 

In a clean server installation, no such file exists yet (see also "Default behavior" below). However, there is an example file entitled repositories.xml.example that can be used to get started:

image.png

This is the content of the example file, showcasing the usage of both PostgreSQL, Microsoft SQL Server and H2 databases.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<repositoryConfig>
	<!-- POSTGRE SQL repository example -->
	<repository name="repo1" type="se.solme.avix.server.cdo.postgresql"
		serverHost="localhost"
		portNumber="5432"
		databaseName="avix1"
		databaseUser="postgres"
		databasePassword="postgres"
		useSSL="false"/>
	
	<!-- MS SQL Server repository example -->
	<repository name="repo2" type="se.solme.avix.server.cdo.mssql"
		serverHost="localhost"
		portNumber="1433"
		databaseName="avix2"
		databaseUser="user"
		databasePassword="pw"
		useSSL="false"/>
	
	<!-- MS SQL Server repository example 2 (same server, another db) -->
	<repository name="repo3" type="se.solme.avix.server.cdo.mssql"
		serverHost="localhost"
		portNumber="1433"
		databaseName="avix3"
		databaseUser="user"
		databasePassword="pw"
		useSSL="false"/>

    <!-- MS SQL Server repository example using Windows/integrated authentication -->
    <repository name="repo2" type="se.solme.avix.server.cdo.mssql"
		serverHost="localhost"
		portNumber="1433"
		databaseName="avix3"
		integratedSecurity="true"
		authenticationScheme="NativeAuthentication"
		useSSL="false"/>
		
	<!-- h2 repository example (self-hosted by the AVIX server) -->
	<repository name="admin" type="se.solme.avix.server.cdo.h2" databaseName="admin"/>
</repositoryConfig>

A note on windows (integrated) authentication for MS sql server

When AVIX5 server is configured to use Windows/integrated authentication with "NativeAuthentication", the Windows service that is running AVIX will typically need to have its "Log On As" set to a Windows account, which has access to the SQL Server instance. Example:

image.png

See here to learn more on how to change the user account of the AVIX Server Service. 

Configure your database repository

To connect the AVIX server to a database you intend to use for the AVIX application, make sure to create the repositories.xml file, and define a "repository" XML element with the appropriate values. Example of repositories.xml, which connects to an available Postgre SQL DBMS:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<repositoryConfig>
	<repository name="repo1" 
                type="se.solme.avix.server.cdo.postgresql"
				serverHost="localhost"
				portNumber="5432"
				databaseName="testavix2"
				databaseUser="postgres"
				databasePassword="c863qsQt5sr3WlRPdogc1m"
				useSSL="false"/>
</repositoryConfig>

When finished, restart the server. 


Verify database repository and connection

To test the example configuration described above, you may launch an AVIX application and connect to your server. 

  1. Start AVIX5 application
  2. Open the "Database browser" dialog: 

    1. image-1645786778348.png

  3. Connect to your server, to see all repositories. 
    1. Host: If you are running the AVIX application on the same machine as the server is running, enter "localhost". Otherwise, the host name or its IP will have to be inserted. 
    2. Port: The default port is 45500
    3. Example of connection URL:  localhost:45500
    4. Terminate with "Enter", to connect. 
  4. If connection could be established, you should see the repository that the server holds:

    1. image-1645787102481.png

  5. In the example above, no AVIX storage yet exists in the repository. 
  6. Create your first storage, if desired.


Troubleshooting

The log file logs/AviXLogfile.log of the server can be inspected, to see information relating to repository management. Some excerpts indicating what you can look out for .

The path to the repositories.xml that the server reads should be presented:

AviX CDO Server starting
Default location for CDO Server 'repositories.xml' file is in Platform.getInstallLocation(), resulting in: file:/C:/AVIX/Servers/se.solme.avix.server.product-win32.win32.x86_64/
...
CDO Server 'repositories.xml' config file is read from existing file C:\AVIX\Servers\se.solme.avix.server.product-win32.win32.x86_64\repositories.xml

Information relating to creation of defined repository: 

Creating CDO repository for PostgreSQL with name: "repo1"
Server:localhost, Port:5432, DbName:testavix2, User:postgres, SSL:false

If successful connection, you should be able to see something like:

(s.s.a.s.c.p.PostgreSQLUtil:64)    - SUCCESS creating repo: "repo1"

In case of failure, expect something like this instead: 

s.s.a.s.c.p.PostgreSQLUtil:67)    - Unsuccesful with creating the repo.
org.eclipse.net4j.db.DBException: org.postgresql.util.PSQLException: FATAL: password authentication failed for user "postgres"
	at org.eclipse.net4j.internal.db.DataSourceConnectionProvider.getConnection(DataSourceConnectionProvider.java:56)
	at org.eclipse.emf.cdo.server.internal.db.DBStore.getConnection(DBStore.java:220)
	...

 

default behavior

As stated above, a clean server installation contains no accessible repositories.xml file. However, when starting without an explicit configuration file, the AVIX server will by default an embedded H2 database repository. 

This repository will be published and thus visible to connected AVIX clients. In the example image below, avix is this H2 db repository:

image.png


relevant preferences

Preferences are stored in the configuration/se.solme.avix.prefs file, which you may edit to serve your purposes.

#
# CDO Server settings
#
[se.solme.avix.server.cdo]
cdo.server.repository.configuration=\\SomeServer\\AVIXConfiguration\\repositories.xml
cdo.server.repository.name = myRepo

  • cdo.server.repository.configuration: can be used to change where the AVIX server reads the repositories configuration file from. The default value is Platform.getInstallLocation(), which will be the root of the AVIX Server installation.
  • cdo.server.repository.name: the value of this will be the name of the default H2 repository. The default value is avix.

At the time of writing, the default behavior to create an H2 repository (in the lack of an explicit repositories configuration) cannot be suppressed. 



Back to top