Skip to main content
Geni uses the DATABASE_URL environment variable to connect to your database. The format varies depending on the database type.

​
PostgreSQL

PostgreSQL supports multiple URL schemes: postgres://, postgresql://, or psql://

​
Format

postgres://[user[:password]@][host][:port][/database][?options]

​
Examples

DATABASE_URL="postgres://[email protected]:5432/app?sslmode=disable"

​
Common Options

  • sslmode - SSL mode (disable, require, verify-ca, verify-full)
  • connect_timeout - Connection timeout in seconds
  • application_name - Application name for connection tracking

​
MySQL

MySQL uses the mysql:// scheme.

​
Format

mysql://[user[:password]@][host][:port][/database][?options]

​
Examples

DATABASE_URL="mysql://root:password@localhost:3306/app"

​
Common Options

  • charset - Character set (utf8mb4 recommended)
  • parseTime - Parse DATE and DATETIME to time.Time
  • loc - Location for time.Time values
The default port for MySQL is 3306.

​
MariaDB

MariaDB uses the mariadb:// scheme and has a similar format to MySQL.

​
Format

mariadb://[user[:password]@][host][:port][/database][?options]

​
Examples

DATABASE_URL="mariadb://root:password@localhost:3307/app"
While MariaDB is MySQL-compatible, using the mariadb:// scheme ensures optimal compatibility with MariaDB-specific features.

​
SQLite

SQLite uses file-based databases with the sqlite:// or sqlite3:// scheme.

​
Format

sqlite://[path/to/database.sqlite]

​
Examples

DATABASE_URL="sqlite://./database.sqlite"
If the SQLite database file doesn’t exist, Geni will automatically create it when running migrations or using geni create.

​
Path Guidelines

  • Use ./ prefix for relative paths: sqlite://./data/app.db
  • Use / prefix for absolute paths: sqlite:///home/user/app.db
  • Geni creates parent directories automatically if they don’t exist

​
LibSQL

LibSQL (including Turso) uses HTTP/HTTPS protocols for remote databases.

​
Format

http://[host][:port]
https://[host][:port]
libsql://[host][:port]

​
Examples

DATABASE_URL="http://localhost:8080"

​
Authentication

LibSQL and Turso databases often require authentication. Set the DATABASE_TOKEN environment variable: 
DATABASE_URL="https://my-database.turso.io" \
DATABASE_TOKEN="eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..." \
geni up
Retrieve your Turso authentication token using:
turso db tokens create [database-name]
  • Local LibSQL servers typically use HTTP (http://localhost:8080)
  • Turso databases always use HTTPS (https://)
  • If DATABASE_TOKEN is not set, Geni attempts to connect without authentication

​
URL Encoding

Special characters in passwords must be URL-encoded:
CharacterEncoded
@%40
:%3A
/%2F
?%3F
#%23
&%26
=%3D
+%2B
(space)%20

​
Example

If your password is p@ssw0rd!, encode it as: 
DATABASE_URL="postgres://user:p%40ssw0rd!@localhost:5432/db"

​
Testing Database URLs

Here are the database URLs used in Geni’s integration tests: 
DATABASE_URL="postgres://postgres:mysecretpassword@localhost:6437/development?sslmode=disable"

​
Troubleshooting

​
Connection Failed

Ensure the database exists. Use geni create to create it (works for PostgreSQL, MySQL, and MariaDB):
DATABASE_URL="postgres://user:pass@localhost:5432/mydb" geni create
  • Verify username and password are correct
  • Check for special characters that need URL encoding
  • For LibSQL/Turso, ensure DATABASE_TOKEN is set correctly
  • Verify the host and port are correct
  • Check if the database server is running
  • Increase DATABASE_WAIT_TIMEOUT if the database is slow to start
DATABASE_WAIT_TIMEOUT="60" geni up
For local development, disable SSL:
DATABASE_URL="postgres://user@localhost:5432/db?sslmode=disable"
For production, use appropriate SSL mode:
  • sslmode=require - Require SSL
  • sslmode=verify-ca - Verify certificate authority
  • sslmode=verify-full - Verify certificate and hostname

​
Supported URL Schemes

Geni recognizes the following URL schemes for database detection:
DatabaseSupported Schemes
PostgreSQLpostgres://, postgresql://, psql://
MySQLmysql://
MariaDBmariadb://
SQLitesqlite://, sqlite3://
LibSQL/Tursohttp://, https://, libsql://
URL schemes are case-sensitive. Always use lowercase schemes (e.g., postgres://, not POSTGRES://).

Build docs developers (and LLMs) love

Get started for freeTalk to us