> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loupp.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Databases

> Create and manage databases and database users on your servers in Loupp

## Overview

Loupp provides comprehensive database management capabilities, allowing you to create, configure, and manage multiple databases and users on your servers. Each server can host multiple databases with different access permissions and configurations.

## Database Management

### Creating a New Database

<Steps>
  <Step title="Access database management">
    Navigate to your server dashboard and click on the "Databases" tab to access the database management interface.
  </Step>

  <Step title="Configure database details">
    Fill in the database configuration:

    * **Database Name**: Choose a unique name for your database (alphanumeric and dashes only)
    * **Default Database**: Optionally set this as the default database for the server
  </Step>

  <Step title="Create database">
    Click "Create Database" to begin the automated setup process.
  </Step>
</Steps>

### Database Configuration

When you create a database, Loupp automatically:

* **Creates Database**: Sets up the database with proper permissions using the server's configured SQL version (MySQL, MariaDB, or PostgreSQL)
* **Configures Access**: Sets up root access and user permissions
* **Optimizes Settings**: Applies performance and security optimizations
* **Integrates with Applications**: Makes the database immediately available for your web applications

<Info>
  Databases are created using the server's configured SQL version (MySQL, MariaDB, or PostgreSQL) and are immediately available for use.
</Info>

## Database User Management

### Creating Database Users

<Steps>
  <Step title="Configure user details">
    Set up the database user with the following information:

    * **Username**: Choose a unique username for database access (alphanumeric and dashes only)
    * **Password**: Set a secure password for the user
    * **Host**: Specify the host from which the user can connect (defaults to 'localhost')
  </Step>

  <Step title="Create user">
    Click "Create User" to create the database user account.
  </Step>
</Steps>

### User Permissions

Database users are created with comprehensive permissions based on the database type:

* **MySQL/MariaDB Users**: Full privileges on all databases (`GRANT ALL ON *.*`)
* **PostgreSQL Users**: Full administrative privileges including `CREATEDB`, `CREATEROLE`, `REPLICATION`, and `BYPASSRLS`

<Warning>
  Database passwords are encrypted and securely stored. Keep these credentials secure and don't share them publicly.
</Warning>

## Database Operations

<Warning>
  **All database operations are delicate services that can significantly impact your server's performance, stability, and data integrity.** These operations directly affect your database system and may temporarily disrupt services. Always perform operations during maintenance windows and ensure you have proper backups.
</Warning>

### Available Actions

<AccordionGroup>
  <Accordion title="Create">
    Add new databases and users to your server with automatic configuration.
  </Accordion>

  <Accordion title="Delete">
    Remove databases and users that are no longer needed (with safety checks).
  </Accordion>

  <Accordion title="Download/Export">
    Export databases for backup or migration purposes.
  </Accordion>

  <Accordion title="Set Default">
    Designate a database as the server's default database.
  </Accordion>
</AccordionGroup>

### Database Deletion

<Warning>
  **Database deletion is an extremely delicate operation that permanently removes all data and cannot be undone.** Always create backups before deletion and double-check that you're deleting the correct database. This operation affects server stability and data integrity.
</Warning>

When deleting databases:

* **Safety Checks**: Loupp prevents deletion of default databases
* **Minimum Database Protection**: Ensures at least one database remains on the server

<Warning>
  Database deletion is irreversible. Ensure you have backups before deleting important databases.
</Warning>

### Database User Deletion

<Warning>
  **Deleting database users is a delicate operation that can break application connections and cause service disruptions.** Users with active database connections will lose access immediately, potentially causing application failures. Always verify that no critical applications depend on the user before deletion.
</Warning>

When deleting database users:

* **Minimum User Protection**: At least one database user must remain on the server
* **System User Protection**: The 'loupp' system user cannot be deleted
* **Connection Impact**: Active connections using the deleted user will be terminated
* **Application Dependency**: Ensure no applications rely on the user before deletion

### Database Download/Export

<Warning>
  **Database export operations expose your sensitive data to potential security risks.** Exported database files contain all your data in plain text and are accessible via download links sent via email. Only export databases when absolutely necessary and ensure the exported data is handled securely. Consider the sensitivity of your data before proceeding with any export operation.
</Warning>

Loupp provides database export functionality:

* **Automated Export**: Uses mysqldump to create SQL exports
* **Compression**: Automatically compresses exports using gzip
* **Email Delivery**: Sends download links via email for security
* **Auto-Cleanup**: Automatically removes exported files after 5 minutes

### Setting Default Database

You can designate any database as the server's default:

* **Single Default**: Only one database can be default at a time
* **Application Integration**: Default databases are prioritized for application connections

## Database Integration

### Database Connection URL

Loupp provides a convenient database connection URL that you can use with any database client or application:

* **Connection URL**: A pre-formatted connection string for your database
* **Database Client Support**: Compatible with popular database management tools like:
  * MySQL Workbench
  * phpMyAdmin
  * DBeaver
  * TablePlus
  * Command line clients
* **Secure Access**: Uses your configured database credentials
* **Immediate Availability**: Available as soon as your database is created

### Application Integration

Databases created in Loupp are automatically available to be used in your projects:

```php theme={null}
// Laravel database configuration example
DB_CONNECTION=mysql
DB_HOST=localhost
DB_DATABASE=your_database_name
DB_USERNAME=your_database_user
DB_PASSWORD=your_database_password
DB_PORT=3306
```

### Using the Connection URL

1. **Copy the URL**: From the "Database Connection Url" section in your server dashboard
2. **Database Client**: Paste the URL into your preferred database management tool
3. **Enter Password**: Manually enter your loupp user password when prompted
4. **Connect**: Establish the connection to manage your database

<Tip>
  The connection URL provides all the necessary connection details, making it easy to connect from any database client or application without manually configuring connection parameters.
</Tip>

## Security and Access Control

<Tip>
  To configure firewall rules for database access, visit the [Network page](/docs/server/network) in your server documentation. There you can manage port restrictions, IP whitelisting, and connection monitoring for your database services.
</Tip>

## Troubleshooting

### Common Database Issues

<AccordionGroup>
  <Accordion title="Connection Refused">
    * Check if the database service is running
    * Verify firewall rules allow database connections
    * Confirm database user credentials are correct
  </Accordion>

  <Accordion title="Permission Denied">
    * Verify user permissions are properly configured
    * Check if the user has access to the specific database
    * Ensure the user can connect from the specified host
  </Accordion>

  <Accordion title="Database Not Found">
    * Confirm the database name is spelled correctly
    * Check if the database was successfully created
    * Verify the database exists on the server
  </Accordion>

  <Accordion title="Cannot Delete Database">
    * Ensure the database is not set as default
    * Verify at least one other database exists on the server
    * Check if any applications are actively using the database
  </Accordion>

  <Accordion title="Cannot Delete User">
    * Ensure at least one database user remains
    * Verify the user is not the protected 'loupp' system user
    * Check if the user has active database connections
  </Accordion>
</AccordionGroup>

<Check>
  Successfully created databases are immediately available for use by your web applications with proper security and performance optimizations. The system supports MySQL, MariaDB, and PostgreSQL with automatic configuration and management.
</Check>