Difference between revisions of "Configuration"

From BaseX Documentation
Jump to navigation Jump to search
(37 intermediate revisions by the same user not shown)
Line 3: Line 3:
  
 
==Configuration Files==
 
==Configuration Files==
BaseX maintains some configuration files, which are stored in the [[#Home Directory|Home Directory]]
+
 
(note that, depending on your OS and configuration, files and folders with a '.' prefix may be hidden):
+
BaseX maintains some configuration files, which are stored in the project’s [[#Home Directory|Home Directory]]:
  
 
* <code>.basex</code> contains all options that are relevant for running the server or standalone versions of BaseX.
 
* <code>.basex</code> contains all options that are relevant for running the server or standalone versions of BaseX.
 
* <code>.basexgui</code> defines all options relevant to the BaseX GUI.
 
* <code>.basexgui</code> defines all options relevant to the BaseX GUI.
* <code>.basexperm</code> contains user name, passwords, and permissions (see [[#User and Log Files|last paragraph]]).
 
* <code>.basexevents</code> contains all existing events (see [[Events]]).
 
 
* <code>.basexhistory</code> contains commands that have been typed in most recently.
 
* <code>.basexhistory</code> contains commands that have been typed in most recently.
 +
* <code>.basexhome</code> can be created by a user to mark a folder as [[#Home Directory|home directory]]. Its contents do not matter, so it is usually empty.
 +
 +
Note that:
 +
 +
* Depending on your OS and configuration, files and folders with a '.' prefix may be hidden.
 +
* In the [[Web Application]] context, options can be defined in the <code>web.xml</code> file.
  
 
==Home Directory==
 
==Home Directory==
Line 16: Line 20:
 
As BaseX is distributed in different flavors, and may be started from different locations, it dynamically determines its home directory:
 
As BaseX is distributed in different flavors, and may be started from different locations, it dynamically determines its home directory:
  
* First, the '''system property''' {{mono|"org.basex.path"}} is checked. If it contains a value, it is chosen as directory path.
+
* First, the '''Java system property''' {{Code|org.basex.path}} is checked. If it contains a value, it is chosen as directory path.
* If not, the '''current user directory''' (defined by the system property {{mono|"user.dir"}}) is chosen if the {{mono|.basex}} configuration file is found in this directory.  
+
* If not, the '''current user directory''' (defined by the system property {{Code|user.dir}}) is chosen if the {{Code|.basex}} or {{Code|.basexhome}} file is found in this directory.  
* Otherwise, the configuration file is searched in the '''application directory''' (the folder in which the project is located).  
+
* If not, the '''application directory''' (the folder in which BaseX is located) is chosen if one of these two files is found.
* In all other cases, the '''user's home directory''' (defined in {{mono|"user.home"}}) is chosen.
+
* In all other cases, a {{Code|basex}} subdirectory in the '''user home directory''' will be returned. The user home directory is retrieved via the {{Code|HOME}} environment variable, or (if unassigned), from the Java system property {{Code|user.home}}.
 +
 
 +
If BaseX is used in an embedded environment (such as a servlet in a [[Web Application]]), it may not immediately be clear what directory was chosen. You can run the XQuery expression <code>Q{org.basex.util.Prop}HOMEDIR()</code> to find out.
  
 
==Database Directory==
 
==Database Directory==
  
A database in BaseX consists of several files, which are all bundled in a folder with the database name.
+
[[Databases]] consists of several binary files. These are located in a directory named by the name of the database. The database root directory is named {{Code|data}}.
If you run the standalone JAR archive, all of these files are stored in a folder in the home directory,
 
which is named {{Mono|BaseXData}}. If you use one of the complete distributions, this directory will be
 
named <code>data</code>, and reside in the application directory.
 
  
 
The database path can be changed as follows:
 
The database path can be changed as follows:
 
* GUI: Choose ''Options'' → ''Preferences'' and choose a new database path.
 
* GUI: Choose ''Options'' → ''Preferences'' and choose a new database path.
* Server/Standalone: <code>[[Options#DBPATH|SET DBPATH [path]]]</code>
+
* General: edit the {{Option|DBPATH}} option in the {{Code|.basex}} configuration file
 +
 
 +
'''Note:''' Existing databases will not automatically be moved to the new destination.
 +
 
 +
==Log Files==
 +
 
 +
Log files are stored in text format in a <code>.logs</code> sub-directory of the database folder (see [[Logging]] for more information).
 +
 
 +
=Changelog=
 +
 
 +
;Version 9.0
 +
 
 +
* Updated: Detection and configuration of home directory and subdirectories.
 +
 
 +
;Version 8.0
  
Note: After having changed the database path, all existing databases have to be manually moved to the new location.
+
* Updated: {{Code|.basexperm}} is obsolete. Users are now stored in {{Code|users.xml}} in the database directory (see [[User Management]] for more information).
  
==User and Log Files==
+
;Version 7.7
Global users, along with their passwords and permissions, are stored in the <code>.basexperm</code> file in the [[#Home Directory|home directory]]. Local users and permissions are stored inside the database files.
 
Log files are stored in text format in the home directory <code>BaseXData/.logs</code> (see [[Logging]] for more information).
 
  
[[Category: Internals]]
+
* Updated: The {{Code|.basexhome}} file marks a folder as [[#Home Directory|home directory]].

Revision as of 14:31, 10 April 2019

This article is part of the Advanced User's Guide. It gives some more insight into the configuration of BaseX.

Configuration Files

BaseX maintains some configuration files, which are stored in the project’s Home Directory:

  • .basex contains all options that are relevant for running the server or standalone versions of BaseX.
  • .basexgui defines all options relevant to the BaseX GUI.
  • .basexhistory contains commands that have been typed in most recently.
  • .basexhome can be created by a user to mark a folder as home directory. Its contents do not matter, so it is usually empty.

Note that:

  • Depending on your OS and configuration, files and folders with a '.' prefix may be hidden.
  • In the Web Application context, options can be defined in the web.xml file.

Home Directory

As BaseX is distributed in different flavors, and may be started from different locations, it dynamically determines its home directory:

  • First, the Java system property org.basex.path is checked. If it contains a value, it is chosen as directory path.
  • If not, the current user directory (defined by the system property user.dir) is chosen if the .basex or .basexhome file is found in this directory.
  • If not, the application directory (the folder in which BaseX is located) is chosen if one of these two files is found.
  • In all other cases, a basex subdirectory in the user home directory will be returned. The user home directory is retrieved via the HOME environment variable, or (if unassigned), from the Java system property user.home.

If BaseX is used in an embedded environment (such as a servlet in a Web Application), it may not immediately be clear what directory was chosen. You can run the XQuery expression Q{org.basex.util.Prop}HOMEDIR() to find out.

Database Directory

Databases consists of several binary files. These are located in a directory named by the name of the database. The database root directory is named data.

The database path can be changed as follows:

  • GUI: Choose OptionsPreferences and choose a new database path.
  • General: edit the DBPATH option in the .basex configuration file

Note: Existing databases will not automatically be moved to the new destination.

Log Files

Log files are stored in text format in a .logs sub-directory of the database folder (see Logging for more information).

Changelog

Version 9.0
  • Updated: Detection and configuration of home directory and subdirectories.
Version 8.0
  • Updated: .basexperm is obsolete. Users are now stored in users.xml in the database directory (see User Management for more information).
Version 7.7