In the previous lesson we settled Escena Viva's data model and left the src/repositories/ boundary ready. Now we go down into the code: we will connect the application to MongoDB, write the connection module that plugs into the graceful shutdown in src/server.js, and translate the diagram from lesson 07-01 into Mongoose schemas and models in src/models/.

This lesson does not write queries yet — that is 07-03. It writes the structure: what shape the documents have, what rules they enforce, what derived fields they expose and what indexes hold them up.

1. What MongoDB is: documents, collections and ObjectId
2. What Mongoose is and whether it is worth it
3. Connection, startup and graceful shutdown
4. The Event schema with embedded sessions
5. Schema types and options
6. Order, Ticket and a minimal User
7. Schema validators versus zod validation
8. _id versus business identifiers
9. Methods, statics and virtuals
10. Schema middleware and toJSON
11. Declared indexes

MongoDB stores documents in collections. A document is a structure much like a JavaScript object, with nested fields and arrays. A collection is the loose equivalent of a table: a container that does not demand that all its documents have the same shape.

The internal format is BSON (Binary JSON): a binary encoding that adds types JSON does not have and that we care about.

Every document has an _id that is unique within its collection. If you do not supply one, MongoDB generates an ObjectId: 12 bytes combining a timestamp, a machine/process identifier and a counter. Two practical consequences: they are unique without central coordination, and they are roughly sortable by creation date, because the first 4 bytes are the instant in seconds.

In text it looks like 507f1f77bcf86cd799439011: 24 hexadecimal characters. Watch out for this, because passing a string that does not have that shape to a query by _id produces a CastError, and that error has to be translated into a 400 rather than being allowed to turn into a 500.

Mongoose is an ODM: it sits on top of the official mongodb driver and adds a schema (the expected shape of your documents), validation before writing, automatic typing and casting, and model functionality: pre/post hooks, methods, virtuals and populate.

Is it worth it compared with the native driver? The honest answer: it depends on how much discipline you can guarantee unaided. With the native driver you write exactly the query that runs and there are no performance surprises, but every required field, every default value and every type conversion is your own code, repeated at every write site. Mongoose centralizes that and makes a malformed document hard to create by accident. The cost is a layer of indirection: you have to know that find() returns a lazy Query, that lean() changes what you get back and that a pre('save') does not fire on an updateOne. For a domain with invariants like ours the scales tip towards Mongoose; for an ingestion script handling a million documents, I would drop down to the native driver without a second thought.

You install it with npm install mongoose; it bundles the mongodb driver as a dependency, so there is no need to install that separately.

The URL comes in through the only place authorized to read process.env: src/config/index.js.

Validating at startup is deliberate: if the URL is wrong we want to find out when the process launches, not on a client's first request.

Three details that are not decoration. serverSelectionTimeoutMS: without it, a wrong URL leaves startup hanging with no explanation. The pool: Mongoose does not open one connection per query, it keeps a set of sockets; if maxPoolSize were 1, you would serialize the entire application. The events: after a disconnected the driver retries automatically and queues the pending operations; you do not need to write reconnection logic, but you do need to log the event so you are not blind during an outage.

createApplication() remains a pure factory that never touches the network. The connection belongs to the process, and the process is governed by src/server.js:

The order matters and it is symmetric. On startup: database first, HTTP second, so no request ever reaches an application without data. On shutdown: HTTP first, database second, because closing the connection with requests in flight would produce errors in purchases already under way. The connection is a process-level resource with the same life cycle as the process itself.

The schema reproduces field by field what we already knew from the domain: evt-001 "Concierto de Otono" at Teatro Almendra, with org-almendra and sessions ses-001-1 and ses-001-2. Nothing new is invented; what already existed is persisted. And { timestamps: true } adds automatic createdAt and updatedAt: the beginning of the history we were missing in the JSON file.

The unique row deserves emphasis: unique: true validates nothing in Mongoose. It asks MongoDB to create a unique index, and the one that rejects the duplicate is the engine, with an E11000 error at write time, not a ValidationError. In the next lesson we will translate it into a 409.

That comment in User is not an oversight: it is a decision. The user exists so orders can reference it and so roles are already modeled, but we are not implementing authentication. Storing passwords badly is worse than not storing them at all.

In Module 6 we put zod at the edge, with createOrderSchema and the validate middleware that leaves the result in req.validatedData. Now Mongoose schema validation shows up. Isn't that duplicated work? No: they are different layers, with different clients.

The rule in one sentence: zod validates what comes in through the door; Mongoose validates what goes out to disk. A nightly import script does not go through Express and therefore does not go through zod; if the schema did not validate, it could leave sold: 9999 on a session with a capacity of 300. And zod can reject things Mongoose does not care about (an extra field, an unknown channel) before spending a round trip to the database. Above both of them sits the domain: Session.sell() keeps its invariant in memory. Three layers, three moments, none of them redundant.

Our documents have two identifiers. The _id is technical: unique, generated without coordination, efficient as an index key and the target of the references populate uses. The business identifier (evt-001, ses-001-1, EV-2026-000431) is semantic: it appears in URLs, emails, printed tickets, the CSV files of Module 3 and the zod schemas of Module 6; and it is stable across migrations, because if tomorrow we move the data to PostgreSQL the _ids disappear but evt-001 is still evt-001. Using _id in public URLs ties you to the engine and leaks internal information; using only the business one as _id is defensible, but you lose the implicit chronological ordering. Keeping both, with a unique index on the business one, is what systems expecting to live for years normally do.

Virtuals reproduce the rich domain getters from Module 2: computed fields that are not stored.

Two warnings. Virtuals do not exist in the database: you cannot filter or sort by occupancy, because MongoDB does not know it exists; for that you need an aggregation (lesson 07-04) or a denormalized stored field. And lean() removes them: if you ask for plain objects for performance, you lose virtuals and methods.

On function versus arrow: in methods, virtuals and hooks you must use function, because Mongoose binds this to the document. An arrow captures the module's lexical this and will leave you with undefined. It is the number-one mistake of newcomers.

Responsible use of hooks means three things:

1. No external side effects. Sending an email or calling an API inside a pre('save') couples persistence to a remote service: a network failure would stop the save. That belongs outside, or in the SalesManager we already have.
2. Remember which hooks fire. pre('save') does not run on updateOne, findOneAndUpdate or deleteMany, because those operations happen on the server without materializing the document. If the logic is non-negotiable, put it in the schema or in the repository. And keep them fast: a slow hook is paid for on every write.

__v is Mongoose's internal version counter: it adds nothing for an HTTP client and only raises questions. And exposing a raw _id couples your public contract to the engine. This transformation is the boundary between "how I store" and "what I publish", the same separation the repositories were defending.

An index speeds up reads and makes writes more expensive. They are declared per expected query, not on a whim:

In development Mongoose creates these indexes at startup (autoIndex). In production it must be turned off (mongoose.set('autoIndex', false)) and they must be created in the corresponding migration: building an index over millions of documents during startup can block the application for several minutes. We come back to this in lesson 07-06.

• Arrow functions in methods, virtuals or hooks. this stops being the document and everything returns undefined.
• Believing unique: true validates. It is an index; the error arrives as E11000, not as a ValidationError.
• Calling mongoose.connect on every request. The connection belongs to the process and it is pooled; connecting per request exhausts the system's sockets.
• Logging the connection URL. If it carries credentials, you have just leaked them. Log connection.name instead.
• Defining the same model twice. mongoose.model('Event', ...) in two files throws OverwriteModelError.
• Tip: start with generous required and enum declarations — relaxing a schema is cheaper than cleaning up incoherent data — and always keep money as an integer number of cents.

Write src/models/venue.js with venueId (unique, in the venue-xxx format), name, city, maxCapacity (integer ≥ 1) and active (boolean, true by default). Add a label virtual returning "<name> (<city>)", a findActive() static, timestamps and the toJSON transformation.

Add a validator to Ticket that prevents setting usedAt to a date when the status is cancelled. Explain why it would not fire with findByIdAndUpdate without options.

Decide the index and the order of its fields for: (a) a user's paid orders sorted by date descending; (b) the valid tickets of a session; (c) an organizer's events in published status.

Exercise 1.

Exercise 2.

It does not fire because updates run on the server without building the document: Mongoose only validates if you pass { runValidators: true }, and even then this is the query, not the document, so a validator depending on other fields may have no access to them.

Exercise 3. (a) { userId: 1, status: 1, createdAt: -1 }. (b) { sessionId: 1, status: 1 }. (c) { organizerId: 1, status: 1 }. The rule is called ESR: equality-compared fields first (Equality), then the sort field (Sort) and finally the range ones (Range).

Escena Viva now has real persistence. You know what MongoDB stores and how, what Mongoose adds on top and at what price, and how to open the connection from validated configuration and wire it into startup and graceful shutdown. You have translated the previous lesson's diagram into four models — Event with its embedded sessions, Order, Ticket and a passwordless User waiting for Module 8 — with their types, validators, virtuals, middleware, a clean toJSON and reasoned indexes. And you have seen why three validation layers coexist without getting in each other's way: zod at the edge, the schema before the disk and the domain in memory.

In the next lesson we start moving data: the four CRUD operations with their traps — lazy Query objects, lean(), pagination, runValidators, $inc, soft deletes — the translation of Mongoose errors into our Module 6 hierarchy, and the moment we have been waiting for: retiring src/catalog-data.js and replacing it with src/repositories/events.js without the controllers noticing.