Configuration - Kin Conecta

Overview

This guide covers configuring the Kin Conecta backend application, focusing on database connections, JPA settings, and environment-specific configurations.

Configuration File Location

The main configuration file is located at:

backendKC/src/main/resources/application.properties

This file contains all Spring Boot application settings, including database connection parameters.

Database Configuration

Connection Settings

The backend requires MySQL database connection settings. Configure these properties in application.properties:

# Application name
spring.application.name=KCv2

# Database connection URL
spring.datasource.url=jdbc:mysql://localhost:3306/KCv2?useSSL=false&allowPublicKeyRetrieval=true

# Database credentials
spring.datasource.username=root
spring.datasource.password=YOUR_PASSWORD

# MySQL JDBC driver
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

Never commit actual passwords to version control. Use environment variables or a separate config file that’s ignored by Git.

Connection URL Parameters

The datasource URL includes important parameters:

localhost:3306 - MySQL host and port
KCv2 - Database schema name (must match the schema created by kinConnect.sql)
useSSL=false - Disables SSL for local development
allowPublicKeyRetrieval=true - Allows the MySQL 8.0+ authentication method

Changing the Schema Name

If you need to use a different schema name:

Update the schema name in the SQL script (kinConnect.sql)
Update the URL in application.properties:

spring.datasource.url=jdbc:mysql://localhost:3306/KCv2?useSSL=false&allowPublicKeyRetrieval=true

The schema name in the INSTRUCTIONS.md file mentions both kin_conecta and kinConecta. The actual SQL script uses KCv2. Ensure consistency between your SQL script and configuration.

JPA and Hibernate Configuration

Schema Management

Control how Hibernate handles the database schema:

spring.jpa.hibernate.ddl-auto=update

Available options:

update

Updates schema automatically when entities change. Recommended for development.

validate

Validates schema matches entities but makes no changes. Recommended for production.

create

Creates schema on startup, destroying existing data. Use with caution.

create-drop

Creates schema on startup, drops on shutdown. Only for testing.

none

No schema management. Use when schema is managed externally via SQL scripts.

For production environments, use validate or none to prevent accidental schema changes. Manage schema changes through SQL migration scripts instead.

SQL Logging

Enable SQL query logging for debugging:

# Show SQL queries in console
spring.jpa.show-sql=true

# Format SQL for readability
spring.jpa.properties.hibernate.format_sql=true

Example output:

Hibernate: 
    select
        u1_0.user_id,
        u1_0.full_name,
        u1_0.email,
        u1_0.role 
    from
        users u1_0

Disable SQL logging in production for better performance and cleaner logs.

Environment-Specific Configurations

Spring Boot supports multiple configuration files for different environments.

Creating Environment Profiles

Create Profile-Specific Files

Create separate properties files for each environment:

application-dev.properties - Development
application-staging.properties - Staging
application-prod.properties - Production

Configure Each Profile

# Development database
spring.datasource.url=jdbc:mysql://localhost:3306/KCv2?useSSL=false&allowPublicKeyRetrieval=true
spring.datasource.username=root
spring.datasource.password=devpassword

# Enable SQL logging
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

# Auto-update schema
spring.jpa.hibernate.ddl-auto=update

Activate a Profile

Specify the active profile when running the application:

# Development
./gradlew bootRun --args='--spring.profiles.active=dev'

# Production
./gradlew bootRun --args='--spring.profiles.active=prod'

Environment Variables

Use environment variables for sensitive configuration:

Setting Environment Variables

export DB_USERNAME=root
export DB_PASSWORD=secret123
export DB_HOST=localhost
export DB_PORT=3306
export DB_NAME=KCv2

Using Environment Variables

Reference environment variables in application.properties:

spring.datasource.url=jdbc:mysql://${DB_HOST:localhost}:${DB_PORT:3306}/${DB_NAME:KCv2}?useSSL=false&allowPublicKeyRetrieval=true
spring.datasource.username=${DB_USERNAME:root}
spring.datasource.password=${DB_PASSWORD}

The syntax ${VAR_NAME:default} provides a default value if the environment variable is not set.

Server Configuration

Port Configuration

Change the server port if 8080 is already in use:

# Change server port
server.port=8081

Context Path

Add a context path to the application:

# Access at http://localhost:8080/kinconecta
server.servlet.context-path=/kinconecta

Session Configuration

# Session timeout (30 minutes)
server.servlet.session.timeout=30m

# Session cookie name
server.servlet.session.cookie.name=KINCONECTA_SESSION

Security Configuration

The application includes Spring Security. Configure authentication settings:

# Security settings (add to application.properties)
spring.security.user.name=admin
spring.security.user.password=admin123

These basic authentication settings are for development only. Implement proper authentication and authorization for production.

Recommended Configurations

Development Environment

Optimal settings for local development:

spring.application.name=KCv2

# Database
spring.datasource.url=jdbc:mysql://localhost:3306/KCv2?useSSL=false&allowPublicKeyRetrieval=true
spring.datasource.username=root
spring.datasource.password=YOUR_DEV_PASSWORD
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

# JPA/Hibernate
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

# Server
server.port=8080

Production Environment

Secure settings for production deployment:

spring.application.name=KCv2

# Database (use environment variables)
spring.datasource.url=jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_NAME}?useSSL=true&requireSSL=true
spring.datasource.username=${DB_USERNAME}
spring.datasource.password=${DB_PASSWORD}
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

# JPA/Hibernate
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.show-sql=false
spring.jpa.properties.hibernate.format_sql=false

# Connection pool
spring.datasource.hikari.maximum-pool-size=10
spring.datasource.hikari.minimum-idle=5
spring.datasource.hikari.connection-timeout=30000

# Server
server.port=8080

Connection Pool Settings

Spring Boot uses HikariCP as the default connection pool. Configure it for optimal performance:

# Maximum number of connections
spring.datasource.hikari.maximum-pool-size=10

# Minimum idle connections
spring.datasource.hikari.minimum-idle=5

# Connection timeout (milliseconds)
spring.datasource.hikari.connection-timeout=30000

# Maximum lifetime of a connection (milliseconds)
spring.datasource.hikari.max-lifetime=1800000

# Idle timeout (milliseconds)
spring.datasource.hikari.idle-timeout=600000

Troubleshooting Configuration Issues

Schema Name Mismatch

Problem: Unknown database 'KCv2' Solution:

Verify the schema exists in MySQL:
```
SHOW DATABASES LIKE 'KCv2';
```
Ensure the schema name in the SQL script matches application.properties
Create the schema if it doesn’t exist

Authentication Failures

Problem: Access denied for user 'root'@'localhost' Solution:

Verify MySQL credentials are correct
Test connection manually:
```
mysql -u root -p
```

Ensure the MySQL user has proper permissions:

GRANT ALL PRIVILEGES ON KCv2.* TO 'root'@'localhost';
FLUSH PRIVILEGES;

SSL Connection Errors

Problem: SSL connection errors with MySQL Solution:

For local development, disable SSL:

spring.datasource.url=jdbc:mysql://localhost:3306/KCv2?useSSL=false&allowPublicKeyRetrieval=true

For production, configure proper SSL certificates

Connection Pool Exhaustion

Problem: Connection pool exhausted errors under load Solution: Increase pool size and adjust timeouts:

spring.datasource.hikari.maximum-pool-size=20
spring.datasource.hikari.connection-timeout=60000

Validation

After configuration, verify everything works:

Start the Application

./gradlew bootRun

Check Logs

Look for successful startup messages:

Tomcat started on port(s): 8080 (http)
Started KCv2Application in X.XXX seconds

Test Database Connection

Watch for SQL queries in the logs if show-sql=true

Test an Endpoint

curl http://localhost:8080/api/users

Next Steps

Database Setup - Create and populate the database
Backend Deployment - Run the Spring Boot application
Frontend Deployment - Serve the web interface
Review security best practices for production deployment

Setup

​Overview

​Configuration File Location

​Database Configuration

​Connection Settings

​Connection URL Parameters

​Changing the Schema Name

​JPA and Hibernate Configuration

​Schema Management

update

validate

create

create-drop

none

​SQL Logging

​Environment-Specific Configurations

​Creating Environment Profiles

​Environment Variables

​Setting Environment Variables

​Using Environment Variables

​Server Configuration

​Port Configuration

​Context Path

​Session Configuration

​Security Configuration

​Recommended Configurations

​Development Environment

​Production Environment

​Connection Pool Settings

​Troubleshooting Configuration Issues

​Schema Name Mismatch

​Authentication Failures

​SSL Connection Errors

​Connection Pool Exhaustion

​Validation

​Next Steps

Build docs developers (and LLMs) love

Overview

Configuration File Location

Database Configuration

Connection Settings

Connection URL Parameters

Changing the Schema Name

JPA and Hibernate Configuration

Schema Management

SQL Logging

Environment-Specific Configurations

Creating Environment Profiles

Environment Variables

Setting Environment Variables

Using Environment Variables

Server Configuration

Port Configuration

Context Path

Session Configuration

Security Configuration

Recommended Configurations

Development Environment

Production Environment

Connection Pool Settings

Troubleshooting Configuration Issues

Schema Name Mismatch

Authentication Failures

SSL Connection Errors

Connection Pool Exhaustion

Validation

Next Steps