Database Configuration

Environment Variables

Database configuration is done through environment variables, typically stored in a .env file in your project root.

Required Variables

Optional Variables

.env File

When you create a new project with soli new myapp, a .env file is automatically generated:

# Database Configuration
SOLIDB_HOST=http://localhost:6745
SOLIDB_DATABASE=default
SOLIDB_USERNAME=admin
SOLIDB_PASSWORD=admin

# Application Settings
# APP_ENV=development
# APP_SECRET=your-secret-key-here

Multiple Environments

Create environment-specific .env files for different environments:

# .env
SOLIDB_HOST=http://localhost:6745
SOLIDB_DATABASE=myapp_development

# .env.test
SOLIDB_HOST=http://localhost:6745
SOLIDB_DATABASE=myapp_test

# .env.production
SOLIDB_HOST=https://db.example.com
SOLIDB_DATABASE=myapp_production
SOLIDB_USERNAME=prod_user
SOLIDB_PASSWORD=secure_password_here

Setting APP_ENV

The APP_ENV environment variable controls which environment-specific .env file is loaded. When set, the system automatically:

1. Loads the base .env file first
2. Then loads .env.{APP_ENV} to override values

This matches the convention used by Rails, Node.js, and other frameworks.

Option 1: Shell Environment (Recommended for CI/Production)

Set APP_ENV when running commands:

# Run migrations in production
APP_ENV=production soli db:migrate

# Start server in test mode
APP_ENV=test soli serve

# Run with development settings (default)
soli serve

Option 2: In .env File (For Local Development)

Set APP_ENV in your base .env file:

# .env
APP_ENV=development
SOLIDB_DATABASE=myapp_development

File Loading Order

Environment-specific values override base values. For example:

# .env
SOLIDB_DATABASE=myapp_development

# .env.production
SOLIDB_DATABASE=myapp_production

Running APP_ENV=production soli serve will use myapp_production as the database.

Starting SoliDB

Before running your application, start the SoliDB server:

# Start SoliDB (default port 6745)
solidb

# Or specify a custom port
solidb --port 6745

# With data directory
solidb --data ./data

Verifying Connection

Test your database connection by running migrations:

cd myapp
soli db:migrate

If successful, you'll see:

Running migrations for database: myapp_development
All migrations are up to date.

Using Models

Once configured, Models automatically connect to the database:

class User extends Model { }

// These all use the configured database
let users = User.all();
let user = User.create({ "name": "Alice" });
let found = User.find(user["id"]);

Raw Queries

For raw database queries, use SDBQL (SoliDB Query Language):

// SDBQL query with bind parameters
let results = db.query("FOR doc IN users FILTER doc.age >= @age RETURN doc", {
    "age": 18
});

// Insert
db.query("INSERT { name: @name, email: @email } INTO users", {
    "name": "Bob",
    "email": "[email protected]"
});

Security Best Practices

Example .gitignore

# Environment files (contain secrets)
.env
.env.*
!.env.example

Example .env.example

Create a template for other developers (safe to commit):

# .env.example (commit this file)
SOLIDB_HOST=http://localhost:6745
SOLIDB_DATABASE=myapp_development
SOLIDB_USERNAME=
SOLIDB_PASSWORD=

Troubleshooting

Next Steps