From c43c8bbe3adbf734c915daba983a8c5a62414510 Mon Sep 17 00:00:00 2001 From: dhruv92 Date: Thu, 23 Jan 2025 16:24:09 -0800 Subject: [PATCH 1/4] feat: initial stab --- builder/databases-v2.mdx | 272 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 272 insertions(+) create mode 100644 builder/databases-v2.mdx diff --git a/builder/databases-v2.mdx b/builder/databases-v2.mdx new file mode 100644 index 0000000..be7d082 --- /dev/null +++ b/builder/databases-v2.mdx @@ -0,0 +1,272 @@ +--- +title: "Databases" +description: "Store and manage data in your apps" +hidden: true +--- + + + + + +## Overview + +Databases let you store and manage information in your apps. Every Create project comes with a free database built in. + +As you chat with Create, it handles all the technical details - from designing your database structure to writing the code to save and retrieve data from it in your app. + +Use databases to: + +* Save user submissions (forms, feedback, uploads) +* Store content (blog posts, products, galleries) +* Persist data between uses of the app +* Build dynamic data-driven features + + +Start simple! You can always expand your database as your needs grow. Create handles updating the structure automatically from your descriptions. + + +## Chat + +Create automatically updates your database structure & the code to save and retrieve data from it as you chat. + +When a feature requires storing data, it: + +1. **Designs the database structure** based on your description +2. **Makes Functions** to save and retrieve data from the database +3. **Designs the Pages and Components** to display and interact with the data +4. **Connects everything**. It makes sure the Pages and Components use the Functions when it needs data. + +For example, if you say "Make me a todo app", Create: +- Makes a Todos table in the database with title, due date, and priority fields +- Creates Functions to save and fetch todos +- Builds a Page with a todo list and an add form +- Connects the UI to save todos when submitted with the Functions + +### Types of Changes + +Here are common ways to modify your database through chat: + +#### Adding Fields +``` +Add a description field to todos. Show it below the title in italics. +``` +Create will: +- Add the description column to the Todos table +- Update Functions to handle the new field +- Modify the UI to display descriptions + +#### Removing Fields +``` +Remove the priority field from todos, we won't use it anymore +``` +Create will: +- Remove the priority column +- Update queries to exclude the field +- Clean up any UI elements showing priority + +#### Adding Tables +``` +Let users add comments on todos. Each comment should have the text and who wrote it +``` +Create will: +- Make a new Comments table +- Link it to the Todos table +- Add UI for viewing/adding comments +- Handle saving comments to the database + +#### Changing Table Structure +``` +Instead of due dates, let's use status (Todo, In Progress, Done) to track progress +``` +Create will: +- Convert the due_date field to a status field +- Update existing data +- Modify the UI to show status options + +#### Adding Relationships +``` +Let users assign todos to team members. Show their avatar next to each todo +``` +Create will: +- Add user relationships to todos +- Update queries to fetch user data +- Show assignee info in the UI + +#### Populating Test Data +``` +Generate 10 sample todos with different statuses and assignees +``` +Create will: +- Generate 10 sample todos with different statuses and assignees based on your structure +- Insert the data into your database +- Preserve relationships between tables + +#### Data Validation +``` +Make sure todo titles are at least 3 characters and due dates can't be in the past +``` +Create will: +- Add validation rules to the database +- Update Functions to check data +- Show validation errors in the UI + + +Always describe both what data you want to store AND how you want to use it. This helps Create build the right database structure, Functions, and UI. + + + +The more specific you are in your prompt, the better Create can help. + +If you describe something at a high level, "make a todo app", Create will guess what fields each todo should have. + +If you describe what you want in detail, "make a todo app with a title, due date, and priority field", Create will make sure each todo has those fields. + + +## Viewing & Editing Data + +Create comes with a built-in database viewer for manual edits to your data. You can quickly verify that data is being stored in the right way when you use your app. + +Access it from: +* Chat - tap the database +* Project Selector - choose your database name + +The database viewer lets you: +* See all tables +* Edit individual rows +* Download data in bulk +* Make custom SQL queries to fetch data + +You can also make your own internal tools that update multiple tables at once: +* Make a new page +* Describe your tool and how it should update the database +* Try it out and verify + + +Changes in Demo mode in the Builder use a test database. This lets you experiment safely without affecting your live data. + + +## Test vs. Live + +Create maintains separate test and live databases for each project: + +**Test Database** +* Used in Demo mode from the builder + +**Live Database** +* Used in published app +* Access your live database from the builder + +When you publish your app, Create automatically: + +* Creates your live database +* Applies the latest structure from the Test database to your Live database so that you have the same tables and fields +* Runs your app with that structure + + +When making changes to your database structure after publishing, be careful about conflicts with your live database. For example: + +* You rename a column from "email" to "userEmail" in test +* But your live database already has data in "email" +* Create will warn you about this conflict on publish + +To resolve migration conflicts: + +1. Check the error message for details +2. Either: + * Modify your test database to match production (keep "email") + * Or manually migrate the live data (move data from "email" to "userEmail") +3. Try publishing again + +Create prevents destructive changes by default to protect your live data. + + +## Errors + +If you run into database issues: + +1. **Check the error message** + * Create often knows how to fix specific errors + * Paste the error into chat for help + +2. **Verify your data** + * Open database viewer + * Confirm data structure + * Look for missing or invalid entries + +3. **Test in Demo mode** + * Isolate if issue is with test or live data + * Try reproducing the problem + * Check if error is consistent + +## FAQ + + + + Yes. Create's built in databases are designed to scale. Under the hood, they use PostgreSQL, which is a powerful and scalable database system. We partner with [Neon](https://neon.tech) to automatically scale your database as your app grows. + + + + Free plans include 100mb of storage per database. You can upgrade to a paid plan to increase this. + + + + Yes! Upload CSV files through the database viewer. Or use Create to make your own import tools. + + + + Use [Functions](/builder/functions) to connect to external databases like Supabase or your own backend. + + + + Yes, live databases are automatically backed up. Contact support if you need to restore data. + + + + Create handles making queries to your database automatically. For custom queries, create a [Function](/builder/functions) and describe what you need. + + + + +Need help? Join our [Discord community](https://create.xyz/discord) or email hello@create.xyz + + +## Helpful database concepts + +Create handles most details when it comes to updating the structure of your database, or writing the code in your app to save and retrieve data from the database. + +However, it somtimes helps to have a quick mental model of how databases work: + + + + + +A database is like a collection of connected spreadsheets: + +* Each spreadsheet is a **table** +* Each column in table is a **field** +* Each row is an entry +* You connect entries across tables with **foreign keys** and **joins** + +Here are the key terms you might encounter: + +* **Schema** - A fancy term for the structure of your database (the tables and fields). Create designs this automatically based on the description of how you want your app to work. It updates it as it learns more. + +* **Table** - A collection of related data, like "Products" or "Feedback". Think of it like a spreadsheet where each row is an entry. + +* **Column** (or **Field**) - A specific piece of information you want to store, like "name" or "email". Create adds these based on what data you describe needing. + +* **Row** - A single entry in a table. Think of it like a row in a spreadsheet. + +* **Query** - Instructions for getting, saving, or updating data from/to tables in your database. Create writes these for you with Functions when you describe how you want your app to show or store data. + +* **Join** - A way to combine data from different tables. For example, grabbing all posts (from the Posts table) with their authors (from the Users table). + +* **Foreign Key** - A way to reference data in another table. Like when a post has an "authorId" that connects to a user (and userId) in the Users table. Create sets these up automatically when you describe relationships (e.g. "all posts have authors"). + +* **SQL** - The language databases use under the hood. Create handles writing SQL for you - you just describe what you want in plain English! + +* **Migrations** - Changes to your database structure over time. Create automatically handles these when you describe new features that require changing the current structure of your database. + + +Don't worry too much about these terms! Create handles the technical details. Just describe what data you want your app to store and how you want your app to display the data. + From 4464ab50a7cc0735da20748d59f29c7ec6722144 Mon Sep 17 00:00:00 2001 From: dhruv92 Date: Thu, 23 Jan 2025 16:34:25 -0800 Subject: [PATCH 2/4] feat: update --- builder/databases-v2.mdx | 23 ++++++++--------------- 1 file changed, 8 insertions(+), 15 deletions(-) diff --git a/builder/databases-v2.mdx b/builder/databases-v2.mdx index be7d082..9080923 100644 --- a/builder/databases-v2.mdx +++ b/builder/databases-v2.mdx @@ -10,37 +10,30 @@ hidden: true ## Overview -Databases let you store and manage information in your apps. Every Create project comes with a free database built in. - -As you chat with Create, it handles all the technical details - from designing your database structure to writing the code to save and retrieve data from it in your app. +Every Create project comes with a free database built in. As you chat with Create, it handles all database details - from designing the structure to writing code that saves and retrieves data. Use databases to: - -* Save user submissions (forms, feedback, uploads) -* Store content (blog posts, products, galleries) -* Persist data between uses of the app +* Store user submissions (forms, feedback, uploads) +* Save content (blog posts, products, galleries) +* Persist data between uses of the app * Build dynamic data-driven features - -Start simple! You can always expand your database as your needs grow. Create handles updating the structure automatically from your descriptions. - ## Chat -Create automatically updates your database structure & the code to save and retrieve data from it as you chat. +Create automatically updates your database structure & how your app retreives and stores data as you chat. When a feature requires storing data, it: - 1. **Designs the database structure** based on your description 2. **Makes Functions** to save and retrieve data from the database 3. **Designs the Pages and Components** to display and interact with the data -4. **Connects everything**. It makes sure the Pages and Components use the Functions when it needs data. +4. **Connects everything** to make sure your Pages use the Functions that retrieve/store data. For example, if you say "Make me a todo app", Create: - Makes a Todos table in the database with title, due date, and priority fields - Creates Functions to save and fetch todos -- Builds a Page with a todo list and an add form -- Connects the UI to save todos when submitted with the Functions +- Builds a Page with a todo list and add form +- Makes the Page use your Functions to save todos when submitted and grab todos to display ### Types of Changes From 0437af3aebd66dd793a942d031e9a9a7a9942221 Mon Sep 17 00:00:00 2001 From: dhruv92 Date: Thu, 23 Jan 2025 16:50:48 -0800 Subject: [PATCH 3/4] feat: updates --- builder/databases-v2.mdx | 53 +++++++++++++++++++++++++++++----------- 1 file changed, 39 insertions(+), 14 deletions(-) diff --git a/builder/databases-v2.mdx b/builder/databases-v2.mdx index 9080923..866cdbf 100644 --- a/builder/databases-v2.mdx +++ b/builder/databases-v2.mdx @@ -35,29 +35,54 @@ For example, if you say "Make me a todo app", Create: - Builds a Page with a todo list and add form - Makes the Page use your Functions to save todos when submitted and grab todos to display -### Types of Changes - Here are common ways to modify your database through chat: -#### Adding Fields +### Setting the scene + +It helps to start with a specific description of what you want your app to do. + +Prompt: + +``` +Make a tasks app. Users should be able to add, view, and delete tasks. + +Each task has title, description and comments + +Comments should show up under the task and show who wrote them. +``` + +Create will: +- Makk the tables needed +-- Make a Tasks table with title, description, and comments fields +-- Make a Users table with name and avatar fields +-- Make a Comments table with text and author fields +- Create Functions to save and fetch tasks, users, and comments +- Build a Page with a task list, add form, and comment list +- Make the Page use your Functions to save tasks when submitted and grab tasks to display + +### Adding Fields + ``` Add a description field to todos. Show it below the title in italics. ``` + Create will: - Add the description column to the Todos table - Update Functions to handle the new field - Modify the UI to display descriptions -#### Removing Fields +### Removing Fields + ``` Remove the priority field from todos, we won't use it anymore ``` + Create will: - Remove the priority column - Update queries to exclude the field - Clean up any UI elements showing priority -#### Adding Tables +### Adding Tables ``` Let users add comments on todos. Each comment should have the text and who wrote it ``` @@ -67,7 +92,7 @@ Create will: - Add UI for viewing/adding comments - Handle saving comments to the database -#### Changing Table Structure +### Changing Table Structure ``` Instead of due dates, let's use status (Todo, In Progress, Done) to track progress ``` @@ -76,7 +101,7 @@ Create will: - Update existing data - Modify the UI to show status options -#### Adding Relationships +### Adding Relationships ``` Let users assign todos to team members. Show their avatar next to each todo ``` @@ -85,7 +110,7 @@ Create will: - Update queries to fetch user data - Show assignee info in the UI -#### Populating Test Data +### Populating Test Data ``` Generate 10 sample todos with different statuses and assignees ``` @@ -94,7 +119,7 @@ Create will: - Insert the data into your database - Preserve relationships between tables -#### Data Validation +### Data Validation ``` Make sure todo titles are at least 3 characters and due dates can't be in the past ``` @@ -195,7 +220,7 @@ If you run into database issues: - Yes. Create's built in databases are designed to scale. Under the hood, they use PostgreSQL, which is a powerful and scalable database system. We partner with [Neon](https://neon.tech) to automatically scale your database as your app grows. + Yes. Create's built in databases are designed to scale. Under the hood, it's PostgreSQL, which is powerful and scalable. We partner with [Neon](https://neon.tech) to autoscale your database as your app grows. @@ -211,11 +236,11 @@ If you run into database issues: - Yes, live databases are automatically backed up. Contact support if you need to restore data. + Yes, databases are automatically backed up. Contact support if you need to restore data. - Create handles making queries to your database automatically. For custom queries, create a [Function](/builder/functions) and describe what you need. + Create handles making queries to your database automatically. For custom queries, create a [Function](/builder/functions) and describe what you need. You can then use your Function. Or use the built in SQL editor in the database viewer. @@ -223,7 +248,7 @@ If you run into database issues: Need help? Join our [Discord community](https://create.xyz/discord) or email hello@create.xyz -## Helpful database concepts +## Helpful database terms Create handles most details when it comes to updating the structure of your database, or writing the code in your app to save and retrieve data from the database. @@ -256,7 +281,7 @@ Here are the key terms you might encounter: * **Foreign Key** - A way to reference data in another table. Like when a post has an "authorId" that connects to a user (and userId) in the Users table. Create sets these up automatically when you describe relationships (e.g. "all posts have authors"). -* **SQL** - The language databases use under the hood. Create handles writing SQL for you - you just describe what you want in plain English! +* **SQL** - The language used to make changes to your database structure or retrieve / store data. Create handles writing SQL for you - you just describe what you want in plain English! * **Migrations** - Changes to your database structure over time. Create automatically handles these when you describe new features that require changing the current structure of your database. From 73901fa3d04d7ca8235752fcd01d802e1fb47375 Mon Sep 17 00:00:00 2001 From: dhruv92 Date: Thu, 23 Jan 2025 16:57:51 -0800 Subject: [PATCH 4/4] feat: docs --- builder/databases-v2.mdx | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/builder/databases-v2.mdx b/builder/databases-v2.mdx index 866cdbf..e176287 100644 --- a/builder/databases-v2.mdx +++ b/builder/databases-v2.mdx @@ -10,7 +10,7 @@ hidden: true ## Overview -Every Create project comes with a free database built in. As you chat with Create, it handles all database details - from designing the structure to writing code that saves and retrieves data. +Every Create project comes with a free database built in. As you chat with Create, it handles all database details - from designing the structure to writing the code that lets your app save and retrieve data from it. Use databases to: * Store user submissions (forms, feedback, uploads) @@ -52,10 +52,10 @@ Comments should show up under the task and show who wrote them. ``` Create will: -- Makk the tables needed --- Make a Tasks table with title, description, and comments fields --- Make a Users table with name and avatar fields --- Make a Comments table with text and author fields +- Make the tables needed + - Make a Tasks table with title, description, and comments fields + - Make a Users table with name and avatar fields + - Make a Comments table with text and author fields - Create Functions to save and fetch tasks, users, and comments - Build a Page with a task list, add form, and comment list - Make the Page use your Functions to save tasks when submitted and grab tasks to display @@ -63,7 +63,7 @@ Create will: ### Adding Fields ``` -Add a description field to todos. Show it below the title in italics. +Add a description to todos. Show it below the title in italics. ``` Create will: @@ -74,7 +74,7 @@ Create will: ### Removing Fields ``` -Remove the priority field from todos, we won't use it anymore +Remove the priority from todos, we won't use it anymore ``` Create will: @@ -92,7 +92,7 @@ Create will: - Add UI for viewing/adding comments - Handle saving comments to the database -### Changing Table Structure +### Changing Structure ``` Instead of due dates, let's use status (Todo, In Progress, Done) to track progress ``` @@ -101,7 +101,7 @@ Create will: - Update existing data - Modify the UI to show status options -### Adding Relationships +### Relationships ``` Let users assign todos to team members. Show their avatar next to each todo ``` @@ -110,7 +110,8 @@ Create will: - Update queries to fetch user data - Show assignee info in the UI -### Populating Test Data +### Filling Data + ``` Generate 10 sample todos with different statuses and assignees ``` @@ -119,9 +120,10 @@ Create will: - Insert the data into your database - Preserve relationships between tables -### Data Validation +### Validation + ``` -Make sure todo titles are at least 3 characters and due dates can't be in the past +Make sure every todo has a title ``` Create will: - Add validation rules to the database