Recommended Free Tools
The supported path is to install Dokku’s official MariaDB plugin on the host, create a service, link that service to your Laravel app, and make Laravel read the connection URL that Dokku injects. The link stays on Dokku’s private Docker network; you do not need to expose MariaDB publicly for the app to use it.
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
How the connection works
Dokku runs the Laravel application and MariaDB as separate containers. The dokku-mariadb plugin creates and manages the database container. When you link a service to an app, Dokku adds a connection URL to the app environment and restarts the app by default.
As an Amazon Associate I earn from qualifying purchases.
A typical generated value has this shape:
mysql://<user>:<password>@dokku-mariadb-appdb:3306/appdbThe hostname, such as dokku-mariadb-appdb, is intended for container-to-container traffic on Dokku’s internal Docker network. It is not a public DNS name. Laravel can use the URL directly when its database configuration is set up to parse a URL, or you can provide the individual host, port, database, username and password variables explicitly.
What you need before starting
- A Dokku host with administrative access and an existing Laravel app deployed under a known Dokku app name, such as
my-laravel-app. - Permission to run
sudoon the Dokku host. - A Laravel application using the MySQL-compatible database driver. Laravel’s current database documentation lists MariaDB 10.3 and newer as supported; verify the framework and PHP versions in your own application before selecting a production image.
- A plan for persistent storage, backups and restoration. A working connection is not, by itself, a production backup strategy.
The plugin repository documents Dokku 0.19.x or newer and Docker 1.8.x or newer as requirements. Those are documented minimums, not a recommendation to run obsolete platform versions; keep the host on versions supported by your operating system and Dokku release.
#1 Best Overall
1. Install the official MariaDB plugin
Run the installation on the Dokku host, not inside the Laravel container:
sudo dokku plugin:install https://github.com/dokku/dokku-mariadb.git --name mariadbThe plugin name in the command is important because later commands use the mariadb: namespace. If installation fails, check that the host can reach the repository, that the Dokku command is available to sudo, and that the Dokku and Docker versions meet the plugin’s documented minimums.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →The plugin documentation currently reports MariaDB 12.2.2 as its default image version (accessed October 15, 2026). Treat that as a value to review, not an automatic production recommendation. Check application compatibility, extensions and migration behavior before committing to the image used by a live service.
2. Create a MariaDB service
Create the service before attempting to link it:
dokku mariadb:create appdbappdb is the service name. Choose a stable, descriptive name because it appears in the generated hostname and in operational commands. Renaming a service later is more disruptive than choosing a durable name now.
Creating the service provisions the database container and its credentials. It does not connect any application to that database. The next command performs that association.
3. Link MariaDB to the Laravel app
Link the service and app by using their Dokku names:
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstalldokku mariadb:link appdb my-laravel-appLinking supplies the app with an internal connection URL in DATABASE_URL and normally restarts the app. The URL includes the service credentials, the internal hostname, port 3306 and the database name. Because those credentials are sensitive, do not paste the value into source control, tickets or public logs.
Rank #2
Dokku’s general deployment model treats a linked backing service as the source of connection environment variables. If your app already has a manually configured DATABASE_URL, determine which value is active after linking and remove conflicting configuration rather than guessing which one Laravel will use.
4. Make Laravel read the variable Dokku provides
Open the deployed project’s config/database.php and identify how the MySQL connection is built. Laravel supports URL-based connection configuration when a URL or DB_URL value is present, but the exact environment variable your application reads depends on that file. A link alone cannot fix a configuration that ignores DATABASE_URL.
URL-based configuration
A connection definition can be arranged so Laravel receives Dokku’s URL:
'mysql' => [
'driver' => 'mysql',
'url' => env('DATABASE_URL'),
'host' => env('DB_HOST', '127.0.0.1'),
'port' => env('DB_PORT', '3306'),
'database' => env('DB_DATABASE', 'forge'),
'username' => env('DB_USERNAME', 'forge'),
'password' => env('DB_PASSWORD', ''),
'unix_socket' => env('DB_SOCKET', ''),
'charset' => 'utf8mb4',
'collation' => 'utf8mb4_unicode_ci',
'prefix' => '',
'prefix_indexes' => true,
'strict' => true,
'engine' => null,
],The important part is not copying this entire array blindly; it is confirming that the active connection has a url entry that reads DATABASE_URL. Preserve the charset, collation, TLS and other settings required by your application.
Separate-variable configuration
Some applications intentionally use individual variables and never parse a URL. In that case, configure the connection to read DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME and DB_PASSWORD, then set those values from the credentials and host supplied by the MariaDB service. Do not set DB_HOST to localhost: inside the Laravel container, that points back to the application container, not the MariaDB container.
If you change configuration in a release that uses cached Laravel configuration, rebuild or clear the cache as part of that deployment so the process does not continue using old environment values. Also ensure the application’s DB_CONNECTION selects the connection you edited.
URL and credential edge cases
Connection URLs contain reserved characters. Let Laravel’s URL parser handle the generated value instead of copying credentials into an unescaped hand-written URL. If you must construct a URL yourself, percent-encode reserved characters in the username or password and test the resulting connection.
The plugin documents MARIADB_DATABASE_SCHEME for applications that require a nonstandard URL scheme. Change the scheme only after unlinking the service, then link it again with the desired setting; changing it while the existing link remains in place can leave the app with an old URL.
5. Deploy the application and run migrations
Deploy or redeploy the Laravel release after linking so the running container receives the service environment. Then run migrations from the app container:
dokku run my-laravel-app php artisan migrate --force--force is appropriate for a non-interactive production command, but review every migration and take a recoverable backup before applying destructive schema changes. Run the command only after the MariaDB container is healthy and the app can resolve its internal hostname.
Dokku’s deployment guidance also requires a web process to honor the PORT environment variable. A database connection can be correct while the release still fails health checks if the Laravel web server listens on a hard-coded port instead of the port Dokku assigns.
For a first deployment, use a staged release or maintenance window. Confirm that migrations finish, the application can read and write a harmless record, queues and scheduled tasks use the same connection, and the web process remains reachable after the link-induced restart.
6. Verify the service and application separately
Inspect MariaDB through Dokku
dokku mariadb:info appdbUse the service information output to confirm that the container is present, identify its connection details and check the DSN generated for the link. The hostname should be the internal service hostname, not a public IP address.
Read database startup and authentication logs
dokku mariadb:logs appdbLook for initialization errors, permission failures, authentication rejection, storage problems and repeated restarts. A healthy app container cannot connect to a database that is still failing its own startup checks.
Rank #4
Check Laravel’s effective configuration
If DATABASE_URL exists but Laravel reports that no connection is configured, inspect the deployed application’s environment and Laravel logs. Confirm all of the following:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- The selected
DB_CONNECTIONpoints to the connection definition you edited. - The definition reads
DATABASE_URL, or the separateDB_*variables have been set deliberately. - Cached configuration was rebuilt after the environment changed.
- The generated hostname is used instead of
localhostor127.0.0.1. - The database name, credentials and port match the linked service.
Common failures and the correct fix
Laravel says the database connection is missing
This usually means the framework is not reading the variable Dokku supplied. Compare config/database.php with the linked environment, and add the URL mapping or explicit variables required by that configuration. Then rebuild configuration cache and redeploy.
Connection refused or host not found
Check that the service exists, is running and is linked to the exact Dokku app name. Use dokku mariadb:info appdb and dokku mariadb:logs appdb. A typo in the service name, an unhealthy container or an app deployed before the link was created can all produce this symptom.
Access denied for the generated user
Do not substitute credentials from a different service or an old environment file. Recheck the active DSN in the service information and the value consumed by Laravel. If credentials were changed manually, update the app configuration through Dokku’s environment management and redeploy rather than editing files inside a running container.
The app connects to the wrong database
Look for a stale DATABASE_URL, cached Laravel configuration, or a second connection definition selected by DB_CONNECTION. Remove ambiguity before running migrations; otherwise a successful migration may modify an unintended database.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →The link works but the web release is unhealthy
Separate database diagnosis from process diagnosis. Confirm the migration command works first, then verify that the Laravel web process binds to Dokku’s PORT value. A port mismatch is independent of MariaDB authentication.
Keep MariaDB private unless an external client truly needs it
The generated service hostname is designed for internal Docker connectivity. Do not run mariadb:expose merely to let the Laravel app connect; exposing the service is a separate operation that makes a public-interface connection possible. Public exposure increases the attack surface and creates firewall, TLS, credential-rotation and access-control work that the private link avoids.
Use exposure only for a specific requirement such as an approved external reporting tool or migration client. Restrict the source addresses, require encrypted transport where appropriate, rotate credentials and document how the external client is removed. Normal Laravel traffic should remain on Dokku’s private network.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Multiple MariaDB services and changing the primary connection
A single app can receive more than one linked service. The first or primary link supplies DATABASE_URL; an additional linked service can receive an alias variable shaped like DOKKU_DATABASE_<ALIAS>_URL. Your Laravel configuration must explicitly select the variable that corresponds to the intended workload, such as a reporting or queue database.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsThe plugin’s mariadb:promote operation can make another service the primary source for DATABASE_URL. Treat promotion as a configuration change: verify the target service, confirm the schema and credentials, redeploy if needed, and run a read/write smoke test before sending production traffic to it.
Backups, export and restore operations
The plugin provides mariadb:backup, mariadb:export and mariadb:import commands. Establish a schedule, store backup output outside the database container and test restoration on a separate service before calling the deployment production-ready.
A practical runbook should identify:
- Which service name is backed up and where encrypted copies are stored.
- How often backups run and how long they are retained.
- Who can execute an import and who approves a production restore.
- How application writes are paused or coordinated during a restore.
- How the restored schema and row counts are validated before traffic is switched.
Backups protect data only when a restore has been rehearsed. Record the MariaDB image version, Laravel release and migration state used during each test so incompatibilities are visible before an incident.
Linked Dokku service versus external managed MariaDB
A linked service is usually the simplest option when the application and database belong on the same Dokku host. An external managed database can be preferable when you need provider-operated backups, multi-zone availability or a database lifecycle independent of the application host. The trade-off is not just a different hostname; it changes network design and operational ownership.
Free tools Windows power users keep installed
One-click scans. No signup required.
| Decision factor | MariaDB service linked in Dokku | External managed MariaDB |
|---|---|---|
| Network location and latency | Same Dokku Docker environment, with an internal hostname and normally low local network latency. | Traffic crosses the host or public/private provider network; latency and firewall rules depend on the selected service. |
| Backups and upgrades | You operate the plugin’s backup, export, import and image-upgrade process. | The provider may operate backups and upgrades, but exact schedules, retention and maintenance guarantees must be verified in its contract. |
| Recovery controls | Dokku commands give you direct export and import control; you are responsible for storage and restore testing. | Recovery tools depend on the provider, with possible snapshot or point-in-time features that are not established by Dokku’s documentation. |
| Cost | No price is established by the Dokku plugin documentation; host storage, compute and operations remain your responsibility. | Pricing varies by provider, region, storage, traffic and availability tier; no universal figure applies. |
| Version pinning | You can review and manage the plugin image used on your host, including checking the currently reported default of MariaDB 12.2.2. | Supported versions and upgrade timing are controlled by the provider’s offering. |
| Operational responsibility | You handle host security, capacity, monitoring, backups, upgrades and database incidents. | The provider handles some infrastructure tasks, while you still own schema changes, credentials, network policy and application compatibility. |
Whichever model you choose, Laravel’s configuration must point to the actual endpoint and credentials in use. Do not leave both a stale Dokku URL and an external URL configured without a deliberate selection rule.
Production checklist
- Install the official plugin on the Dokku host and confirm platform prerequisites.
- Create the service with a stable name before linking it.
- Link the service to the exact Laravel app name and protect the generated credentials.
- Verify that
config/database.phpreadsDATABASE_URLor that explicitDB_*variables are configured. - Redeploy, rebuild cached Laravel configuration when necessary and run migrations from the app container.
- Confirm the web process honors Dokku’s
PORTvariable. - Inspect the service with
dokku mariadb:infoand review failures withdokku mariadb:logs. - Keep MariaDB unexposed to the public interface unless an approved external client requires access.
- Schedule backups, exports and restore tests before relying on the service for production data.
- Document the MariaDB image version, migration procedure, recovery owner and rollback plan.
Bottom line
Create the MariaDB service first, link it with dokku mariadb:link, and then verify that Laravel’s active database definition consumes the resulting DATABASE_URL. Run migrations inside the app container, keep the database on Dokku’s private network, and treat inspection, logs and tested backup/restore procedures as part of the connection—not as optional follow-up work.
For the plugin’s command reference and current image information, see the official dokku-mariadb repository.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
