El projecte està fet: l'esquema es crea, les dades carreguen, les quinze consultes retornen el que han de retornar i els índexs estan justificats. I tot i així falta la meitat de la feina, perquè hi ha una cosa que gairebé ningú no ensenya i que decideix com es valora tot l'anterior: explicar-ho. Un model excel·lent mal explicat es corregeix com un model mediocre; un número correcte presentat sense la seva definició es llegeix com un número equivocat; i un repositori que ningú no aconsegueix executar en cinc minuts és, a efectes pràctics, un repositori buit.

Aquesta lliçó és aquesta meitat: l'informe apartat per apartat, com es presenten resultats de dades sense enganyar de bona fe, les preguntes de la defensa i com preparar-les, com es publica el projecte perquè algú el pugui executar, i l'autoavaluació amb la rúbrica de 12-02 convertida en checklist. I després, el tancament de tot el curs.

1. L'informe: 04-informe.md
2. Com presentar resultats de dades
3. La defensa: les preguntes que et faran
4. Publicar el projecte
5. Autoavaluació: la rúbrica com a checklist
6. Errors habituals i consells
7. Exercicis
8. Conclusió del curs

L'informe no és documentació tècnica —per a això hi ha els comentaris del DDL— ni un diari del que vas fer. És un document que respon a tres preguntes: què has construït, per què així i què saps que encara no està bé. Entre 4 i 8 pàgines; més que això no es llegeix, i menys que això sol significar que no hi ha decisions explicades.

• Escriu en present i en primera persona del plural o impersonal: "el préstec penja d'exemplars perquè…", no "vaig decidir que…" ni "s'hauria pogut fer…". Ferm, sense arrogància.
• Una decisió, un paràgraf, un perquè. El patró que funciona és sempre el mateix: què vaig fer · quina alternativa hi havia · per què aquesta · què em costa. Aquest quart element —el preu que pagues— és el que distingeix algú que ha decidit d'algú que ha encertat per casualitat.
• Res d'adjectius sense dada. "El rendiment és excel·lent" no diu res; "la consulta de vençuts passa de 340 ms a 4 ms amb l'índex parcial, sobre 50.000 préstecs" sí.
• Ni una captura de pantalla de codi. Blocs de text, que es copien, es busquen i es llegeixen en qualsevol pantalla.

El diagrama ER no parla sol. Un lector que veu dotze caixes i setze fletxes no entén res si no li dius per on ha de començar. La seqüència que funciona, i cap en un paràgraf sota el diagrama:

1. La columna vertebral primer. "El sistema gira sobre prestecs: una fila per exemplar prestat a un soci." Una frase, i el lector ja sap on mirar.
2. El gir, amb un exemple concret. "obres desa el títol; exemplars, cada volum físic. D'El jardí de les hores n'hi ha tres exemplars en dues seus." Un exemple amb noms propis val més que tres paràgrafs de teoria.
3. Les dues relacions que cal mirar dues vegades. La N:M obres_autors i la reflexiva de bibliotecaris.
4. Les taules satèl·lit en una línia cadascuna. multes, reserves, materies, editorials: no necessiten més.

I una decisió de format: el diagrama va com a imatge, no com a codi. Exporta el mermaid a PNG o SVG i deixa'l a informe/model-er.png. Qui llegeixi l'informe en qualsevol visor de Markdown el veurà; qui llegeixi el codi font, també.

Quatre elements, sempre en el mateix ordre, i una sola consulta per pàgina:

La pregunta — quins exemplars porten més temps fora de termini, i de qui són?

La definició — préstec vençut = sense data_devolucio i amb data_prevista anterior a avui. La multa encara no existeix (RN-10): la columna és una estimació.

La consulta i el seu resultat — la vista v_prestecs_vencuts, amb les tres files: 36 dies i 7,20 € de la Lena Fuentes, i dos préstecs d'un dia.

La lectura — tres préstecs vençuts sobre sis actius és una taxa alta, però dos dels tres s'han passat un sol dia: el problema real és un, i porta més d'un mes.

Aquest quart element és el que gairebé ningú no escriu i l'únic que interessa a qui decideix. Una taula sense lectura obliga el lector a fer la teva feina; i si la fa, en traurà la seva pròpia conclusió, que pot no ser la correcta.

Reconèixer els límits no resta, suma, perquè demostra que entens el sistema millor que qui es pensa que l'ha tancat. Per a aquest projecte, cinc limitacions honestes i ben triades:

1. L'índex parcial impedeix dos préstecs actius, no dos préstecs històrics solapats; la solució seria EXCLUDE amb btree_gist (12-04).
2. L'estat del soci (bloquejat) es manté fora de la base: res no garanteix que es correspongui amb el seu deute real. Seria una tasca programada nocturna o un disparador sobre multes.
3. No hi ha auditoria: si algú canvia una data_devolucio a mà, no en queda rastre.
4. La cua de reserves no contempla prioritats, només FIFO pur, i la caducitat de 3 dies no s'aplica sola.
5. El sistema és d'una xarxa, no multiinstitució: no hi ha préstec interbibliotecari ni taula d'organitzacions.

Tot això és 11-04 aplicat al teu propi informe, i és el que separa una taula d'un argument.

Defineix la mètrica abans d'ensenyar-la, sempre. No hi ha excepcions. En aquest projecte hi ha tres parells de definicions que es confonen amb facilitat i que cal fixar per escrit:

Taula o gràfic. La regla pràctica: taula quan el lector llegirà valors concrets o són menys d'una desena de files; gràfic quan el que importa és la forma —una tendència, una comparació de magnituds, una distribució—. La sèrie mensual de RC-12 demana gràfic; el pivot seu × matèria de RC-15, amb les seves tres files, demana taula. I el pivot mai un gràfic de formatget amb sis porcions, que és la manera més eficaç que ningú no compari res.

Tot número necessita el seu denominador. "6 multes" no significa res; "6 multes sobre 30 préstecs retornats, un 20,0 %" sí. I al revés: un percentatge sense la xifra absoluta és igual de trampós. La regla del projecte, que surt directament d'11-04: si el denominador baixa d'unes desenes, publica el número absolut i no el percentatge. Dir que la Biblioteca Infantil té "un 100 % de préstecs infantils" és cert i és soroll: són 6 préstecs.

Arrodoniment i unitats. Arrodoneix només en presentar, mai als passos intermedis. Els diners, a dos decimals i amb el símbol (7,20 €); els dies, enters; les mitjanes, a un decimal (32,3 dies) perquè el segon decimal és falsa precisió amb 36 files. I la unitat a la capçalera de la columna, no repetida a cada cel·la.

Honestedat sobre la mida de la mostra. Aquest projecte té 36 préstecs. Qualsevol frase del tipus "la matèria més llegida és Narrativa" ha d'anar amb el seu "amb 12 de 36 préstecs" al costat. I hi ha dos resultats que l'informe ha de presentar amb el seu avís: el "tercer soci més lector" de la Biblioteca Infantil té zero préstecs perquè aquella seu només té tres socis (RC-13), i la mitjana de dies per matèria es calcula sobre 6 o 8 préstecs, no sobre milers. Escriure-ho no et fa semblar insegur: et fa semblar algú de qui fiar-se.

I la xifra de control, sempre visible. Cada taula de l'informe hauria de poder quadrar-se amb un total conegut. Les d'aquest projecte: 36 préstecs, 20 exemplars, 12 obres, 27,20 € en multes. Si un desglossament no suma això, el desglossament està malament — i si el lector pot comprovar-ho d'un cop d'ull, es fia de la resta.

Tant se val que sigui un tribunal, una revisió amb el teu equip o una entrevista de feina amb el projecte damunt de la taula: les preguntes són gairebé sempre les mateixes sis. Prepara-les per escrit, en dues o tres frases cadascuna.

Tres consells de preparació que valen més que assajar el discurs:

• Tingues l'EXPLAIN a mà, en un fitxer, juntament amb l'abans i el després. És la resposta a mitja dotzena de preguntes i no es pot improvisar.
• Tingues la base carregada i psql obert. Si algú pregunta "i quants socis tenen deute?", respondre-ho executant val deu vegades més que respondre-ho de memòria.
• Prepara el resum de dos minuts. Domini, gir central (obra/exemplar), el que més et va costar i una limitació coneguda. És el que diràs a l'ascensor, a l'entrevista i a la primera frase de la defensa.

Un projecte que no es pot executar no existeix. El llistó és concret: algú que no l'ha vist mai l'ha de tenir funcionant en cinc minuts.

Cinc apartats i ni un més: què és (dues línies), requisits (PostgreSQL 16), com executar-ho (les ordres, copiables), què esperar (la taula de recomptes, perquè sàpiga si ha anat bé) i on és l'informe.

Aquesta última línia és el detall que distingeix un README bo d'un de correcte: diu al lector com saber que ha funcionat. Sense ella, executa els tres fitxers, no veu errors i es queda sense saber si la càrrega està completa.

01-esquema.sql és idempotent perquè esborra i recrea: perfecte per a un lliurable, impossible en producció, on esborrar les taules és esborrar les dades. Un apartat de l'informe que digui "per a producció, això es convertiria en migracions versionades amb Flyway o Liquibase, i el canvi de l'índex de títol seria un CREATE INDEX CONCURRENTLY per no bloquejar la taula" demostra que saps la diferència (05-06, 11-05). Afegir dos fitxers de migració d'exemple costa deu minuts i es nota.

• Credencials. Ni al README, ni en un .env, ni en un comentari, ni "temporalment". Git recorda: una contrasenya pujada i esborrada després continua sent a l'historial. Fes servir un .env.example amb valors falsos i un .gitignore que exclogui el .env real.
• Dades personals reals. Ni de clients, ni de companys, ni teves. Les del projecte són inventades i els correus van a @example.com, que és un domini reservat justament per a això (RS-07).
• Bolcats de producció. Un pg_dump d'una base real en un repositori és una fuita de dades, no un fitxer de proves.
• Fitxers de 200 MB. Si necessites volum, puja el generador (generate_series), no les dades generades.

La rúbrica de 12-02, convertida en preguntes de sí o no. Respon-les abans de lliurar, amb el projecte al davant i sent dur amb tu mateix.

Model (25 %)

• [ ] obres i exemplars són dues taules, i prestecs penja d'exemplars?
• [ ] reserves penja d'obres, no d'exemplars?
• [ ] La N:M obres_autors té PK composta i dades pròpies (rol, ordre)?
• [ ] bibliotecaris té la seva FK reflexiva, nul·lable només a la direcció?
• [ ] Cada desnormalització està escrita i justificada a l'informe?

Integritat (20 %)

• [ ] Estan declarades les 14 RI, amb nom i anotades amb el seu número?
• [ ] RI-03 està resolta a la base amb l'índex únic parcial?
• [ ] Has executat els INSERT que han de fallar, i fallen?
• [ ] Cada ON DELETE és coherent amb la semàntica de la seva relació?

Consultes (25 %)

• [ ] Les quinze s'executen sense ni un error?
• [ ] Cap no perd files per un JOIN mal triat ni les duplica?
• [ ] Tots els rànquings tenen desempat explícit?
• [ ] Cada mètrica porta la seva definició en un comentari?
• [ ] Has validat almenys dos totals per dos camins?

Rendiment (10 %) · Seguretat (10 %) · Lliurament (10 %)

• [ ] Cada índex té una consulta concreta que el fa servir, i has escrit el que decideixes no indexar?
• [ ] Hi ha dos EXPLAIN abans/després amb volum suficient perquè signifiquin alguna cosa?
• [ ] Els tres rols existeixen, cap no té DELETE sobre l'històric i ho demostres amb has_table_privilege?
• [ ] Totes les dades personals són fictícies i les baixes són lògiques?
• [ ] Els quatre fitxers s'executen en ordre sobre una base buida, dues vegades seguides?
• [ ] L'informe té els set apartats, inclòs el de limitacions?

Si respons que no a alguna, arregla-la abans de lliurar. Cap d'aquestes caselles costa més de mitja hora, i cadascuna val més que reescriure una consulta que ja funcionava.

• Escriure l'informe l'última nit. Les decisions es justifiquen molt millor el dia que es prenen. Un fitxer decisions.md obert des del primer dia es converteix sol en l'apartat 3.
• Explicar el procés en lloc del resultat. A ningú no li interessa que primer posessis una taula llibres i després la dividissis. Interessa el model final i per què. El procés només apareix si explica una decisió.
• Ensenyar les quinze consultes a l'informe. Són a 03-consultes.sql. A l'informe n'hi van tres o quatre, triades, amb el seu resultat i la seva lectura.
• Publicar un percentatge sobre 6 casos. Amb aquests volums, gairebé tot percentatge menteix. Xifra absoluta i denominador.
• Dir "res" quan et pregunten què faries diferent. És la resposta que pitjor cau: significa que no has mirat la teva feina amb distància. Tingues-ne dues de preparades.
• Un README que comença per l'arquitectura. Comença per com s'executa. L'arquitectura la llegeix qui ja ho té funcionant.
• Consell: demana a algú que l'executi davant teu sense ajudar-lo. En deu minuts sabràs què falta al README, i no hi ha manera més barata d'esbrinar-ho.
• Consell: llegeix l'informe en veu alta. Les frases que no pots llegir sense entrebancar-te són les que ningú no entendrà.
• Consell: desa una versió del projecte tal com el vas lliurar. D'aquí a un any el voldràs ensenyar, i voldràs que sigui el que vas defensar, no un que vas tocar després.

Escriu l'apartat 3 de l'informe (decisions de disseny) complet: entre sis i vuit decisions, cadascuna amb la seva alternativa descartada, el motiu i el preu que pagues. Hi ha d'incloure obligatòriament la separació obra/exemplar, data_prevista, l'índex parcial i la cua de reserves.

Prepara la defensa de dos minuts: escriu-la, cronometra-la i retalla-la fins que hi càpiga. Ha de contenir el domini, el gir central del model, la decisió tècnica de la qual estiguis més orgullós, una xifra concreta i una limitació coneguda.

Un company escriu al seu informe: "La Biblioteca Central és clarament la més eficient de la xarxa: concentra el 55,6 % dels préstecs." (1) És certa la dada? (2) Dona tres raons per les quals la conclusió no se sosté. (3) Què escriuries al seu lloc?

Solució 1 — No hi ha una resposta única, però sí una plantilla que es corregeix bé, quatre elements per decisió. Exemple, perquè vegis el nivell de detall esperat:

exemplars com a taula pròpia. Alternativa descartada: una columna num_exemplars a obres, com l'stock d'un catàleg comercial. Per què: l'exemplar té seu pròpia, estat físic propi i història pròpia, i sense fila pròpia seria impossible saber quin dels tres va tornar; el préstec deixaria de poder apuntar a un objecte concret. Què em costa: una taula més, un JOIN més a gairebé totes les consultes del catàleg, i que "quants llibres hi ha" passi a tenir dues respostes legítimes —12 obres i 20 exemplars— que cal distingir a cada informe.

I els senyals que l'apartat està mal escrit: decisions sense alternativa ("vaig fer servir claus subrogades"), alternatives de palla (comparar la teva solució amb una d'absurda), i cap menció al preu. Tota decisió de disseny té un cost; si no el trobes, és que no has decidit res.

Solució 2 — L'estructura que cap en dos minuts, amb els temps:

L'error típic és gastar 90 segons en la llista de taules. Ningú no recorda una llista de taules; tothom recorda "tres exemplars en dues seus".

Solució 3 — (1) La dada és certa: 20 de 36 préstecs són de la Central, que és el 55,6 %. L'aritmètica està bé. (2) La conclusió no se sosté per tres motius. (a) "Eficiència" no és "volum". La Central té 10 dels 20 exemplars i 7 dels 15 socis; amb la meitat del fons fer el 56 % dels préstecs és gairebé exactament l'esperat. Una mètrica d'eficiència seria préstecs per exemplar —2,0 a la Central enfront de 2,0 a la Infantil, que amb 3 exemplars va fer 6 préstecs—, i llavors la conclusió desapareix. (b) Les seus no són comparables: la Infantil va obrir el 2024 i les altres el 2018 i el 2021, i el seu públic i el seu fons són d'una altra naturalesa. (c) La mida de mostra: 36 préstecs en total i 6 a la Infantil; un sol préstec mou diversos punts percentuals.

(3) Alguna cosa així: "La Central concentra 20 dels 36 préstecs (55,6 %), en línia amb el seu pes al fons: custodia 10 dels 20 exemplars. Normalitzat per exemplar, les tres seus rendeixen de manera semblant (2,0 · 1,4 · 2,0 préstecs per exemplar), sobre volums massa petits per afirmar diferències." Menys rotund i molt més útil — que és, gairebé sempre, la diferència entre una anàlisi i un titular.

Aquí s'acaba, així que convé mirar enrere abans de tancar.

Vas començar sense saber què era una taula i acabes de dissenyar un sistema sencer. Aquest és el recorregut:

• Mòduls 1 i 2 — els fonaments. Què és SQL i quin lloc ocupa, PostgreSQL instal·lat, els tipus de dades, el model relacional amb les seves claus i la seva normalització, i BotigaVerda carregada. Després, SELECT: columnes, àlies, WHERE, DISTINCT, ORDER BY i la paginació amb LIMIT i amb keyset.
• Mòduls 3 i 4 — combinar i resumir. Els JOIN en totes les seves formes, el LEFT JOIN i l'anti-join que troben el que no hi és, el self join sobre relacions reflexives i els operadors de conjunts. I el filtratge fi —LIKE, IN, BETWEEN, la lògica de tres valors dels NULL— amb l'agregació, el GROUP BY i el HAVING.
• Mòduls 5 i 6 — escriure i transformar. CREATE TABLE amb les seves sis restriccions, INSERT, UPDATE, DELETE i l'esborrat lògic, l'upsert i les migracions amb ALTER TABLE. I les funcions: cadenes, números, dates, CAST, COALESCE, CASE i el pivot.
• Mòduls 7 i 8 — profunditat i velocitat. Subconsultes escalars, correlacionades, EXISTS, derivades i LATERAL, amb el criteri per triar entre JOIN, subconsulta i CTE. I els índexs: com funciona un B-tree, quins crear i quins no, i EXPLAIN per deixar d'endevinar.
• Mòduls 9 i 10 — fiabilitat i potència. Transaccions, ACID, MVCC, SAVEPOINT, nivells d'aïllament, bloqueigs i SKIP LOCKED. I les eines grans: vistes i materialitzades, CTE i recursives, funcions de finestra, procediments, disparadors i JSON.
• Mòdul 11 — l'ofici. Els casos d'ús que reapareixen sempre, les bones pràctiques i els seus antipatrons, la seguretat amb la injecció SQL i el model de rols, l'anàlisi de dades on definir importa més que consultar, i el SQL real d'una aplicació web amb el seu pool, el seu ORM i el seu N+1.
• Mòdul 12 — fer-ho tu. Un domini nou, un encàrrec amb les imprecisions d'un encàrrec real, i d'aquí a un sistema complet: dotze taules, catorze restriccions declarades, quinze consultes, set índexs justificats, tres rols i un informe.

Què saps fer ara que no sabies en començar. No és "escriure consultes": això és la part fàcil. És això:

• Llegir un enunciat de negoci i treure'n un model, distingint entitats d'atributs i detectant quan una mateixa paraula significa dues coses.
• Fer que la base de dades defensi les seves pròpies regles, en lloc de confiar que tothom se'n recordi, de validar.
• Escriure una consulta i saber si està bé, comprovant recomptes i validant totals per dos camins.
• Saber per què una consulta és lenta i quin índex l'arregla, amb un pla d'execució al davant en lloc d'una intuïció.
• Decidir què es desa i què es calcula, què s'encapsula i què no, i defensar cada decisió amb la seva alternativa i el seu preu.
• Presentar un resultat sense enganyar de bona fe: amb la seva definició, el seu denominador i la seva mida de mostra.

Cap on continuar. Cap d'aquests camins no és obligatori, i tots comencen on aquest curs acaba:

I la lectura, curta i ben triada: la documentació oficial de PostgreSQL, que és de les millors que existeixen i es llegeix sorprenentment bé; SQL Performance Explained, de Markus Winand, per a índexs i plans; Designing Data-Intensive Applications, de Martin Kleppmann, per entendre què hi ha sota tot això; i The Art of PostgreSQL, de Dimitri Fontaine, per continuar escrivint millor SQL.

Queda una última cosa, i és la que de debò marca la diferència: fer-lo servir. El SQL que s'aprèn i no es practica s'oblida en sis mesos, i el que es fa servir s'esmola sol. Agafa el projecte que acabes de fer i estira'l —afegeix-hi el préstec interbibliotecari, l'auditoria, les notificacions—; ofereix-te a escriure l'informe que al teu equip treu algú a mà cada mes; obre la consola de la base de dades que ja fas servir i pregunta-li alguna cosa que ningú no li hagi preguntat.

Dotze mòduls després, la frase amb què va començar el curs torna amb un altre sentit: SQL és el llenguatge amb què es parla amb les dades. Ja el parles. El que hi diguis depèn de tu.