Database Configuration

SoliLang uses SoliDB as its database backend. Configure your database connection using environment variables.

Environment Variables

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

Required Variables

Variable	Description	Default
`SOLIDB_HOST`	SoliDB server URL	`http://localhost:6745`
`SOLIDB_DATABASE`	Database name	`default`

Optional Variables

Variable	Description	Default
`SOLIDB_USERNAME`	Authentication username	None
`SOLIDB_PASSWORD`	Authentication password	None
`SOLIDB_API_KEY`	API key for SoliDB authentication	None

.env File

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

.env

# Database Configuration
SOLIDB_HOST=http://localhost:6745
SOLIDB_DATABASE=default
SOLIDB_USERNAME=admin
SOLIDB_PASSWORD=admin
SOLIDB_API_KEY=your-api-key-here

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

Multiple Environments

Create environment-specific .env files for different environments:

.env

Development (default)

.env.test

Test environment

.env.production

Production environment

Development

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

Test

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

Production

# .env.production
SOLIDB_HOST=https://db.example.com
SOLIDB_DATABASE=myapp_production
SOLIDB_USERNAME=prod_user
SOLIDB_PASSWORD=secure_password_here
SOLIDB_API_KEY=your-production-api-key

Setting APP_ENV

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

Loads the base .env file first
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

.env — base configuration
.env.{APP_ENV} — environment overrides

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 < Model end

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

Raw Queries

For everyday CRUD inside a server, use the Model ORM — it reuses the worker's connection and adds validations, callbacks, and relations. Drop down to a raw query for SDBQL features the ORM doesn't cover, or in scripts and one-offs. Both forms below parameterize bind values — nothing is concatenated, so queries stay safe against injection.

Using a Solidb instance

Construct a client with Solidb(host, database), optionally auth it, then call query with @param placeholders and a hash of bind values:

db = Solidb(env("SOLIDB_HOST"), env("SOLIDB_DATABASE"))
db.auth(env("SOLIDB_USERNAME"), env("SOLIDB_PASSWORD"))

# Read with named parameters
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]"
})

# Update
db.query("UPDATE @key WITH { name: @name } IN users", {
  "key": user_id,
  "name": "Alice Smith"
})

# Delete
db.query("REMOVE @key IN users", { "key": user_id })

Inside migrations, a pre-wired db helper is injected for you — you don't construct a Solidb instance manually.

Using @sdbql{} Query Block

The @sdbql{} syntax provides a more readable way to write database queries with interpolation:

# Simple query with interpolation
users = @sdbql{
  FOR u IN users
  FILTER u.age >= #{age}
  RETURN u
}

# Query with multiple interpolations
results = @sdbql{
  FOR u IN users
  FILTER u.age >= #{min_age} AND u.city == #{city}
  SORT u.name ASC
  LIMIT #{limit}
  RETURN u
}

# Insert with interpolation
@sdbql{
  INSERT {
    name: #{name},
    email: #{email},
    created_at: NOW
  } INTO users
}

# Update with interpolation
@sdbql{
  UPDATE #{user_id} IN users
  SET {
    last_login: NOW
  }
}

# Delete with interpolation
@sdbql{
  REMOVE #{user_id} IN users
};

Note: The @sdbql{} block supports:

String interpolation using #{expression} - expressions are evaluated at runtime
Multi-line queries for better readability
All SDBQL operations: FOR, FILTER, SORT, LIMIT, RETURN, INSERT, UPDATE, REMOVE

@sdql{} is accepted as a legacy alias for @sdbql{}. New code should use @sdbql{} — it matches the language name (SDBQL).

When to Use Each Syntax

Approach	Use Case
`Model.where(...)`	Standard CRUD inside a server — your first choice
`Solidb(...).query()` with `@param`	Scripts, migrations, or when bind values are already a hash
`@sdbql{}` with `#{expr}`	Inline interpolation, readable multi-line queries

Security Best Practices

Important Security Rules

Never commit .env files - Add .env* to .gitignore
Use strong passwords - Especially in production
Use HTTPS in production - Set SOLIDB_HOST=https://...
Rotate credentials - Change passwords periodically
Limit network access - Use firewalls to restrict database access

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=
SOLIDB_API_KEY=

Troubleshooting

Connection Refused

Error: Failed to connect: Connection refused

Solution: Make sure SoliDB is running:

solidb

Authentication Failed

Error: Authentication failed

Solution: Check your SOLIDB_USERNAME and SOLIDB_PASSWORD in .env.

Database Not Found

Error: Database 'mydb' not found

Solution: The database is created automatically on first use. Check your SOLIDB_DATABASE value.

Environment Variables Not Loading

Solution: Ensure .env is in your project root (same directory as main.sl).

Database Configuration

Environment Variables

Required Variables

Optional Variables

.env File

Multiple Environments

.env

.env.test

.env.production

Development

Test

Production

Setting APP_ENV

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

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

File Loading Order

Starting SoliDB

Verifying Connection

Using Models

Raw Queries

Using a Solidb instance

Using @sdbql{} Query Block

When to Use Each Syntax

Security Best Practices

Important Security Rules

Example .gitignore

Example .env.example

Troubleshooting

Connection Refused

Authentication Failed

Database Not Found

Environment Variables Not Loading

Next Steps

Models →

Migrations →

Testing →