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

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:

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, 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:

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:

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:

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, 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 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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}