{"id":31322753,"url":"https://github.com/valarpirai/sharding-springboot","last_synced_at":"2026-04-10T00:48:37.639Z","repository":{"id":316357202,"uuid":"1063032745","full_name":"valarpirai/sharding-springboot","owner":"valarpirai","description":"Database Sharding library with Multi-Tenant support","archived":false,"fork":false,"pushed_at":"2025-09-24T04:47:56.000Z","size":86,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-24T06:21:47.212Z","etag":null,"topics":["database","java","multi-tenant","mysql","postgres","sharding","spring-boot"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/valarpirai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-24T04:36:31.000Z","updated_at":"2025-09-24T04:51:05.000Z","dependencies_parsed_at":"2025-09-24T06:21:49.524Z","dependency_job_id":"28055914-c7af-461d-a2f4-fe125670a5b6","html_url":"https://github.com/valarpirai/sharding-springboot","commit_stats":null,"previous_names":["valarpirai/sharding-springboot"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/valarpirai/sharding-springboot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valarpirai%2Fsharding-springboot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valarpirai%2Fsharding-springboot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valarpirai%2Fsharding-springboot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valarpirai%2Fsharding-springboot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/valarpirai","download_url":"https://codeload.github.com/valarpirai/sharding-springboot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valarpirai%2Fsharding-springboot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276966584,"owners_count":25736821,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-25T02:00:09.612Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","java","multi-tenant","mysql","postgres","sharding","spring-boot"],"created_at":"2025-09-25T19:12:42.943Z","updated_at":"2026-04-10T00:48:37.610Z","avatar_url":"https://github.com/valarpirai.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sharding Spring Boot Starter\n\nProduction-ready multi-tenant database sharding solution with Spring Boot auto-configuration.\n\n## Project Structure\n\n```\nsharding-springboot/\n├── sharding-springboot-starter/   # Core sharding library\n├── sample-sharded-app/            # Demo ticket management application\n└── docs/                          # Comprehensive documentation\n```\n\n## Key Features\n\n✅ **Directory-Based Sharding** - Tenant-to-shard mapping via `tenant_shard_mapping` table\n✅ **Multi-Replica Support** - Master-replica configuration with automatic read/write splitting\n✅ **Auto-Configuration** - Zero-config Spring Boot integration\n✅ **Entity Validation** - `@ShardedEntity` annotation validation during startup\n✅ **Query Validation** - SQL-level tenant filtering with configurable strictness\n✅ **Connection Routing** - Intelligent routing based on tenant context\n✅ **HikariCP Optimization** - Database-specific tuning with optimal defaults\n✅ **Batch Processing** - Tenant iterator for background jobs\n✅ **Monitoring** - JMX metrics and routing statistics\n✅ **Multi-Database Support** - Native MySQL and PostgreSQL support with database-specific optimizations\n✅ **Dual DataSource Configuration** - Automatic separation of global and sharded entities with package-based routing\n\n### Architecture Components\n\n#### 📁 Configuration (`/config/`)\n- `ShardingConfigProperties` - Main configuration with flat structure\n- `HikariConfigProperties` - Comprehensive HikariCP settings\n- `ShardingAutoConfiguration` - Spring Boot auto-configuration\n- `ShardingDataSourceAutoConfiguration` - Dual DataSource auto-configuration with Lombok-based properties\n- `DualDataSourceProperties` - Package-based routing configuration (Lombok)\n- `HikariConfigUtil` - Optimal defaults and database-specific optimizations\n\n#### 🎯 Context Management (`/context/`)\n- `TenantContext` - Thread-local tenant information\n- `TenantInfo` - Immutable tenant data holder\n\n#### 🔍 Shard Lookup (`/lookup/`)\n- `TenantShardMappingRepository` - Directory-based tenant-shard mapping\n- `TenantShardMapping` - Data model for lookup table\n- `ShardUtils` - Comprehensive shard management utilities\n- `DatabaseSqlProvider` - Interface for database-specific SQL operations\n- `MySQLSqlProvider` - MySQL-specific SQL implementation\n- `PostgreSQLSqlProvider` - PostgreSQL-specific SQL implementation\n- `DatabaseSqlProviderFactory` - Automatic database detection and provider selection\n\n#### 🔄 Connection Routing (`/routing/`)\n- `ShardAwareDataSourceDelegate` - Routes connections based on tenant context\n- `RoutingDataSource` - Spring DataSource integration\n- `RoutingDataSource` - Enhanced routing DataSource with dual configuration support\n- `ShardDataSources` - Master-replica container with load balancing\n\n#### 🛡️ Validation (`/validation/`)\n- `QueryValidator` - SQL query validation for tenant filtering\n- `EntityValidator` - `@ShardedEntity` annotation validation\n- `ValidatingDataSource` - DataSource proxy for query interception\n\n#### 🔄 Batch Processing (`/iterator/`)\n- `TenantIterator` - Batch processing with parallel support\n- Background job utilities for cross-tenant operations\n\n#### 🏷️ Annotations (`/annotation/`)\n- `@ShardedEntity` - Marker for sharded entities\n\n### Configuration Example\n\n**PostgreSQL Configuration (Default):**\n```properties\n# Global Database\napp.sharding.global-db.url=jdbc:postgresql://localhost:5432/global_db\napp.sharding.global-db.username=global_user\napp.sharding.global-db.password=global_password\n\n# Shard Configuration\napp.sharding.shards.shard1.master.url=jdbc:postgresql://localhost:5432/shard1_db\napp.sharding.shards.shard1.replicas.replica1.url=jdbc:postgresql://localhost:5433/shard1_db\napp.sharding.shards.shard1.hikari.maximum-pool-size=20\napp.sharding.shards.shard1.latest=true\n\n# Validation\napp.sharding.validation.strictness=STRICT\napp.sharding.tenant-column-names=tenant_id,company_id\n```\n\n**Alternative Database Support:**\n- Full MySQL 5.7+ support with optimizations\n- Full PostgreSQL 11+ support with optimizations\n- Automatic database type detection from JDBC URLs\n\n### Maven Dependency\n\nAdd the sharding starter to your project's `pom.xml`:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.valarpirai\u003c/groupId\u003e\n    \u003cartifactId\u003esharding-springboot-starter\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### Usage Example\n\n```java\n@Entity\n@ShardedEntity  // Routes to tenant-specific shard\npublic class Customer {\n    @Column(name = \"tenant_id\", nullable = false)\n    private Long tenantId;\n    // ... other fields\n}\n\n@Service\npublic class CustomerService {\n    public Customer save(Customer customer) {\n        return TenantContext.executeInTenantContext(customer.getTenantId(), () -\u003e {\n            return customerRepository.save(customer);\n        });\n    }\n}\n```\n\n## 🆕 Sample Sharded Application\n\n**Location**: `sample-sharded-app/`\n**Purpose**: Complete demonstration of the sharding library\n\n### Features Demonstrated\n- Sharded entities (`Customer`) with tenant isolation\n- Non-sharded entities (`GlobalConfig`) in global database\n- REST API with tenant context management\n- Database setup scripts with sample data\n- Configuration examples\n\n### API Endpoints\n```\nPOST /api/customers/set-tenant/{tenantId}  # Set tenant context\nPOST /api/customers                        # Create customer\nGET  /api/customers                        # Get customers for tenant\nGET  /api/customers/{id}                   # Get specific customer\nPUT  /api/customers/{id}                   # Update customer\nDELETE /api/customers/{id}                 # Delete customer\n```\n\n## 📊 Technical Specifications\n\n### Validation Levels\n- **STRICT**: Throw exception if tenant_id missing (Production)\n- **WARN**: Log warning but proceed (Development)\n- **LOG**: Info logging only (Testing)\n- **DISABLED**: No validation (Not recommended)\n\n### Database Support \u0026 Optimization\n\n#### Supported Databases\n- ✅ **MySQL 5.7+** - Full support with MySQL-specific optimizations\n- ✅ **PostgreSQL 11+** - Full support with PostgreSQL-specific optimizations\n- 🔄 **SQL Server** - Planned for future release\n- 🔄 **Oracle** - Planned for future release\n\n#### HikariCP Database-Specific Optimizations\n- **MySQL**: Prepared statement caching, server-side preparation, UTF8MB4 charset support\n- **PostgreSQL**: Statement cache optimization, prepared statement thresholds, cache size tuning\n- **SQL Server**: Statement pooling configuration *(planned)*\n- **Oracle**: Implicit statement caching *(planned)*\n\n#### Automatic Database Detection\nThe library automatically detects the database type from JDBC URLs and applies appropriate SQL syntax and optimizations:\n- **MySQL**: Uses `DATABASE()` function and MySQL-specific table creation syntax\n- **PostgreSQL**: Uses `current_schema()` function and PostgreSQL-specific syntax\n- **Fallback**: Defaults to MySQL provider if detection fails\n\n### Connection Pool Defaults\n- `maximum-pool-size`: 20 (balanced for production)\n- `minimum-idle`: 5 (maintain ready connections)\n- `connection-timeout`: 30s (standard timeout)\n- `idle-timeout`: 10m (cleanup idle connections)\n- `max-lifetime`: 30m (connection refresh)\n\n### Replica Selection Strategies\n- **ROUND_ROBIN**: Distribute load across replicas\n- **RANDOM**: Random replica selection\n- **FIRST_AVAILABLE**: Always use first replica\n\n## Quick Start\n\n```bash\n# 1. Build the library\nmvn clean install\n\n# 2. Set up PostgreSQL databases\ncd sample-sharded-app\npsql -U postgres -f database-setup.sql\n\n# 3. Run the sample application\nmvn spring-boot:run\n\n# 4. Access Swagger UI\nopen http://localhost:8080/swagger-ui.html\n```\n\n## Documentation\n\n📚 **[Complete Documentation](docs/)** - Comprehensive guides, deployment, testing, and reference\n\n### Quick Links\n\n- **[Getting Started](docs/guides/getting-started.md)** - Installation and basic usage\n- **[Migrations Guide](docs/guides/migrations.md)** - Database schema changes across shards\n- **[Transactions Guide](docs/guides/transactions.md)** - Transaction patterns\n- **[Zero Downtime Deployment](docs/deployment/zero-downtime.md)** - Production best practices\n- **[Integration Tests](docs/testing/integration-tests.md)** - Testing guide (69 comprehensive tests)\n- **[Technical Specification](docs/reference/specification.md)** - Complete library reference\n\n## Basic Usage\n\n### 1. Add Dependency\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.valarpirai\u003c/groupId\u003e\n    \u003cartifactId\u003esharding-springboot-starter\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### 2. Configure\n\n```properties\n# Global Database\napp.sharding.global-db.url=jdbc:postgresql://localhost:5432/global_db\napp.sharding.global-db.username=user\napp.sharding.global-db.password=pass\n\n# Shard\napp.sharding.shards.shard1.master.url=jdbc:postgresql://localhost:5432/shard1_db\napp.sharding.shards.shard1.master.username=user\napp.sharding.shards.shard1.master.password=pass\napp.sharding.shards.shard1.latest=true\n```\n\n### 3. Mark Sharded Entities\n\n```java\n@Entity\n@ShardedEntity\npublic class Customer {\n    @Column(nullable = false)\n    private Long tenantId;  // Required\n    \n    private String name;\n}\n```\n\n### 4. Use Tenant Context\n\n```java\n@Service\npublic class CustomerService {\n    public Customer save(Long tenantId, Customer customer) {\n        return TenantContext.executeInTenantContext(tenantId, () -\u003e {\n            return customerRepository.save(customer);\n        });\n    }\n}\n```\n\n## Architecture\n\n### Two-Database Model\n\n1. **Global DB**: Central database for tenant-shard mappings and global entities\n2. **Shard DBs**: Multiple databases with tenant-specific data (master + replicas)\n\n### Package-Based Routing\n\n- Global entities/repos → `*.entity.global`, `*.repository.global`\n- Sharded entities/repos → `*.entity.sharded`, `*.repository.sharded`\n\n### Migration Strategies\n\n- **SEQUENTIAL**: One shard at a time (safest)\n- **PARALLEL**: All shards simultaneously (fastest)\n- **WAVE**: Batches with delays (recommended for production)\n- **CANARY**: Test on one shard first (critical changes)\n\n## Benefits\n\n**For Developers:**\n- ✅ Zero-configuration Spring Boot integration\n- ✅ Type-safe entity validation at compile time\n- ✅ Database-agnostic (PostgreSQL, MySQL with auto-detection)\n- ✅ Comprehensive testing suite (69 integration tests)\n\n**For Operations:**\n- ✅ Multiple migration strategies (sequential, parallel, wave, canary)\n- ✅ Database-specific HikariCP optimizations\n- ✅ JMX metrics and health endpoints\n- ✅ Read-write splitting with replica support\n\n**For Business:**\n- ✅ Complete tenant data isolation\n- ✅ Horizontal scalability (add shards as needed)\n- ✅ Production-ready with zero-downtime deployment patterns\n- ✅ Compliance-friendly with strict query validation\n\n## Sample Application\n\nThe `sample-sharded-app` demonstrates a multi-tenant ticket management system:\n\n- **Account signup** with automatic demo environment setup\n- **JWT authentication** with tenant validation\n- **User and ticket management** with role-based permissions\n- **Liquibase migrations** across global DB and shards\n- **Comprehensive tests** including API, security, and migration tests\n\n**API Documentation**: http://localhost:8080/swagger-ui.html (when running)\n\n## Tech Stack\n\n- **Java 21**\n- **Spring Boot 3.4.5**\n- **Hibernate/JPA**\n- **HikariCP** (connection pooling)\n- **Liquibase** (schema migrations)\n- **PostgreSQL** / **MySQL** (auto-detected)\n- **TestContainers** (integration tests)\n\n## License\n\nLicensed under the MIT License. See `LICENSE` file for details.\n\n---\n\n**For complete documentation, see [`docs/`](docs/) directory.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvalarpirai%2Fsharding-springboot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvalarpirai%2Fsharding-springboot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvalarpirai%2Fsharding-springboot/lists"}