# How to Configure the Snipe-IT Database Connection: A Complete Guide

> Configure your Snipe-IT database connection easily. Follow our guide to set environment variables and initialize the schema for a smooth asset management setup.

- Repository: [Grokability, Inc./snipe-it](https://github.com/grokability/snipe-it)
- Tags: how-to-guide
- Published: 2026-07-31

---

**To configure the Snipe-IT database connection, copy `.env.example` to `.env`, set the `DB_*` environment variables to match your database server, and run `php artisan migrate` to initialize the schema.**

Snipe-IT is a Laravel-based open-source asset management platform maintained by `grokability/snipe-it`. Since it follows Laravel conventions, all database connection settings are controlled through environment variables defined in the project root `.env` file.

## Prerequisites

Before editing configuration files, ensure you have created an empty database on your server with appropriate credentials. Snipe-IT supports **MySQL/MariaDB**, **PostgreSQL**, **SQLite**, and **SQL Server**, though MySQL is the most common production choice.

## Step 1: Create the Environment File

Snipe-IT stores sensitive configuration outside of version control using environment variables. Create your local configuration by copying the example template:

```bash
cp .env.example .env

```

This creates a new `.env` file containing all configurable variables, including the database connection block.

## Step 2: Configure Database Variables in `.env`

Open `.env` in your editor and locate the database section. The application reads these values at runtime through [`config/database.php`](https://github.com/grokability/snipe-it/blob/main/config/database.php), where lines 90–100 define the MySQL connection array and lines 118–122 define the PostgreSQL options.

Set these required variables:

- **`DB_CONNECTION`** – The database driver (`mysql`, `pgsql`, `sqlite`, or `sqlsrv`)
- **`DB_HOST`** – Hostname or IP address of your database server (e.g., `127.0.0.1` or `db.company.com`)
- **`DB_PORT`** – Server port (`3306` for MySQL, `5432` for PostgreSQL)
- **`DB_DATABASE`** – Name of the database you created for Snipe-IT
- **`DB_USERNAME`** – Database user with privileges on the named database
- **`DB_PASSWORD`** – Password for the specified user
- **`DB_PREFIX`** – Optional table prefix (e.g., `snipe_`) for multi-tenant installations

Optional variables include `DB_CHARSET` and `DB_COLLATION` (typically `utf8mb4` and `utf8mb4_unicode_ci` for MySQL), `DB_SOCKET` for Unix socket connections, and SSL configuration variables (`DB_SSL`, `DB_SSL_CA_PATH`, `DB_SSL_CERT_PATH`, `DB_SSL_KEY_PATH`) for encrypted connections.

## Step 3: Apply the Configuration

After saving the `.env` file, execute these commands from the project root to cache the configuration and build the database schema:

```bash
php artisan config:cache
php artisan key:generate
php artisan migrate

```

The `config:cache` command optimizes lookup speed by compiling the environment variables into a PHP cache. The `migrate` command creates the required tables, asset logs, and initial schema based on the connection details you provided.

## Database Configuration Examples

### MySQL/MariaDB Setup

For a standard MySQL server running locally:

```dotenv
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=snipe_it
DB_USERNAME=snipe_user
DB_PASSWORD=superSecretPassword
DB_CHARSET=utf8mb4
DB_COLLATION=utf8mb4_unicode_ci
DB_PREFIX=null
DB_SOCKET=

```

### PostgreSQL Setup

For a PostgreSQL instance with SSL disabled:

```dotenv
DB_CONNECTION=pgsql
DB_HOST=pg.example.com
DB_PORT=5432
DB_DATABASE=snipe_it
DB_USERNAME=snipe_user
DB_PASSWORD=superSecretPassword
DB_PREFIX=null

```

## Advanced Connection Options

**Table Prefixing:** Set `DB_PREFIX=snipe_` to prepend all table names. This allows multiple Snipe-IT instances to share one database server without naming conflicts.

**SSL/TLS Encryption:** For databases requiring encrypted connections (common in managed cloud services), set `DB_SSL=true` and provide the absolute paths to your certificate authority, client certificate, and key files using the `DB_SSL_*_PATH` variables.

**Unix Sockets:** When running MySQL on the same server and preferring socket connections over TCP, specify the socket path in `DB_SOCKET` (e.g., `/var/run/mysqld/mysqld.sock`) and leave `DB_HOST` empty.

**Runtime Validation:** The system validates the `DB_CONNECTION` value in several places, including [`app/Console/Commands/RestoreFromBackup.php`](https://github.com/grokability/snipe-it/blob/main/app/Console/Commands/RestoreFromBackup.php), which explicitly checks that the connection is set to `mysql` before allowing database restores.

## Troubleshooting Common Connection Issues

If you encounter a `SQLSTATE[HY000] [2002] Connection refused` error, verify that `DB_HOST` and `DB_PORT` match your database server's actual listening address. Many Docker or cloud installations use specific service names rather than `localhost`.

For permission denied errors, confirm that the `DB_USERNAME` account has been granted full privileges on the `DB_DATABASE` schema, including CREATE, ALTER, and INDEX rights for running migrations.

When using SSL connections, ensure the certificate files specified in `DB_SSL_CA_PATH` and related variables are readable by the web server process and are in PEM format.

## Summary

- Snipe-IT uses Laravel's database configuration system driven by environment variables in `.env`.
- Copy `.env.example` to `.env` and configure `DB_CONNECTION`, `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, and `DB_PASSWORD`.
- Run `php artisan migrate` after setting variables to create the required tables.
- Advanced options include table prefixes (`DB_PREFIX`), SSL encryption (`DB_SSL*`), and Unix socket connections (`DB_SOCKET`).
- Configuration is parsed in [`config/database.php`](https://github.com/grokability/snipe-it/blob/main/config/database.php) with driver-specific settings defined beginning at lines 90 (MySQL) and 118 (PostgreSQL).

## Frequently Asked Questions

### What database systems does Snipe-IT support?

Snipe-IT supports **MySQL/MariaDB**, **PostgreSQL**, **SQLite**, and **SQL Server** through Laravel's database abstraction layer. While MySQL is the most common choice in production, PostgreSQL is fully supported with configuration options defined in [`config/database.php`](https://github.com/grokability/snipe-it/blob/main/config/database.php) lines 118–122.

### Where does Snipe-IT read database settings from?

The application reads database configuration from environment variables defined in the `.env` file in the project root. These values are loaded into the Laravel config system via [`config/database.php`](https://github.com/grokability/snipe-it/blob/main/config/database.php), which maps the `DB_*` variables to connection arrays used by Eloquent and the query builder.

### How do I change the database connection after installation?

Edit the `.env` file to update the `DB_HOST`, `DB_DATABASE`, or other relevant variables, then clear the configuration cache by running `php artisan config:cache` to force the application to reload the new settings. If migrating to an entirely new database server, you must also run `php artisan migrate` to recreate the schema.

### Why do I need to run `php artisan config:cache`?

This command compiles the `.env` variables and configuration files into a single PHP cache file for performance optimization. While not strictly required for the connection to work, caching ensures that database credentials are loaded efficiently on every request rather than parsing the `.env` file repeatedly. Always run this after modifying database configuration in production environments.