SuperTokens Core requires a database to store user data, sessions, and authentication information. This guide covers setup for all supported databases.
Supported Databases
- PostgreSQL 11+ (Recommended for production)
- MySQL 5.7+ / MariaDB 10.2+
- SQLite (Development only - not for production)
- MongoDB (via plugin)
PostgreSQL Setup
Installation
Ubuntu/Debian
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql
Docker
docker run -d \
--name postgres \
-e POSTGRES_PASSWORD=yourpassword \
-e POSTGRES_DB=supertokens \
-p 5432:5432 \
postgres:15
Database Creation
-- Connect to PostgreSQL
psql -U postgres
-- Create database
CREATE DATABASE supertokens;
-- Create user
CREATE USER supertokens_user WITH PASSWORD 'your_secure_password';
-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE supertokens TO supertokens_user;
-- For PostgreSQL 15+, also grant schema privileges
\c supertokens
GRANT ALL ON SCHEMA public TO supertokens_user;
Connection Configuration
In config.yaml:
postgresql_connection_uri: "postgresql://supertokens_user:your_secure_password@localhost:5432/supertokens"
Or via environment variable:
POSTGRESQL_CONNECTION_URI="postgresql://supertokens_user:your_secure_password@localhost:5432/supertokens"
postgresql://[user[:password]@][host][:port][/database][?param1=value1&...]
Examples:
# Basic connection
postgresql_connection_uri: "postgresql://user:pass@localhost:5432/supertokens"
# With SSL
postgresql_connection_uri: "postgresql://user:pass@host:5432/supertokens?sslmode=require"
# Cloud providers (AWS RDS)
postgresql_connection_uri: "postgresql://user:[email protected]:5432/supertokens?sslmode=require"
# Multiple hosts (failover)
postgresql_connection_uri: "postgresql://user:pass@host1:5432,host2:5432/supertokens"
PostgreSQL Optimization
For production workloads:
-- Tune PostgreSQL configuration
ALTER SYSTEM SET shared_buffers = '256MB';
ALTER SYSTEM SET effective_cache_size = '1GB';
ALTER SYSTEM SET maintenance_work_mem = '64MB';
ALTER SYSTEM SET checkpoint_completion_target = 0.9;
ALTER SYSTEM SET wal_buffers = '16MB';
ALTER SYSTEM SET default_statistics_target = 100;
ALTER SYSTEM SET random_page_cost = 1.1;
ALTER SYSTEM SET effective_io_concurrency = 200;
ALTER SYSTEM SET work_mem = '4MB';
ALTER SYSTEM SET min_wal_size = '1GB';
ALTER SYSTEM SET max_wal_size = '4GB';
-- Restart PostgreSQL to apply changes
MySQL Setup
Installation
Ubuntu/Debian
sudo apt update
sudo apt install mysql-server
sudo systemctl start mysql
sudo systemctl enable mysql
sudo mysql_secure_installation
Docker
docker run -d \
--name mysql \
-e MYSQL_ROOT_PASSWORD=rootpassword \
-e MYSQL_DATABASE=supertokens \
-e MYSQL_USER=supertokens_user \
-e MYSQL_PASSWORD=your_secure_password \
-p 3306:3306 \
mysql:8.0
Database Creation
-- Connect to MySQL
mysql -u root -p
-- Create database
CREATE DATABASE supertokens CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-- Create user
CREATE USER 'supertokens_user'@'%' IDENTIFIED BY 'your_secure_password';
-- Grant privileges
GRANT ALL PRIVILEGES ON supertokens.* TO 'supertokens_user'@'%';
FLUSH PRIVILEGES;
Connection Configuration
In config.yaml:
mysql_connection_uri: "mysql://supertokens_user:your_secure_password@localhost:3306/supertokens"
Or via environment variable:
MYSQL_CONNECTION_URI="mysql://supertokens_user:your_secure_password@localhost:3306/supertokens"
mysql://[user[:password]@][host][:port][/database][?param1=value1&...]
Examples:
# Basic connection
mysql_connection_uri: "mysql://user:pass@localhost:3306/supertokens"
# With SSL
mysql_connection_uri: "mysql://user:pass@host:3306/supertokens?useSSL=true"
# Cloud providers (AWS RDS)
mysql_connection_uri: "mysql://user:[email protected]:3306/supertokens?useSSL=true"
# Connection pooling settings
mysql_connection_uri: "mysql://user:pass@host:3306/supertokens?maxPoolSize=10"
MySQL Optimization
-- Optimize for SuperTokens workload
SET GLOBAL innodb_buffer_pool_size = 268435456; -- 256MB
SET GLOBAL max_connections = 200;
SET GLOBAL innodb_flush_log_at_trx_commit = 2;
SET GLOBAL innodb_log_file_size = 67108864; -- 64MB
MongoDB Setup
MongoDB support requires a separate plugin. Contact SuperTokens for enterprise MongoDB support.
Installation
# Install MongoDB
sudo apt install mongodb-org
sudo systemctl start mongod
sudo systemctl enable mongod
Connection Configuration
mongodb_connection_uri: "mongodb://username:password@localhost:27017/supertokens"
SQLite (Development Only)
SQLite is only suitable for development and testing. Do not use in production.
SQLite is automatically used when no database connection is specified:
# SQLite will be used by default
# No configuration needed
Database location: .started directory in installation folder
Connection Pool Configuration
SuperTokens manages database connections automatically. For high-traffic scenarios:
# Increase server thread pool
max_server_pool_size: 50
The database driver handles connection pooling internally.
Database Migrations
Automatic Migrations
SuperTokens automatically creates and migrates database schema on startup. No manual migration is needed.
Migration process:
- SuperTokens checks the current schema version
- Applies any pending migrations automatically
- Logs migration progress
Manual Migration Scripts
For controlled migrations in production:
# Located in the installation directory
ls migration_scripts/
Apply migrations manually:
-- PostgreSQL
\i migration_scripts/postgresql/001_initial_schema.sql
-- MySQL
source migration_scripts/mysql/001_initial_schema.sql
Schema Version Tracking
SuperTokens tracks schema versions in the st_schema_version table:
SELECT * FROM st_schema_version;
High Availability Setup
PostgreSQL HA
Option 1: PostgreSQL Streaming Replication
# Primary connection with replica failover
postgresql_connection_uri: "postgresql://user:pass@primary:5432,replica1:5432,replica2:5432/supertokens?target_session_attrs=read-write"
Option 2: PgBouncer Connection Pooling
postgresql_connection_uri: "postgresql://user:pass@pgbouncer:6432/supertokens"
Option 3: Cloud Managed Services
- AWS RDS PostgreSQL with Multi-AZ
- Google Cloud SQL
- Azure Database for PostgreSQL
MySQL HA
Option 1: MySQL Group Replication
mysql_connection_uri: "mysql://user:pass@node1:3306,node2:3306,node3:3306/supertokens"
Option 2: ProxySQL
mysql_connection_uri: "mysql://user:pass@proxysql:6033/supertokens"
Option 3: Cloud Managed Services
- AWS RDS MySQL with Multi-AZ
- Google Cloud SQL
- Azure Database for MySQL
Backup and Recovery
PostgreSQL Backup
Full database backup:
# Backup
pg_dump -U supertokens_user -h localhost supertokens > backup.sql
# Restore
psql -U supertokens_user -h localhost supertokens < backup.sql
Continuous archiving (PITR):
# Configure WAL archiving in postgresql.conf
archive_mode = on
archive_command = 'cp %p /path/to/archive/%f'
# Base backup
pg_basebackup -D /backup/base -F tar -z -P
MySQL Backup
Full database backup:
# Backup
mysqldump -u supertokens_user -p supertokens > backup.sql
# Restore
mysql -u supertokens_user -p supertokens < backup.sql
Binary log replication:
# Enable binary logging in my.cnf
log_bin = mysql-bin
server_id = 1
Cloud Database Providers
AWS RDS
# PostgreSQL
postgresql_connection_uri: "postgresql://admin:[email protected]:5432/supertokens?sslmode=require"
# MySQL
mysql_connection_uri: "mysql://admin:[email protected]:3306/supertokens?useSSL=true"
Google Cloud SQL
# Using Cloud SQL Proxy
postgresql_connection_uri: "postgresql://user:pass@localhost:5432/supertokens"
# Or direct connection
postgresql_connection_uri: "postgresql://user:pass@IP_ADDRESS:5432/supertokens"
Azure Database
# PostgreSQL
postgresql_connection_uri: "postgresql://user@servername:[email protected]:5432/supertokens?sslmode=require"
# MySQL
mysql_connection_uri: "mysql://user@servername:[email protected]:3306/supertokens?useSSL=true"
DigitalOcean Managed Databases
postgresql_connection_uri: "postgresql://user:[email protected]:25060/supertokens?sslmode=require"
Troubleshooting
Connection Issues
Test database connectivity:
# PostgreSQL
psql -U supertokens_user -h localhost -d supertokens
# MySQL
mysql -u supertokens_user -h localhost -p supertokens
Common errors:
- Connection refused: Check if database is running and firewall allows connections
- Authentication failed: Verify username and password
- Database does not exist: Create the database first
- SSL errors: Check SSL configuration and certificates
Check slow queries:
-- PostgreSQL
SELECT * FROM pg_stat_statements ORDER BY total_time DESC LIMIT 10;
-- MySQL
SELECT * FROM mysql.slow_log ORDER BY query_time DESC LIMIT 10;
Monitor connection count:
-- PostgreSQL
SELECT count(*) FROM pg_stat_activity;
-- MySQL
SHOW PROCESSLIST;
Migration Failures
If automatic migration fails:
- Check SuperTokens error logs
- Verify database user has sufficient privileges
- Ensure database is accessible
- Apply migrations manually from
migration_scripts/
Security Best Practices
Follow these security practices for production databases.
- Use strong passwords: Minimum 16 characters, mixed case, numbers, symbols
- Enable SSL/TLS: Always encrypt database connections
- Restrict network access: Use firewall rules to limit database access
- Regular backups: Automate daily backups with retention policy
- Principle of least privilege: Grant only necessary permissions
- Monitor access logs: Track database access and queries
- Keep databases updated: Apply security patches regularly
Next Steps