--- title: "Schema internals and migrations | SurrealDB University" description: "Learn how SurrealDB stores schema metadata, how DEFINE statements shape your database, and how to migrate production data safely." url: https://surrealdb.com/learn/schemas --- ![Course content preview](https://surrealdb.com/assets/static/course-schemas.D4CFbBhP.avif) Course chapters [Back to courses](https://surrealdb.com/learn) [Schema internals and migrations](https://surrealdb.com/learn/schemas) Internals [1: Schemaless vs. schemafull](https://surrealdb.com/learn/schemas/page-01) [2: Schema internals](https://surrealdb.com/learn/schemas/page-02) [3: Migrations](https://surrealdb.com/learn/schemas/page-03) [4: Data types](https://surrealdb.com/learn/schemas/page-04) [5: Automation](https://surrealdb.com/learn/schemas/page-05) Migrations [6: SurrealKit and the first table](https://surrealdb.com/learn/schemas/page-06) [7: Activities and seed data](https://surrealdb.com/learn/schemas/page-07) [8: Computed and asserted fields](https://surrealdb.com/learn/schemas/page-08) [9: Graph dependencies](https://surrealdb.com/learn/schemas/page-09) [10: Sync vs rollouts](https://surrealdb.com/learn/schemas/page-10) [11: Milestones](https://surrealdb.com/learn/schemas/page-11) [12: People and indexes](https://surrealdb.com/learn/schemas/page-12) [13: Events and CI](https://surrealdb.com/learn/schemas/page-13) [14: Capstone](https://surrealdb.com/learn/schemas/page-14) # Schema internals and migrations Welcome to **Schema internals and migrations**, a SurrealDB University course on how schema lives inside the database, how `DEFINE` statements shape it, and how to change the schema of a live database without unpleasant surprises. SurrealDB's philosophy on defined schema is that you can have as little or as much of it as you like. With schemaless as the default, you can run a full database without ever touching a `DEFINE` statement if that is what you want. However, production systems usually end up wanting typed fields, indexes, permissions, and a plan for evolving all of that safely. This course covers what the database stores, how to tighten or loosen constraints, and how to migrate data without taking downtime you did not mean to take. ## What you'll learn By the end you should be able to: - Read `INFO FOR TABLE` / `INFO FOR DB` output, and know how that differs from `INFO … STRUCTURE` - Choose between schemaless and schemafull tables, and use `FLEXIBLE` and union types when full strictness gets in the way - Change field types on live data with backfills, union types, and gradual normalisation - Use field clauses (`DEFAULT`, `VALUE`, `COMPUTED`, `ASSERT`, `REFERENCE`) to keep logic close to the data and cut down on code elsewhere - Decide when hand-written SurrealQL migrations are enough, and when [SurrealKit](https://surrealdb.com/docs/manage/schema-migration) is worth adopting - Grow a [project planning](https://surrealdb.com/docs/learn/schema-management/schema-design/sample-industry-schemas#project-planning) schema from one table to graph relations, `COMPUTED` roll-ups, indexes, and `DEFINE EVENT`, using SurrealKit `sync`, `rollouts`, and `test` along the way ## Course outline | Part | Topic | Focus | | --- | --- | --- | | **1** | Schemaless vs schemafull | Schemaless defaults, `STRICT`, type flexibility, security notes | | **2** | Schema internals | Stored form of `DEFINE`, `INFO` / `STRUCTURE`, SurrealDB Studio Designer | | **3** | Migrations | Backfills, sandbox testing, gradual widen → normalise → tighten, when to use SurrealKit | | **4** | Data types | Literals, records, datetimes, regex, geometry (and geohashes), bytes, objects, arrays and sets | | **5** | Automation | Clauses that assign or validate values, `UPSERT` / `ON DUPLICATE KEY UPDATE`, permissions beside the data, when to reach for `DEFINE EVENT` | | **6** | SurrealKit and the first table | `surrealkit init --minimal`, `database/schema/`, first `project` table, `sync` | | **7** | Activities and seed data | `activity` table, split schema files, `sync --watch`, `database/seed/` | | **8** | Computed and asserted fields | `COMPUTED` duration, `ASSERT` on progress, `VALUE` timestamps | | **9** | Graph dependencies | `RELATION` tables `depends_on` and `activity_of`, graph `COMPUTED` `followed_by` | | **10** | Sync vs rollouts | Disposable `sync` vs shared `rollouts`, manifests, expand → deploy → contract; park `milestone.surql` unapplied | | **11** | Milestones | Preview parked `milestone` with `sync --dry-run`, then apply once with a `rollout` | | **12** | People and indexes | `employee`, `option>`, `REFERENCE`, `DEFINE INDEX` / `UNIQUE` | | **13** | Events and CI | `DEFINE EVENT` lifecycle rules, `surrealkit test` | | **14** | Capstone | Align with the docs [project planning](https://surrealdb.com/docs/learn/schema-management/schema-design/sample-industry-schemas#project-planning) sample, `rollout baseline`, environments | ## The schema used in this course The latter part of this course builds a project planning schema, [one of many](https://surrealdb.com/docs/learn/schema-management/schema-design/sample-industry-schemas#project-planning) sample schemas divided by industry that you can find in the documentation. While a modest size at about 25 lines in length, it nevertheless represents the core of the sort of schema you will see in production. This schema was chosen because it is fairly general but contains a lot of interesting tidbits such as `COMPUTED` fields, assertions, graph links, and closure functions. You can see what the schema looks like below. In the latter half of this course we will be building it up over several files instead of one to demonstrate how SurrealKit is able to combine them all and perform syncs or rollouts every time a change is made. ```surql -- Activities in a project schedule DEFINE TABLE activity SCHEMAFULL; DEFINE FIELD name ON activity TYPE string; DEFINE FIELD description ON activity TYPE option; DEFINE FIELD start ON activity TYPE datetime; DEFINE FIELD end ON activity TYPE datetime; DEFINE FIELD duration ON activity COMPUTED end - start; DEFINE FIELD progress ON activity TYPE float ASSERT $value IN 0.0..=1.0; DEFINE FIELD assigned_to ON activity TYPE option>; DEFINE FIELD followed_by ON activity COMPUTED <-depends_on<-activity; -- Milestones DEFINE TABLE milestone SCHEMAFULL; DEFINE FIELD project ON milestone TYPE record; DEFINE FIELD activities ON milestone TYPE array>; DEFINE FIELD name ON milestone TYPE string; DEFINE FIELD last_updated ON milestone VALUE time::now(); DEFINE FIELD progress ON milestone COMPUTED math::mean(activities.progress); DEFINE FIELD is_complete ON milestone COMPUTED activities.all(|$a| $a.progress > 0.95); -- Graph-style dependency links DEFINE TABLE depends_on SCHEMAFULL TYPE RELATION IN activity OUT activity; DEFINE TABLE activity_of SCHEMAFULL TYPE RELATION IN activity OUT project; ``` ## Before you start You should be comfortable running SurrealQL in the CLI or SurrealDB Studio, and with basic `CREATE` / `SELECT` / `UPDATE`. If any of that sounds unfamiliar, the [Tour of SurrealDB](https://surrealdb.com/learn/tour) and [SurrealDB Fundamentals](https://surrealdb.com/learn/fundamentals) are good places to start first. At a glance **Chapters** 14 **Format** Text, with queries you can run **Runs in** SurrealDB Studio, in the browser **Cost** Free **Then take** [A tour of SurrealDB](https://surrealdb.com/learn/tour) [Start the course](https://surrealdb.com/learn/schemas/page-01) ## Continue ### [SurrealDB University](https://surrealdb.com/learn) All courses ### [1: Schemaless vs. schemafull](https://surrealdb.com/learn/schemas/page-01) Get started THE PLATFORM ## Everything an application and its agents know. Five surfaces, one engine. Database Document, graph, vector, time-series and relational in one engine. ![Five data models as dotted tiles: documents, graph, vector, time-series and relational](https://surrealdb.com/assets/static/platform-database.DUdumYDz.avif) Read more [Database](https://surrealdb.com/surrealdb) Agent Memory What an agent learns, with its source and its time, in the same engine. ![A timeline of remembered facts, each with its source](https://surrealdb.com/assets/static/platform-agent-memory.Cvv8D5Wl.avif) Read more [Agent Memory](https://surrealdb.com/agent-memory) Cloud Managed clusters in the regions you choose, scaled on demand. ![Clusters in three regions on a world map, each running or scaling](https://surrealdb.com/assets/static/platform-cloud.--QZnaVi.avif) Read more [Cloud](https://surrealdb.com/cloud) Studio Query, explore and design the schema from the browser. ![A SurrealQL query in Studio and the schema graph under it](https://surrealdb.com/assets/static/platform-studio.7ykBFNLq.avif) Read more [Studio](https://surrealdb.com/studio) MCP Every model that speaks MCP reaches the database and the memory directly. ![Three models connected through MCP to the database and Agent Memory](https://surrealdb.com/assets/static/platform-mcp.D_oH0_wm.avif) Read more [MCP](https://surrealdb.com/mcp) IN PRODUCTION ## Trusted at scale. Samsung, Nvidia, Verizon, Tencent, and Walmart run on SurrealDB. 14,000+ Developers building on SurrealDB Cloud 4M+ Developers building on SurrealDB worldwide FROM THE TEAMS > SurrealDB gives us a foundation where we can unify semantic search, knowledge graphs, and AI-driven decision making without stitching together multiple systems. Collapsing responsibility into SurrealDB has become our default engineering posture. *Justin Foley* VP of Engineering, Later ```json {"@context":"https://schema.org","@type":"Course","name":"Schema internals and migrations","description":"Learn how SurrealDB stores schema metadata, how DEFINE statements shape your database, and how to migrate production data safely.","url":"https://surrealdb.com/learn/schemas","inLanguage":"en","isAccessibleForFree":true,"provider":{"@type":"Organization","name":"SurrealDB","url":"https://surrealdb.com"},"hasPart":[{"@type":"LearningResource","name":"1: Schemaless vs. schemafull","url":"https://surrealdb.com/learn/schemas/page-01"},{"@type":"LearningResource","name":"2: Schema internals","url":"https://surrealdb.com/learn/schemas/page-02"},{"@type":"LearningResource","name":"3: Migrations","url":"https://surrealdb.com/learn/schemas/page-03"},{"@type":"LearningResource","name":"4: Data types","url":"https://surrealdb.com/learn/schemas/page-04"},{"@type":"LearningResource","name":"5: Automation","url":"https://surrealdb.com/learn/schemas/page-05"},{"@type":"LearningResource","name":"6: SurrealKit and the first table","url":"https://surrealdb.com/learn/schemas/page-06"},{"@type":"LearningResource","name":"7: Activities and seed data","url":"https://surrealdb.com/learn/schemas/page-07"},{"@type":"LearningResource","name":"8: Computed and asserted fields","url":"https://surrealdb.com/learn/schemas/page-08"},{"@type":"LearningResource","name":"9: Graph dependencies","url":"https://surrealdb.com/learn/schemas/page-09"},{"@type":"LearningResource","name":"10: Sync vs rollouts","url":"https://surrealdb.com/learn/schemas/page-10"},{"@type":"LearningResource","name":"11: Milestones","url":"https://surrealdb.com/learn/schemas/page-11"},{"@type":"LearningResource","name":"12: People and indexes","url":"https://surrealdb.com/learn/schemas/page-12"},{"@type":"LearningResource","name":"13: Events and CI","url":"https://surrealdb.com/learn/schemas/page-13"},{"@type":"LearningResource","name":"14: Capstone","url":"https://surrealdb.com/learn/schemas/page-14"}]} ``` ```json {"@context":"https://schema.org","@type":"Organization","@id":"https://surrealdb.com/#organization","name":"SurrealDB","url":"https://surrealdb.com","logo":"https://surrealdb.com/assets/static/logo.BG7_TG2b.svg","description":"SurrealDB is the context and memory layer for AI agents. A multi-model database for documents, graphs, vectors, and time-series.","foundingDate":"2022","legalName":"SurrealDB Ltd","identifier":{"@type":"PropertyValue","propertyID":"GB-COH","value":"13615201"},"address":{"@type":"PostalAddress","streetAddress":"3rd Floor, 1 Ashley Road","addressLocality":"Altrincham","addressRegion":"Cheshire","postalCode":"WA14 2DT","addressCountry":"GB"},"contactPoint":[{"@type":"ContactPoint","contactType":"customer support","email":"support@surrealdb.com","url":"https://surrealdb.com/contact","availableLanguage":"English"},{"@type":"ContactPoint","contactType":"sales","email":"info@surrealdb.com","url":"https://surrealdb.com/contact","availableLanguage":"English"},{"@type":"ContactPoint","contactType":"security","email":"security@surrealdb.com","url":"https://surrealdb.com/.well-known/security.txt","availableLanguage":"English"},{"@type":"ContactPoint","contactType":"legal","email":"legal@surrealdb.com","url":"https://surrealdb.com/legal","availableLanguage":"English"}],"hasCertification":[{"@type":"Certification","name":"SOC 2 Type 2"},{"@type":"Certification","name":"GDPR"},{"@type":"Certification","name":"Cyber Essentials Plus"},{"@type":"Certification","name":"ISO 27001"}],"owns":[{"@type":"SoftwareApplication","name":"SurrealDB","url":"https://surrealdb.com/surrealdb"},{"@type":"SoftwareApplication","name":"Agent Memory","url":"https://surrealdb.com/agent-memory"}],"knowsAbout":["multi-model databases","document databases","graph databases","vector search","time-series databases","SurrealQL","Agent Memory","real-time databases","embedded databases","context layer","graph ontology","distributed database","knowledge graphs","distributed transaction protocols","highly-scalable databases"],"sameAs":["https://www.wikidata.org/wiki/Q124316308","https://github.com/surrealdb/surrealdb","https://twitter.com/surrealdb","https://www.youtube.com/@surrealdb","https://www.linkedin.com/company/surrealdb","https://discord.gg/surrealdb","https://www.reddit.com/r/surrealdb","https://www.instagram.com/surrealdb","https://medium.com/surrealdb","https://dev.to/surrealdb"]} ``` ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://surrealdb.com"},{"@type":"ListItem","position":2,"name":"Learn","item":"https://surrealdb.com/learn"},{"@type":"ListItem","position":3,"name":"Schemas","item":"https://surrealdb.com/learn/schemas"}]} ```