# Database instances

> Provision, register, and manage MariaDB, MySQL, and PostgreSQL instances — configuration, lifecycle, credentials, logs, and connecting external applications.

Source: https://fleetdock.dev/docs/database-instances


An **instance** is a database server process that Fleetdock manages. Fleetdock supports
**MariaDB, MySQL, and PostgreSQL** instances. This page covers provisioning new instances,
the instance lifecycle, and connecting to them.

## Managed vs external instances [#managed-vs-external-instances]

* **Managed** instances run on your nodes. They are either **provisioned** by Fleetdock (a
  database Docker container it launches) or **registered** (an existing database on the
  node). Operations run through that node's agent against `127.0.0.1`.
* **External** instances are databases you already host elsewhere. The control plane
  connects to them directly and can **import** their existing databases.

## Provisioning a database instance [#provisioning-a-database-instance]

Open **Servers → your server → Add instance → Provision new**. Fleetdock launches a database
container on the node for the engine you choose — MariaDB, MySQL, or PostgreSQL — with a
named data volume and a published port.

### Configuration fields [#configuration-fields]

* **Engine** — MariaDB, MySQL, or PostgreSQL.
* **Version** — the image version to run (the engine name doubles as the container image).
* **Port assignment** — the port published on the server for client access (defaults to the
  engine's standard port: `3306` for MariaDB/MySQL, `5432` for PostgreSQL).
* **Storage** — a named Docker data volume backing the instance.
* **Credentials** — a generated superuser password stored encrypted; you can create
  additional users and grants afterward.
* **Resource limits** — constrain the container's resource usage where supported.

<Callout type="info">
  Provisioning requires Docker on the node. The agent installer installs Docker
  automatically. All three engines — MariaDB, MySQL, and PostgreSQL — can be provisioned,
  registered, or connected as external instances.
</Callout>

## Registering an existing database [#registering-an-existing-database]

Choose **Add instance → Register** (managed) to point Fleetdock at a database already
running on the node, or **Add instance → External** to connect to a database hosted
elsewhere. Use **Import DBs** to pull existing databases into Fleetdock's inventory.

## Status lifecycle [#status-lifecycle]

A provisioned instance moves through states as you operate it. From its detail page you can:

* **Start / Stop / Restart** the underlying container.
* **Inspect** its info, databases, and database users with their grants.
* **Delete** the instance.

## Restarting, stopping, and deleting [#restarting-stopping-and-deleting]

Start, stop, and restart act on the provisioned container. Deleting removes the container
and, if you confirm, its data volume.

<Callout type="error">
  Deleting a provisioned instance removes its container. If you confirm removal of the data
  volume, the databases on it are destroyed permanently. Back up first.
</Callout>

## Inspecting logs [#inspecting-logs]

Container-level logs are available on the node with standard Docker tooling:

```bash
docker logs <container-name>
```

Operation-level history (create, drop, backup, restore, connection test) is tracked on the
**Operations** page for every instance.

## Connecting from external applications [#connecting-from-external-applications]

How you connect depends on where your application runs.

### Private network (recommended for internal apps) [#private-network-recommended-for-internal-apps]

Provisioned instances publish a port on the server. Connect with the client for your engine
using the server's internal address and the published port:

<Tabs items="[&#x22;MariaDB / MySQL&#x22;, &#x22;PostgreSQL&#x22;]">
  <Tab value="MariaDB / MySQL">
    ```bash
    mariadb -h <server-address> -P <published-port> -u <user> -p
    ```
  </Tab>

  <Tab value="PostgreSQL">
    ```bash
    psql "postgresql://<user>@<server-address>:<published-port>/<database>"
    ```
  </Tab>
</Tabs>

<Callout type="warn">
  The instance port must be reachable from wherever your application connects — and, for
  live administration, from the control plane. Keep it on a private network where possible.
  See [Networking](/docs/networking).
</Callout>

### Public access via Fleetdock Gateway [#public-access-via-fleetdock-gateway]

For applications **outside** your private network, enable **public access** on the database
page (**Connectivity**). Fleetdock assigns a stable gateway endpoint
(`gateway.example.com:<port>`) and routes traffic through HAProxy with CIDR enforcement.

<Callout type="info">
  Public access is **disabled by default**. Do not expose database ports directly to the
  internet as your primary pattern — use the gateway with application credentials and CIDR
  allowlists. See [External database access](/docs/external-access).
</Callout>

Use **application credentials** (not instance root credentials) for external apps. The
connection URL is shown once on create or rotate.

## Databases on an instance [#databases-on-an-instance]

Within an instance you create logical **databases**. When admin credentials exist, creating
a database physically creates it via an operation; otherwise it is registered as
metadata-only. Databases can be locked, unlocked, and soft-deleted with a seven-day
recovery window.

<Screenshot name="databases" />