DataBridge DataBridge

Database Connection Setup

Complete guide to configuring MySQL, PostgreSQL, SQL Server, SQLite, and CockroachDB connections

Database Connection Setup

Learn how to properly configure your database connection for DataBridge.

Overview

DataBridge v0.2.9 supports 5 major databases. This guide covers:

  • ✅ MySQL - Fully tested
  • ✅ PostgreSQL - Fully tested
  • ✅ SQL Server - Fully tested
  • ✅ SQLite - File-based database
  • ✅ CockroachDB - Distributed SQL
  • Connection string formats for each database
  • Environment variable configuration
  • Docker setup examples
  • Troubleshooting connection issues

Connection String Formats

MySQL

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

Examples:

# Local
mysql://root:password@localhost:3306/mydb

# With SSL
mysql://root:password@localhost:3306/mydb?ssl=true

# Remote
mysql://user:pass@db.example.com:3306/production

PostgreSQL

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

Examples:

# Local
postgresql://postgres:password@localhost:5432/mydb

# With SSL
postgresql://postgres:password@localhost:5432/mydb?sslmode=require

# Remote (AWS RDS)
postgresql://dbuser:pass@mydb.abc123.us-east-1.rds.amazonaws.com:5432/production

SQL Server

sqlserver://[host]:[port];database=[database];user=[user];password=[password];[options]

Examples:

# Local with sa account
sqlserver://localhost:1433;database=mydb;user=sa;password=YourStrong@Passw0rd;encrypt=true;trustServerCertificate=true

# Azure SQL Database
sqlserver://myserver.database.windows.net:1433;database=mydb;user=admin@myserver;password=Pass123!;encrypt=true

# Named instance
sqlserver://localhost\SQLEXPRESS;database=mydb;user=sa;password=Pass123!;encrypt=true;trustServerCertificate=true

SQL Server Environment Variables:

For SQL Server, you also need these environment variables:

DB_SERVER=127.0.0.1
DB_PORT=1433
DB_NAME=mydb
DB_USER=sa
DB_PASSWORD=YourStrong@Passw0rd

Important: When running databridge init with SQL Server:

  1. Select “SQL Server” as the database provider
  2. Enter the full connection string (example above)
  3. After init completes, manually add the additional environment variables (DB_SERVER, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD) to your .env file
  4. These variables are required because the Prisma 7 SQL Server adapter needs them to create the connection pool

SQLite

file:[path]

Examples:

# Relative path
file:./dev.db

# Absolute path
file:/absolute/path/to/database.db

# In-memory
file::memory:

CockroachDB

postgresql://[user]@[host]:[port]/[database]?sslmode=[mode]

Examples:

# Local insecure
postgresql://root@localhost:26257/mydb?sslmode=disable

# With SSL
postgresql://user@host:26257/mydb?sslmode=require&sslrootcert=certs/ca.crt

# CockroachDB Cloud
postgresql://user:pass@free-tier.gcp-us-central1.cockroachlabs.cloud:26257/mydb?sslmode=verify-full

URL Encoding

Special characters in passwords must be URL-encoded:

CharacterEncoded
@%40
:%3A
/%2F
?%3F
#%23
&%26
%%25
!%21

Environment Variables

Using .env File

Create a .env file in your project root:

# .env
DATABASE_URL="mysql://root:password@localhost:3306/mydb"
API_PORT=3000
NODE_ENV=development

Important: Add .env to .gitignore:

echo ".env" >> .gitignore

Using .databridge.json

The .databridge.json file can reference environment variables:

{
  "version": "0.1.0",
  "database": {
    "url": "${DATABASE_URL}"
  },
  "api": {
    "port": "${API_PORT}",
    "cors": "*"
  }
}

DataBridge will automatically read from .env when using ${VARIABLE} syntax.

Docker Setup Examples

MySQL with Docker

1. Start MySQL container:

docker run -d \
  --name databridge-mysql \
  -e MYSQL_ROOT_PASSWORD=password \
  -e MYSQL_DATABASE=mydb \
  -p 3306:3306 \
  mysql:8.0

# Wait for MySQL to be ready (takes ~30 seconds)
docker logs databridge-mysql -f
# Press Ctrl+C when you see "ready for connections"

2. Connection string:

DATABASE_URL="mysql://root:password@127.0.0.1:3306/mydb"

PostgreSQL with Docker

1. Start PostgreSQL container:

docker run -d \
  --name databridge-postgres \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=mydb \
  -p 5432:5432 \
  postgres:16

# Wait for PostgreSQL to be ready
docker logs databridge-postgres -f
# Press Ctrl+C when you see "database system is ready to accept connections"

2. Connection string:

DATABASE_URL="postgresql://postgres:password@127.0.0.1:5432/mydb"

SQL Server with Docker

1. Start SQL Server container:

docker run -d \
  --name databridge-sqlserver \
  -e 'ACCEPT_EULA=Y' \
  -e 'SA_PASSWORD=YourStrong@Passw0rd' \
  -p 1433:1433 \
  mcr.microsoft.com/mssql/server:2022-latest

# Wait for SQL Server to be ready
docker logs databridge-sqlserver -f
# Press Ctrl+C when you see "SQL Server is now ready"

2. Create database:

# Using sqlcmd inside container
docker exec -it databridge-sqlserver \
  /opt/mssql-tools18/bin/sqlcmd \
  -S localhost -U sa -P 'YourStrong@Passw0rd' -C \
  -Q "CREATE DATABASE mydb;"

⚠️ Windows Git Bash Users: If you get path conversion errors, prefix the command with MSYS_NO_PATHCONV=1:

MSYS_NO_PATHCONV=1 docker exec -it databridge-sqlserver \
  /opt/mssql-tools18/bin/sqlcmd \
  -S localhost -U sa -P 'YourStrong@Passw0rd' -C \
  -Q "CREATE DATABASE mydb;"

This prevents Git Bash from converting Unix paths like /opt/mssql-tools18/bin/sqlcmd to Windows paths.

3. Connection string and environment variables:

# .env
DATABASE_URL="sqlserver://localhost:1433;database=mydb;user=sa;password=YourStrong@Passw0rd;encrypt=true;trustServerCertificate=true"
DB_SERVER=127.0.0.1
DB_PORT=1433
DB_NAME=mydb
DB_USER=sa
DB_PASSWORD=YourStrong@Passw0rd

Note: SQL Server adapter requires additional environment variables (DB_SERVER, DB_PORT, etc.) due to Prisma 7 adapter architecture.

SQLite with Docker (Optional)

SQLite doesn’t require Docker as it’s file-based:

# Just use a file path
DATABASE_URL="file:./dev.db"

If you want to use Docker for consistency:

# Create a volume for the database file
docker run -d \
  --name databridge-app \
  -v $(pwd):/app \
  -w /app \
  node:20 \
  tail -f /dev/null

# Connection string
DATABASE_URL="file:./dev.db"

CockroachDB with Docker

1. Start CockroachDB container:

docker run -d \
  --name databridge-cockroach \
  -p 26257:26257 \
  -p 8080:8080 \
  cockroachdb/cockroach:latest start-single-node --insecure

# Wait for CockroachDB to be ready
docker logs databridge-cockroach -f
# Press Ctrl+C when you see "CockroachDB node starting"

2. Create database:

docker exec -it databridge-cockroach \
  ./cockroach sql --insecure \
  -e "CREATE DATABASE mydb;"

3. Connection string:

DATABASE_URL="postgresql://root@127.0.0.1:26257/mydb?sslmode=disable"

Multi-Database Docker Compose

Create docker-compose.yml with all databases:

version: '3.8'

services:
  mysql:
    image: mysql:8.0
    container_name: databridge-mysql
    environment:
      MYSQL_ROOT_PASSWORD: password
      MYSQL_DATABASE: mydb
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql

  postgres:
    image: postgres:16
    container_name: databridge-postgres
    environment:
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mydb
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  sqlserver:
    image: mcr.microsoft.com/mssql/server:2022-latest
    container_name: databridge-sqlserver
    environment:
      ACCEPT_EULA: Y
      SA_PASSWORD: YourStrong@Passw0rd
    ports:
      - "1433:1433"
    volumes:
      - sqlserver_data:/var/opt/mssql

  cockroachdb:
    image: cockroachdb/cockroach:latest
    container_name: databridge-cockroach
    command: start-single-node --insecure
    ports:
      - "26257:26257"
      - "8080:8080"
    volumes:
      - cockroach_data:/cockroach/cockroach-data

volumes:
  mysql_data:
  postgres_data:
  sqlserver_data:
  cockroach_data:

Start all databases:

docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f

Environment Variables

Using .env File

Create a .env file in your project root:

MySQL:

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

PostgreSQL:

DATABASE_URL="postgresql://postgres:password@localhost:5432/mydb"

SQL Server:

DATABASE_URL="sqlserver://localhost:1433;database=mydb;user=sa;password=YourStrong@Passw0rd;encrypt=true;trustServerCertificate=true"
DB_SERVER=127.0.0.1
DB_PORT=1433
DB_NAME=mydb
DB_USER=sa
DB_PASSWORD=YourStrong@Passw0rd

SQLite:

DATABASE_URL="file:./dev.db"

CockroachDB:

DATABASE_URL="postgresql://root@localhost:26257/mydb?sslmode=disable"

Additional variables:

API_PORT=3000
NODE_ENV=development

Important: Add .env to .gitignore:

echo ".env" >> .gitignore

Using .databridge.json

The .databridge.json file can reference environment variables:

{
  "version": "0.2.9",
  "database": {
    "url": "${DATABASE_URL}"
  },
  "api": {
    "port": "${API_PORT}",
    "cors": "*"
  }
}

DataBridge will automatically read from .env when using ${VARIABLE} syntax.

Remote Database Connections

MySQL Managed Services

PlanetScale:

DATABASE_URL="mysql://user:pscale_pw_xxxxx@host.psdb.cloud/mydb?sslaccept=strict"

AWS RDS:

DATABASE_URL="mysql://admin:password@mydb.xxxxx.us-east-1.rds.amazonaws.com:3306/mydb"

DigitalOcean:

DATABASE_URL="mysql://doadmin:password@mydb-do-user-xxxxx.db.ondigitalocean.com:25060/mydb?ssl-mode=REQUIRED"

PostgreSQL Managed Services

AWS RDS:

DATABASE_URL="postgresql://postgres:password@mydb.xxxxx.us-east-1.rds.amazonaws.com:5432/mydb"

Heroku Postgres:

DATABASE_URL="postgresql://user:pass@ec2-xxx.compute-1.amazonaws.com:5432/dbname"

Supabase:

DATABASE_URL="postgresql://postgres:password@db.xxxxx.supabase.co:5432/postgres"

DigitalOcean:

DATABASE_URL="postgresql://doadmin:password@db-postgresql-nyc3-xxxxx.ondigitalocean.com:25060/defaultdb?sslmode=require"

SQL Server Managed Services

Azure SQL Database:

DATABASE_URL="sqlserver://myserver.database.windows.net:1433;database=mydb;user=admin@myserver;password=Pass123!;encrypt=true"

# Additional environment variables
DB_SERVER=myserver.database.windows.net
DB_PORT=1433
DB_NAME=mydb
DB_USER=admin@myserver
DB_PASSWORD=Pass123!

AWS RDS SQL Server:

DATABASE_URL="sqlserver://mydb.xxxxx.us-east-1.rds.amazonaws.com:1433;database=mydb;user=admin;password=Pass123!;encrypt=true"

DB_SERVER=mydb.xxxxx.us-east-1.rds.amazonaws.com
DB_PORT=1433
DB_NAME=mydb
DB_USER=admin
DB_PASSWORD=Pass123!

CockroachDB Managed Services

CockroachDB Serverless:

DATABASE_URL="postgresql://user:pass@free-tier.gcp-us-central1.cockroachlabs.cloud:26257/mydb?sslmode=verify-full"

CockroachDB Dedicated:

DATABASE_URL="postgresql://user:pass@cluster-name.cockroachlabs.cloud:26257/mydb?sslmode=verify-full&sslrootcert=certs/ca.crt"

Railway (Multiple Databases)

# Railway provides DATABASE_URL automatically
DATABASE_URL="${DATABASE_URL}"

Prisma Schema Configuration

After running databridge introspect, your prisma/schema.prisma will have the correct provider:

MySQL:

datasource db {
  provider = "mysql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
  output   = "../generated/prisma"
}

model users {
  id         Int       @id @default(autoincrement())
  email      String    @unique @db.VarChar(255)
  name       String    @db.VarChar(100)
  created_at DateTime? @default(now())
}

PostgreSQL:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
  output   = "../generated/prisma"
}

SQL Server:

datasource db {
  provider = "sqlserver"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
  output   = "../generated/prisma"
}

SQLite:

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
  output   = "../generated/prisma"
}

CockroachDB:

datasource db {
  provider = "cockroachdb"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
  output   = "../generated/prisma"
}

New in v0.2.x: DataBridge automatically detects and updates the provider during databridge introspect!

Troubleshooting

Connection Refused

Error:

Error: P1001: Can't reach database server

Solutions:

  1. Check database is running:

    # Docker - check all databases
docker ps

# Check specific database
docker ps | grep mysql
docker ps | grep postgres
docker ps | grep sqlserver
docker ps | grep cockroach

  2. Check port is correct:

    # Find container ports
docker port databridge-mysql      # Should show 3306
docker port databridge-postgres   # Should show 5432
docker port databridge-sqlserver  # Should show 1433
docker port databridge-cockroach  # Should show 26257

  3. Use 127.0.0.1 instead of localhost:

    # Instead of localhost, use 127.0.0.1
DATABASE_URL="mysql://root:pass@127.0.0.1:3306/mydb"
DATABASE_URL="postgresql://postgres:pass@127.0.0.1:5432/mydb"

Authentication Failed

Error:

Error: P1000: Authentication failed against database server

Solutions:

  1. MySQL - Check credentials:

    mysql -h 127.0.0.1 -u root -ppassword

  2. PostgreSQL - Check credentials:

    psql -h 127.0.0.1 -U postgres -d mydb

  3. SQL Server - Check credentials:

    docker exec -it databridge-sqlserver \
  /opt/mssql-tools18/bin/sqlcmd \
  -S localhost -U sa -P 'YourStrong@Passw0rd' -C

# Windows Git Bash users, use:
MSYS_NO_PATHCONV=1 docker exec -it databridge-sqlserver \
  /opt/mssql-tools18/bin/sqlcmd \
  -S localhost -U sa -P 'YourStrong@Passw0rd' -C

  4. Reset Docker container password:

    docker rm -f databridge-mysql
docker run -d --name databridge-mysql \
  -e MYSQL_ROOT_PASSWORD=newpassword \
  -p 3306:3306 mysql:8.0

  5. URL encode special characters (see encoding table above)

Database Not Found

Error:

Error: P1003: Database does not exist

Solutions:

  1. MySQL - Create database:

    mysql -h 127.0.0.1 -u root -ppassword -e "CREATE DATABASE mydb"

  2. PostgreSQL - Create database:

    docker exec -it databridge-postgres \
  psql -U postgres -c "CREATE DATABASE mydb;"

  3. SQL Server - Create database:

    docker exec -it databridge-sqlserver \
  /opt/mssql-tools18/bin/sqlcmd \
  -S localhost -U sa -P 'YourStrong@Passw0rd' -C \
  -Q "CREATE DATABASE mydb;"

# Windows Git Bash users, use:
MSYS_NO_PATHCONV=1 docker exec -it databridge-sqlserver \
  /opt/mssql-tools18/bin/sqlcmd \
  -S localhost -U sa -P 'YourStrong@Passw0rd' -C \
  -Q "CREATE DATABASE mydb;"

  4. CockroachDB - Create database:

    docker exec -it databridge-cockroach \
  ./cockroach sql --insecure \
  -e "CREATE DATABASE mydb;"

  5. Or use Docker environment variable:

    # MySQL
docker run -d --name databridge-mysql \
  -e MYSQL_ROOT_PASSWORD=password \
  -e MYSQL_DATABASE=mydb \
  -p 3306:3306 mysql:8.0

# PostgreSQL
docker run -d --name databridge-postgres \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=mydb \
  -p 5432:5432 postgres:16

SSL/TLS Issues

Error:

Error: SSL connection error

Solutions:

  1. MySQL - Disable SSL for local dev:

    DATABASE_URL="mysql://root:pass@localhost:3306/mydb?sslmode=disable"

  2. PostgreSQL - Disable SSL for local dev:

    DATABASE_URL="postgresql://postgres:pass@localhost:5432/mydb?sslmode=disable"

  3. SQL Server - Trust server certificate:

    DATABASE_URL="sqlserver://localhost:1433;database=mydb;user=sa;password=Pass123!;encrypt=true;trustServerCertificate=true"

  4. CockroachDB - Disable SSL for local dev:

    DATABASE_URL="postgresql://root@localhost:26257/mydb?sslmode=disable"

  5. Enable SSL for production:

    # MySQL
DATABASE_URL="mysql://user:pass@host:3306/mydb?ssl=true"

# PostgreSQL
DATABASE_URL="postgresql://user:pass@host:5432/mydb?sslmode=require"

# SQL Server
DATABASE_URL="sqlserver://host:1433;database=mydb;user=admin;password=Pass123!;encrypt=true"

SQL Server Specific Issues

Error: SQL Server environment variables not loaded:

TypeError: Cannot read property 'server' of undefined

Solution: Ensure all required environment variables are set:

# .env
DATABASE_URL="sqlserver://localhost:1433;database=mydb;user=sa;password=YourStrong@Passw0rd;encrypt=true;trustServerCertificate=true"
DB_SERVER=127.0.0.1
DB_PORT=1433
DB_NAME=mydb
DB_USER=sa
DB_PASSWORD=YourStrong@Passw0rd

Error: SQL Server connection timeout:

Error: Failed to connect to localhost:1433 in 15000ms

Solutions:

  1. Wait for SQL Server to fully start (can take 30-60 seconds)
  2. Check SQL Server logs: docker logs databridge-sqlserver
  3. Verify container is running: docker ps | grep sqlserver

Port Already in Use

Error:

docker: Error response: port is already allocated

Solutions:

  1. Find what’s using the port:

    # Linux/Mac
lsof -i :3306   # MySQL
lsof -i :5432   # PostgreSQL
lsof -i :1433   # SQL Server
lsof -i :26257  # CockroachDB

# Windows
netstat -ano | findstr :3306
netstat -ano | findstr :5432
netstat -ano | findstr :1433
netstat -ano | findstr :26257

  2. Use different port:

    # MySQL on port 3307
docker run -d --name databridge-mysql \
  -e MYSQL_ROOT_PASSWORD=password \
  -e MYSQL_DATABASE=mydb \
  -p 3307:3306 \
  mysql:8.0

DATABASE_URL="mysql://root:password@localhost:3307/mydb"

Prisma Provider Mismatch

Error:

Error: Invalid database string. Must start with mysql://

Solution: Run databridge introspect which auto-detects and updates the provider:

databridge introspect

This automatically updates your prisma/schema.prisma with the correct provider based on your DATABASE_URL.

Best Practices

Security

✅ Always use environment variables for credentials

# .env
DATABASE_URL="mysql://root:${DB_PASSWORD}@localhost:3306/mydb"

✅ Keep .env in .gitignore

echo ".env" >> .gitignore

✅ Use SSL/TLS in production

# Production
DATABASE_URL="mysql://user:pass@host:3306/mydb?ssl=true"

# Development
DATABASE_URL="mysql://root:pass@localhost:3306/mydb"

✅ Never commit credentials to git

Performance

✅ Use connection pooling (handled automatically by Prisma 7 adapters)

✅ Keep database close to your API server (same region/datacenter)

✅ Use indexes for frequently queried fields

Development Workflow

✅ Use Docker for consistent local development

✅ Keep separate databases for dev/staging/production

# .env.development
DATABASE_URL="mysql://root:pass@localhost:3306/mydb_dev"

# .env.production
DATABASE_URL="mysql://user:pass@prod-host:3306/mydb"

✅ Backup production data regularly

Next Steps

Now that your database is configured:

  1. Run introspect - Generate Prisma schema
  2. Generate API - Create REST endpoints
  3. Test endpoints - Use Swagger UI

Additional Resources

Port Already in Use

Error:

docker: Error response: port is already allocated

Solutions:

  1. Find what’s using port 3306:

    # Linux/Mac
lsof -i :3306

# Windows
netstat -ano | findstr :3306

  2. Use different port:

    docker run -d --name databridge-mysql \
  -e MYSQL_ROOT_PASSWORD=password \
  -p 3307:3306 \
  mysql:8.0

# Update connection string:
DATABASE_URL="mysql://root:password@localhost:3307/mydb"

Testing Your Connection

Method 1: MySQL CLI

mysql -h 127.0.0.1 -P 3306 -u root -ppassword -e "SHOW DATABASES"

Method 2: DataBridge Introspect

databridge introspect
# If successful, you'll see your tables listed

Method 3: Prisma Studio

npx prisma studio
# Opens http://localhost:5555 with database browser

Best Practices

Development

  • ✅ Use Docker for consistent environment
  • ✅ Store credentials in .env file
  • ✅ Add .env to .gitignore
  • ✅ Use strong passwords even in dev
  • ✅ Keep .databridge.json in version control (without credentials)

Production

  • ✅ Use environment variables (never commit credentials)
  • ✅ Enable SSL/TLS connections
  • ✅ Use connection pooling
  • ✅ Implement connection retry logic
  • ✅ Monitor connection health
  • ✅ Use managed database services (RDS, PlanetScale, etc.)

Security Checklist

# .gitignore
.env
.env.local
.env.production
*.pem
*.key

# Never commit these patterns:
# mysql://root:password@...
# MYSQL_ROOT_PASSWORD=...

Additional Resources

Was this page helpful?

Edit this page on GitHub