> For the complete documentation index, see [llms.txt](https://epromc.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://epromc.gitbook.io/docs/ehome/core-features-and-mechanics/database-and-storage.md).

# Database & Storage Architecture

Technical architecture of eHome database connection pools, Linux hosting path resolution, and safe teleportation mechanics.

eHome is backed by an asynchronous database engine powered by **HikariCP**, engineered to manage tens of thousands of homes across high-population servers with zero main-thread hitching.

***

## ⚡ HikariCP Connection Pooling

eHome shades **HikariCP 6.2.0** to provide rapid, fail-safe connection handling:

* **Connection Timeout:** Enforces a 5-second fail-fast timeout to prevent blocking server threads during connection drops.
* **Leak Detection:** Built-in connection lifecycle monitors prevent memory and pool leaks.
* **Non-Blocking Async DAOs:** All database operations run asynchronously using `CompletableFuture` dispatched via the platform's scheduler.

***

## 🐧 Linux Hosting & Container Self-Healing

On cloud hosting environments (such as Pterodactyl, Docker containers, and Linux VPS), standard SQLite drivers can fail with `path to database does not exist` if directories have case-sensitivity differences or parent directories do not exist prior to pool connection.

eHome incorporates an intelligent **Self-Healing Path Resolver**:

1. Inspects `/plugins/` to locate the exact plugin folder (case-insensitively).
2. Recursively ensures parent directories are created using modern NIO (`Files.createDirectories`).
3. Explicitly initializes the database file (`createNewFile()`) before HikariCP touches the disk.
4. Guarantees 100% plug-and-play operation across any cloud host without manual permission fixes.

***

## 📊 Database Schema & Automatic Migrations

Upon startup, eHome's built-in migrator automatically deploys schema definitions:

### 1. `eh_homes` Table

Stores all player home coordinates, world dimensions, and customization states:

* `player_uuid` (VARCHAR 36) — Unique identifier of the home owner.
* `name` (VARCHAR 32) — Normalized home name.
* `world` (VARCHAR 64) — World identifier.
* `x`, `y`, `z` (DOUBLE) — Exact coordinate locations.
* `yaw`, `pitch` (FLOAT) — Player view angle orientation.
* `bed_icon` (VARCHAR 32) — Selected bed color material name (default: `WHITE_BED`).
* `is_pinned` (BOOLEAN) — Pinned favorite priority flag.
* `created_at`, `updated_at` (BIGINT) — Unix epoch timestamps for activity tracking and purge calculations.

### 2. `eh_pending_invites` Table

Tracks active invitations for the `/home share` system:

* `target_uuid` (VARCHAR 36) — Invited player's UUID.
* `sender_uuid` (VARCHAR 36) — Inviting host's UUID.
* `home_name` (VARCHAR 32) — Target home name.
* `expires_at` (BIGINT) — Auto-expiration timestamp (default: 60 seconds).

***

## 🛡️ Safe Teleportation Scanner

To protect player equipment and hardcore gameplay, eHome executes a rigorous safety scan before initiating teleports:

1. **Suffocation Checks:** The destination feet and head blocks must not be solid, suffocating blocks.
2. **Hazard Detection:** Destination and surrounding blocks cannot be lava, fire, campfire, sweet berry bushes, or wither roses.
3. **Void & Liquid Checks:** Teleportation into open void or hazardous liquids is automatically aborted.
4. **Adaptive Bed Placement:** If the location is safe, the player spawns centered facing their saved yaw and pitch.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://epromc.gitbook.io/docs/ehome/core-features-and-mechanics/database-and-storage.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.