{
    "slug": "database_partitioning",
    "term": "Database Partitioning",
    "category": "performance",
    "difficulty": "advanced",
    "short": "Splitting a large table into physical segments by range, list, or hash — enabling partition pruning, faster archival, and parallel scans.",
    "long": "Partitioning divides a single logical table into multiple physical storage segments. MySQL and PostgreSQL support: Range partitioning (by date range — perfect for time-series data and rolling retention), List partitioning (by discrete values — region or status), Hash partitioning (distributes rows evenly), and Composite forms. Benefits: partition pruning (a query on the last 7 days scans only recent partitions), fast archival (DROP PARTITION is instant vs DELETE on millions of rows), and parallel scan on multi-core hardware. Unlike sharding, partitioning is transparent to the application — all partitions appear as one table with no application-layer changes required.",
    "aliases": [
        "table partitioning",
        "horizontal partitioning",
        "range partitioning"
    ],
    "tags": [
        "performance",
        "database",
        "scalability",
        "architecture"
    ],
    "misconception": "Partitioning and sharding are the same technique. Partitioning divides a table within a single database server — the database engine manages it transparently. Sharding distributes data across multiple servers, requiring application-level routing logic.",
    "why_it_matters": "Partitioning splits a large table into smaller physical segments — queries that filter on the partition key only scan relevant partitions, and old partitions can be archived or dropped instantly.",
    "common_mistakes": [
        "Partitioning tables that are not actually large enough to benefit — adds complexity with no gain.",
        "Choosing a partition key that most queries don't filter on — all partitions are scanned anyway.",
        "Not including the partition key in the primary key — required in most databases for partitioned tables.",
        "Assuming partitioning replaces indexing — indexes within partitions are still needed for non-partition-key filters."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "database_sharding",
        "database_indexing",
        "query_plan"
    ],
    "prerequisites": [
        "db_schema_design",
        "database_indexing",
        "db_time_series"
    ],
    "refs": [
        "https://dev.mysql.com/doc/refman/8.0/en/partitioning.html"
    ],
    "bad_code": "-- Without partitioning: DELETE of old rows is slow and locks the table:\nDELETE FROM events WHERE created_at < '2023-01-01'; -- Deletes millions of rows slowly\n\n-- With range partitioning by month:\n-- DROP PARTITION p_2023_01; -- Instant, no row-by-row deletion",
    "good_code": "-- PostgreSQL range partitioning by date — each partition is a separate table\nCREATE TABLE events (\n    id         BIGSERIAL,\n    created_at TIMESTAMPTZ NOT NULL,\n    payload    JSONB\n) PARTITION BY RANGE (created_at);\n\nCREATE TABLE events_2024_q1 PARTITION OF events\n    FOR VALUES FROM ('2024-01-01') TO ('2024-04-01');\nCREATE TABLE events_2024_q2 PARTITION OF events\n    FOR VALUES FROM ('2024-04-01') TO ('2024-07-01');\n\n-- Queries filtered on created_at only scan the relevant partition\n-- Old partitions can be detached and archived without touching live data\nALTER TABLE events DETACH PARTITION events_2024_q1;",
    "quick_fix": "Partition large tables by date range — MySQL: PARTITION BY RANGE(YEAR(created_at)); each partition can be dropped (instant) instead of deleted (slow) for archival",
    "severity": "medium",
    "effort": "high",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/database_partitioning",
        "html_url": "https://codeclaritylab.com/glossary/database_partitioning",
        "json_url": "https://codeclaritylab.com/glossary/database_partitioning.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Database Partitioning](https://codeclaritylab.com/glossary/database_partitioning) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/database_partitioning"
            }
        }
    }
}