Database Setup

Relevant source files

The following files were used as context for generating this wiki page:

• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/database/provider/NexAuthMySQLDatabaseProvider.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/database/provider/NexAuthPostgreSQLDatabaseProvider.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/database/provider/NexAuthSQLiteDatabaseProvider.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/database/provider/NexAuthSQLDatabaseProvider.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/database/connector/AuthenticMySQLDatabaseConnector.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/database/connector/AuthenticPostgreSQLDatabaseConnector.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/database/connector/AuthenticSQLiteDatabaseConnector.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/util/GeneralUtil.java

NexAuth provides robust and flexible database support for storing user authentication data. It is designed to work with several popular SQL databases and includes a system for automatic schema management and data migration. The entire database system is configured through the main config.yml file.

The architecture separates connection management from data access logic, allowing for a clean and extensible design. This page details the supported databases, the underlying architecture, configuration options, the database schema, and the migration process. For information on migrating from other authentication plugins, see the Database Migration section.

Supported Databases

NexAuth has built-in support for MySQL, PostgreSQL, and SQLite. The desired database type is selected using the database.type key in the configuration.

database.type Value	Database	Description
nexauth-mysql	MySQL	Connects to a MySQL or MariaDB server.
nexauth-postgresql	PostgreSQL	Connects to a PostgreSQL server.
nexauth-sqlite	SQLite	Uses a local SQLite database file.

Sources: ConfigurationKeys.java:161-168

Core Architecture

The database system is built on two primary components: DatabaseConnector and DatabaseProvider. This separation of concerns ensures that connection-specific details are isolated from the data manipulation logic.

• DatabaseConnector: Manages the physical connection to the database. Implementations like AuthenticMySQLDatabaseConnector use the HikariCP library for efficient connection pooling. They are responsible for establishing, disconnecting, and providing connection instances.
• DatabaseProvider: Implements the ReadWriteDatabaseProvider interface to handle all CRUD (Create, Read, Update, Delete) operations for user data. Implementations like NexAuthMySQLDatabaseProvider use a DatabaseConnector to execute SQL queries.

The following diagram illustrates the relationship between these components for a MySQL setup.

This diagram shows how AuthenticNexAuth uses a DatabaseProvider which in turn relies on a DatabaseConnector for database access.

Sources: AuthenticNexAuth.java:164, NexAuthSQLDatabaseProvider.java:23, NexAuthMySQLDatabaseProvider.java:17, AuthenticMySQLDatabaseConnector.java:23, API/src/main/java/xyz/xreatlabs/nexauth/api/database/WriteDatabaseProvider.java

Database Initialization Flow

On plugin startup, NexAuth follows a specific sequence to initialize the database connection and ensure the schema is up-to-date.

1. Register Providers & Connectors: The setupDB() method registers all available DatabaseConnector and DatabaseProvider implementations.
2. Read Configuration: The connectToDB() method reads the database.type from the configuration to determine which database to use.
3. Establish Connection: It creates and connects the appropriate DatabaseConnector (e.g., AuthenticMySQLDatabaseConnector). If the connection fails, the server shuts down to prevent data corruption.
4. Instantiate Provider: A DatabaseProvider (e.g., NexAuthMySQLDatabaseProvider) is created with the active connector.
5. Validate Schema: The validateSchema() method is called on the provider. This method automatically creates the necessary tables if they don't exist and adds any missing columns, ensuring the database schema is always correct for the current plugin version.

The process is visualized in the flowchart below.

Configuration

Database connection details are configured in the database.properties section of the config.yml.

MySQL/MariaDB Configuration

Set database.type to nexauth-mysql.

Key	Default Value	Description
host	localhost	The host of the database.
database	nexauth	The name of the database.
user	root	The user of the database.
password	""	The password of the database.
port	3306	The port of the database.
max-life-time	600000	The maximum lifetime of a connection in milliseconds.
jdbc-url	jdbc:mariadb://%host%:%port%/%database%?autoReconnect=true&zeroDateTimeBehavior=convertToNull	The JDBC URL. Do not touch unless you know what you are doing.

Sources: AuthenticMySQLDatabaseConnector.java:80-120

PostgreSQL Configuration

Set database.type to nexauth-postgresql.

Key	Default Value	Description
host	localhost	The host of the database.
database	nexauth	The name of the database.
user	root	The user of the database.
password	""	The password of the database.
port	5432	The port of the database.
max-life-time	600000	The maximum lifetime of a connection in milliseconds.

Sources: AuthenticPostgreSQLDatabaseConnector.java:88-123

SQLite Configuration

Set database.type to nexauth-sqlite.

Key	Default Value	Description
path	user-data.db	Path to the SQLite database file, relative to the plugin's data folder.

Sources: AuthenticSQLiteDatabaseConnector.java:79-84

Database Schema

NexAuth uses a single table named librepremium_data to store all user information. The schema is automatically created and managed by the validateSchema method.

The following diagram shows the structure of the librepremium_data table.

Table Columns

Column	Type	Constraints	Description
uuid	VARCHAR(255)	NOT NULL, PRIMARY KEY	The unique identifier for the user.
premium_uuid	VARCHAR(255)	UNIQUE	The user's premium (online-mode) UUID, if they have one.
hashed_password	VARCHAR(255)		The user's hashed password.
salt	VARCHAR(255)		The salt used for password hashing.
algo	VARCHAR(255)		The algorithm used for password hashing (e.g., BCrypt-2A).
last_nickname	VARCHAR(255)	NOT NULL, UNIQUE	The last known in-game name of the user.
joined	TIMESTAMP		Timestamp of the user's first join.
last_seen	TIMESTAMP		Timestamp of the user's last session.
secret	VARCHAR(255)		The secret key for TOTP-based 2FA.
ip	VARCHAR(255)		The last known IP address of the user.
last_authentication	TIMESTAMP		Timestamp of the last successful login.
last_server	VARCHAR(255)		The name of the last server the player was connected to.
email	VARCHAR(255)		The user's email address for password recovery.

Sources: NexAuthSQLDatabaseProvider.java:231-267

Database Migration

NexAuth includes a utility to migrate data from other popular authentication plugins. This process is controlled via the migration section in the configuration file.

To perform a migration, set migration.on-next-startup to true and configure the migration.type and old database credentials. The migration will run once on the next server start.

Migration Configuration

Key	Default Value	Description
migration.on-next-startup	false	If true, a database migration will be performed on the next startup.
migration.type	authme-sqlite	The source of the migration (e.g., authme-mysql, nlogin-sqlite).
migration.old-database...		Connection details for the old database, structured similarly to the main database properties.

A wide variety of migration sources are supported, including AuthMe, JPremium, NLogin, LoginSecurity, and more.

Sources: ConfigurationKeys.java:182-242, AuthenticNexAuth.java:556-651