CONV · Conventions

The rules every table follows: how money, phones and dates are stored, what is never deleted, and how the database refuses. Code CONV.

Answered questions

DOC-Q1 (search_path): a new rule, R-CONV-15, below.
DOC-Q5 (which phone columns): R-CONV-07 covers every phone column, the four that V13 left unchecked included. They are listed under the rule.
DOC-Q7 (dates defaulting to the server's day): registered_on, started_on and issued_on are business dates, so R-CONV-10 covers them. Their default is the pool's date, not the server's.
DOC-Q8 (unknown setting name, bad counter period): neither becomes a rule. They catch a caller's mistake, not a business rule, so their refusals stay under R-CONV-13.

Status: planned
Example: given a rent charge of Rp 150.000, when it is saved, then amount holds 150000 as a bigint, and a money column declared as numeric, real or double precision is a defect.
Refusal: none: a fraction can't be stored in a bigint column.
Who: every writer.
Source: [Ref] Database rules and conventions, Money.

Status: planned
Example: given a pricing group, when its admin_fee is saved as -50000, then the row is refused. The same holds for rates, costs, fees, shares and totals.
Refusal: none: check_violation (23514).
Who: every writer.
Source: [Ref] Data model V13, the ≥ 0 checks on money columns.

Status: planned
Example: given an insurance policy starting on 2026-11-01, when ends_on is saved as 2026-10-31, then the row is refused. The same holds for rentals, maintenance records and payouts.
Refusal: none: check_violation (23514).
Who: every writer.
Source: [Ref] Data model V13: rentals, insurance_policies, maintenance_records, payouts.

Status: planned
Example: given a charge dated 2026-10-07, when its due_date is saved as 2026-10-06, then the row is refused. The same holds for a debt letter's due_on against its issued_on.
Refusal: none: check_violation (23514).
Who: every writer.
Source: [Ref] Data model V13: charges, debt_letters.

Status: planned
Example: given an inspection, when fuel_level is saved as 120, then the row is refused.
Refusal: none: check_violation (23514).
Who: every writer.
Source: [Ref] Data model V13: inspections.

Status: planned
Example: given a car, when odometer_km is saved as -10, then the row is refused. The same holds for inspections and maintenance records.
Refusal: none: check_violation (23514).
Who: every writer.
Source: [Ref] Data model V13: vehicles, inspections, maintenance_records.

Status: planned
Example: given a garage, when its phone is saved as 0812-3456-7890, then the row is refused; +6281234567890 is accepted.
Refusal: none: check_violation (23514).
Who: every writer. The data phase normalizes v1's numbers before they are loaded.
Source: [Ref] Database rules and conventions, Normalized input. The columns: drivers.phone, driver_emergency_contacts.phone, queue_tickets.phone, profiles.phone, rental_companies.contact_phone, garages.phone and insurers.phone. V13 checked only the first three; the other four are added (DOC-Q5). Any phone column added later follows the rule.

Status: planned
Example: given any table whose rows can be updated, when its columns are listed, then created_at and updated_at are both there, as timestamptz.
Refusal: none: this describes the schema.
Who: every table. Append-only tables (GPS positions, events, the audit log) carry their own time column instead.
Source: D9 (P14).

Status: planned
Example: given a driver updated at 10:00, when a client updates the row at 10:05 and sends updated_at = 2020-01-01, then updated_at reads 10:05.
Refusal: none: the value is overwritten, not refused.
Who: every writer.
Source: D9 (P14); [Ref] Database rules and conventions, Timestamps.

Status: planned
Example: given a pool in Asia/Makassar (WITA), when a charge is raised at 23:30 WITA on 7 October, which is 15:30 UTC, then its charge_date is 2026-10-07, and at 00:30 WITA on 8 October it is 2026-10-08.
Refusal: none.
Who: every writer; app.pool_today(pool) gives the date.
Source: D9 (P11). Also covered (DOC-Q7): drivers.registered_on (the driver's pool), maintenance_records.started_on (the car's home pool) and debt_letters.issued_on (the driver's pool). In V13 they default to the server's date, which is UTC on Supabase; they default to the pool's date instead.

Status: planned
Example: given a car with a rental, when someone deletes the car, then the delete is refused. Photos, items and other pure children go with their parent.
Refusal: none: foreign_key_violation (23503).
Who: every writer.
Source: D9 (P13); [Ref] Database rules and conventions, No hard deletes.

Status: planned
Example: given rentals.vehicle_id points at vehicles, when the indexes on rentals are listed, then one starts with vehicle_id.
Refusal: none: this describes the schema.
Who: every table.
Source: [Ref] Database rules and conventions, Indexes.

Status: planned
Example: given a car at pool PML and a driver at another pool, when the rental is booked, then the error message is exactly rental.cross_pool. A key that isn't registered raises internal.unknown_error_key instead.
Refusal: internal.unknown_error_key, when a function tries to raise an unregistered key.
Who: every database function and trigger. Argument checks that catch a caller's mistake (settings.unknown_key, settings.pool_not_found, document.bad_period, document.wrong_organization, vehicle.not_found, driver.not_found, profile.not_found) follow this rule and have no rule of their own (DOC-Q8).
Source: D10.

Status: planned
Example: given an allocation of Rp 200.000 against a charge with Rp 150.000 open, when it is saved, then the detail is {"charge_id": "…", "balance": 150000, "amount": 200000}.
Refusal: none: this describes every refusal.
Who: every database function and trigger.
Source: D10.

Status: planned
Example: given app.set_vehicle_status, which is security definer, when its definition is read, then it sets search_path to a fixed list, so a caller's own schema can't swap a table or function it uses.
Refusal: none: this describes the schema.
Who: every security definer function.
Source: D3 (rules run in security definer functions); Supabase's database linter, lint 0011 function_search_path_mutable. Added for DOC-Q1.