Database Configuration - FlatRun Docs

FlatRun can manage shared database servers that multiple deployments can use. This is more efficient than running a separate database container for each application.

Supported Databases

Database	Default Port	Config Type
MySQL	3306	`mysql`
MariaDB	3306	`mariadb`
PostgreSQL	5432	`postgres`

Configuration

Configure the database in your agent config:

infrastructure:
  default_database_network: database

  database:
    enabled: true
    type: mysql
    container: flatrun-mysql
    host: ""
    port: 3306
    root_user: root
    root_password: ${MYSQL_ROOT_PASSWORD}

Option	Description
`enabled`	Enable database management
`type`	Database type: mysql, mariadb, postgres
`container`	Container name (for managed database)
`host`	Database host (for external database)
`port`	Database port
`root_user`	Admin username
`root_password`	Admin password

Managed vs External

Managed Database

FlatRun creates and manages the database container. Specify the container name:

infrastructure:
  database:
    enabled: true
    type: mysql
    container: flatrun-mysql
    root_password: supersecret

External Database

Use an existing database server. Specify the host instead:

infrastructure:
  database:
    enabled: true
    type: postgres
    host: db.example.com
    port: 5432
    root_user: admin
    root_password: ${DB_PASSWORD}

Database Network

For deployments to connect to the shared database, they must be on the same Docker network:

# In your docker-compose.yml
services:
  app:
    image: myapp
    environment:
      DB_HOST: flatrun-mysql
      DB_NAME: myapp
    networks:
      - default
      - database

networks:
  database:
    external: true

Database Management

FlatRun provides a complete database management interface:

List Databases

curl -X POST "http://localhost:8090/api/databases/list" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Create Database

curl -X POST "http://localhost:8090/api/databases/create" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "myapp_production"
  }'

Create User

curl -X POST "http://localhost:8090/api/databases/users/create" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "myapp_user",
    "password": "secure_password",
    "host": "%"
  }'

Grant Privileges

curl -X POST "http://localhost:8090/api/databases/privileges/grant" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "myapp_production",
    "username": "myapp_user",
    "privileges": ["ALL"]
  }'

Execute Query

curl -X POST "http://localhost:8090/api/databases/query" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "myapp_production",
    "query": "SELECT * FROM users LIMIT 10"
  }'

Using with Templates

When deploying from templates that require databases (WordPress, Laravel, etc.), FlatRun can automatically:

Create a database for the deployment
Create a user with appropriate privileges
Configure the application with database credentials

Template variables for database configuration:

Variable	Description
`${DB_HOST}`	Database hostname
`${DB_PORT}`	Database port
`${DB_NAME}`	Database name
`${DB_USER}`	Database username
`${DB_PASSWORD}`	Database password

Database Manager UI

The FlatRun UI includes a full-featured database manager:

Browse Databases — View all databases on the server
Table Explorer — Browse tables and view data
Query Editor — Execute SQL queries with syntax highlighting
User Management — Create and manage database users
Backup/Export — Export data (coming soon)

Connection Testing

Test your database connection:

curl -X POST "http://localhost:8090/api/databases/test" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Security Best Practices

Strong Passwords — Use long, random passwords for database users
Least Privilege — Grant only necessary permissions to application users
Network Isolation — Only connect containers that need database access
Regular Backups — Set up automated database backups
Don't Expose Ports — Keep database ports internal to Docker networks

Security Warning: Never expose database ports (3306, 5432) to the internet. Access should only be through the Docker network or secure tunnels.

PostgreSQL Specifics

PostgreSQL has some differences in user and privilege management:

infrastructure:
  database:
    enabled: true
    type: postgres
    container: flatrun-postgres
    root_user: postgres
    root_password: ${POSTGRES_PASSWORD}

Creating databases with PostgreSQL:

# Create a database with owner
curl -X POST "http://localhost:8090/api/databases/create" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "myapp",
    "owner": "myapp_user"
  }'