Skip to content

Commit f82a0b1

Browse files
committed
tweak readme
1 parent 60d6af4 commit f82a0b1

1 file changed

Lines changed: 8 additions & 8 deletions

File tree

README.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@ A PostgreSQL extension that enforces optimal column alignment to minimize row pa
77

88
## Why Column Order Matters
99

10-
PostgreSQL stores each row as a sequence of bytes on disk. Column types have different sizes a `bigint` takes 8 bytes, an `integer` takes 4, a `boolean` takes just 1. So far so simple.
10+
PostgreSQL stores each row as a sequence of bytes on disk. Column types have different sizes: a `bigint` takes 8 bytes, an `integer` takes 4, a `boolean` takes just 1. So far so simple.
1111

12-
The problem is that PostgreSQL can't just pack them back to back. The CPU reads memory most efficiently when values are naturally aligned an 8-byte value should start at a position divisible by 8, a 4-byte value at a position divisible by 4, and so on. To guarantee this, PostgreSQL inserts invisible **padding bytes** between columns whenever needed.
12+
The problem is that PostgreSQL can't just pack them back to back. The CPU reads memory most efficiently when values are naturally aligned; an 8-byte value should start at a position divisible by 8, a 4-byte value at a position divisible by 4, and so on. To guarantee this, PostgreSQL inserts invisible **padding bytes** between columns whenever needed.
1313

1414
Here's an example. Say you create a table like this:
1515

@@ -43,7 +43,7 @@ CREATE TABLE good_order (
4343
[user_id: 8B] [age: 4B] [active: 1B] → 13 bytes of column data
4444
```
4545

46-
Zero padding. Same data, 35% smaller rows. Multiply that across millions of rows and dozens of columns it adds up fast. Optimal column order is free performance: zero runtime cost, just a smarter `CREATE TABLE`.
46+
Zero padding. Same data, 35% smaller rows. Multiply that across millions of rows and dozens of columns and it will adds up fast. Optimal column order is free performance: zero runtime cost, just a smarter `CREATE TABLE`.
4747

4848
### Alignment Groups
4949

@@ -53,7 +53,7 @@ The extension sorts columns into these groups, largest alignment first:
5353
2. **4-byte aligned** (`i`): `integer`, `float4`, `date`, `oid`
5454
3. **2-byte aligned** (`s`): `smallint`
5555
4. **1-byte aligned** (`c`): `boolean`, `char(1)`
56-
5. **Variable-length** (varlena): `text`, `varchar`, `numeric`, `jsonb`, `bytea` always last
56+
5. **Variable-length** (varlena): `text`, `varchar`, `numeric`, `jsonb`, `bytea` - always last
5757

5858
Within each group, `NOT NULL` columns come first (minor CPU optimization for tuple deforming).
5959

@@ -64,7 +64,7 @@ Within each group, `NOT NULL` columns come first (minor CPU optimization for tup
6464

6565
## Installation
6666

67-
Pure SQL/PL/pgSQL no C, no compilation.
67+
Pure SQL/PL/pgSQL - no C, no compilation.
6868

6969
### Self-hosted PostgreSQL
7070

@@ -88,7 +88,7 @@ psql -d your_database -f pg_column_tetris--0.1.0.sql
8888

8989
The extension has three modes (`warn`, `strict`, `off`) that cover different workflows.
9090

91-
### Warn mode (default) catch bad ordering during development
91+
### Warn mode (default) - catch bad ordering during development
9292

9393
The extension installs in `warn` mode. Any `CREATE TABLE` with suboptimal column order emits a NOTICE but still succeeds:
9494

@@ -133,7 +133,7 @@ CREATE TABLE orders ( ... );
133133

134134
Use this in staging/production databases or CI pipelines to guarantee every new table has optimal alignment.
135135

136-
### As an analysis tool audit existing tables
136+
### As an analysis tool - audit existing tables
137137

138138
Use `check()` to inspect any table's current layout and see where padding is wasted:
139139

@@ -172,7 +172,7 @@ SELECT column_tetris.exclude('legacy_imports');
172172
### What gets checked
173173

174174
- **CREATE TABLE** statements are validated by the event trigger
175-
- **ALTER TABLE** is deliberately skipped you can't reorder existing columns, so warning would be noise
175+
- **ALTER TABLE** is deliberately skipped - you can't reorder existing columns, so warning would be noise
176176
- **Temp tables** and **system schemas** (`pg_catalog`, `information_schema`) are skipped
177177
- Tables in the `exclusions` list are skipped
178178

0 commit comments

Comments
 (0)