gh-levnikolaevich-claude-code-skills-full-development-workflow-skills/skills/ln-114-project-docs-creator/references/templates/database_schema_template.md

Database Schema: {{PROJECT_NAME}}

Document Version: 1.0 Date: {{DATE}} Status: {{STATUS}}

---

1. Introduction

1.1 Purpose

This document specifies the database schema, entity relationships, and data dictionary for {{PROJECT_NAME}}.

1.2 Database System

{{DATABASE_SYSTEM}}

1.3 Normalization Level

{{NORMALIZATION_LEVEL}}

---

2. Entity Relationship Diagram

2.1 High-Level ER Diagram

erDiagram
    {{ER_DIAGRAM_ENTITIES_RELATIONSHIPS}}

---

3. Data Dictionary

3.1 {{TABLE_1}} Table

Table Name: {{table_1}} Description: {{TABLE_1_DESCRIPTION}}

Column	Type	Null	Default	Constraints	Description
id	UUID	NO	gen_random_uuid()	PRIMARY KEY	Unique user identifier
email	VARCHAR(255)	NO	-	UNIQUE, CHECK (email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+.[A-Z	a-z]{2,}$')
password_hash	VARCHAR(255)	NO	-	-	bcrypt hashed password
first_name	VARCHAR(100)	YES	NULL	-	User first name
last_name	VARCHAR(100)	YES	NULL	-	User last name
role	VARCHAR(20)	NO	'viewer'	CHECK (role IN ('admin', 'editor', 'viewer'))	User role for RBAC
is_active	BOOLEAN	NO	TRUE	-	Account status
created_at	TIMESTAMP	NO	CURRENT_TIMESTAMP	-	Account creation timestamp
updated_at	TIMESTAMP	NO	CURRENT_TIMESTAMP	ON UPDATE CURRENT_TIMESTAMP	Last update timestamp

Indexes:

CREATE UNIQUE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_role ON users(role);
CREATE INDEX idx_users_created_at ON users(created_at);

Relationships:

• users.id → orders.user_id (One-to-Many)
• users.id → reviews.user_id (One-to-Many)

---

3.2 {{TABLE_2}} Table

Table Name: {{table_2}} Description: {{TABLE_2_DESCRIPTION}}

Column	Type	Null	Default	Constraints	Description
id	UUID	NO	gen_random_uuid()	PRIMARY KEY	Product identifier
category_id	UUID	NO	-	FOREIGN KEY REFERENCES categories(id) ON DELETE RESTRICT	Product category
name	VARCHAR(200)	NO	-	-	Product name
slug	VARCHAR(220)	NO	-	UNIQUE	URL-friendly name
description	TEXT	YES	NULL	-	Product description
price	DECIMAL(10,2)	NO	-	CHECK (price >= 0)	Product price (USD)
stock_quantity	INTEGER	NO	0	CHECK (stock_quantity >= 0)	Available inventory
is_published	BOOLEAN	NO	FALSE	-	Publish status
created_at	TIMESTAMP	NO	CURRENT_TIMESTAMP	-	Creation timestamp
updated_at	TIMESTAMP	NO	CURRENT_TIMESTAMP	ON UPDATE CURRENT_TIMESTAMP	Last update timestamp

Indexes:

CREATE UNIQUE INDEX idx_products_slug ON products(slug);
CREATE INDEX idx_products_category_id ON products(category_id);
CREATE INDEX idx_products_is_published ON products(is_published);
CREATE INDEX idx_products_price ON products(price);

Relationships:

• categories.id → products.category_id (One-to-Many)
• products.id → order_items.product_id (One-to-Many)
• products.id → reviews.product_id (One-to-Many)

---

3.3 {{TABLE_3}} Table

{{TABLE_3_DEFINITION}}

---

4. Database Constraints

4.1 Foreign Key Constraints

FK Name	Child Table	Child Column	Parent Table	Parent Column	On Delete	On Update
fk_orders_user	orders	user_id	users	id	CASCADE	CASCADE
fk_products_category	products	category_id	categories	id	RESTRICT	CASCADE
fk_order_items_order	order_items	order_id	orders	id	CASCADE	CASCADE
fk_order_items_product	order_items	product_id	products	id	RESTRICT	CASCADE

4.2 Check Constraints

Constraint Name	Table	Expression	Description
chk_users_role	users	role IN ('admin', 'editor', 'viewer')	Valid role values
chk_products_price	products	price >= 0	Non-negative price
chk_products_stock	products	stock_quantity >= 0	Non-negative stock
chk_orders_status	orders	status IN ('pending', 'paid', 'shipped', 'delivered', 'canceled')	Valid order statuses

---

5. Indexes Strategy

5.1 Primary Indexes

{{PRIMARY_INDEXES}}

5.2 Secondary Indexes

{{SECONDARY_INDEXES}}

5.3 Composite Indexes

{{COMPOSITE_INDEXES}}

---

6. Database Migrations

6.1 Migration Tool

{{MIGRATION_TOOL}}

6.2 Migration Strategy

{{MIGRATION_STRATEGY}}

6.3 Migration Examples

Migration 001: Initial Schema

-- Up Migration
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    role VARCHAR(20) NOT NULL DEFAULT 'viewer',
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

-- Down Migration
DROP TABLE IF EXISTS users;

Migration 002: Add Soft Delete

-- Up Migration
ALTER TABLE users ADD COLUMN deleted_at TIMESTAMP NULL;
CREATE INDEX idx_users_deleted_at ON users(deleted_at);

-- Down Migration
ALTER TABLE users DROP COLUMN deleted_at;

---

7. Data Types & Standards

7.1 Common Data Types

Logical Type	PostgreSQL Type	MySQL Type	Description
UUID	UUID	CHAR(36)	Unique identifiers
Money	DECIMAL(10,2)	DECIMAL(10,2)	Currency values (2 decimal places)
Timestamp	TIMESTAMP	DATETIME	Date and time (UTC)
Boolean	BOOLEAN	TINYINT(1)	True/false values
JSON	JSONB	JSON	Semi-structured data

7.2 Naming Conventions

{{NAMING_CONVENTIONS}}

---

8. Maintenance

Last Updated: {{DATE}}

Update Triggers:

• New tables added
• Schema changes (columns, indexes, constraints)
• Migration scripts created
• Denormalization for performance
• Relationship changes

Verification:

• All tables documented with columns/types/constraints
• ER diagram matches actual schema
• Indexes match query patterns
• Foreign keys enforce referential integrity
• Migrations tested (up + down)

---

Version: 1.0.0 Template Last Updated: 2025-11-16