Skip to content
Butterbase

Quickstart

This guide walks you through creating an app, defining a schema, inserting data, and setting up authentication. You can do all of this through the MCP tools (if using an AI assistant), the CLI, or the REST API.

  1. Create an app

    Use the init_app tool with name: "my-app"

    You’ll receive an app_id and API base URL. Save these — you’ll need them for all subsequent operations.

  2. Define your schema

    Describe your tables in a declarative JSON format:

    {
      "schema": {
        "tables": {
          "posts": {
            "columns": {
              "id": { "type": "uuid", "primary": true, "default": "gen_random_uuid()" },
              "title": { "type": "text", "nullable": false },
              "body": { "type": "text" },
              "user_id": { "type": "uuid", "nullable": false },
              "published": { "type": "boolean", "default": "false" },
              "created_at": { "type": "timestamptz", "default": "now()" }
            }
          }
        }
      },
      "name": "create posts table"
    }

    Preview the changes first with dry_run: true, then apply.

  3. Enable row-level security

    Restrict data so each user only sees their own posts:

    Use create_user_isolation_policy with table_name: "posts", user_column: "user_id"

  4. Insert and query data

    import { createClient } from '@butterbase/sdk';
    

    const butterbase = createClient({
      appId: 'app_abc123',
      apiUrl: 'https://api.butterbase.ai',
    });
    

    // Insert a row
    const { data } = await butterbase
      .from('posts')
      .insert({ title: 'Hello World', body: 'My first post' });
    

    // Query rows
    const { data: posts } = await butterbase
      .from('posts')
      .select('*')
      .eq('published', true)
      .order('created_at', { ascending: false });

  5. Deploy your frontend

    Build your frontend, zip the output, and deploy:

    Terminal window
    npm run build
    # Zip the dist/ folder (use archiver or Git Bash zip)

    Then use the create_frontend_deployment and start_frontend_deployment MCP tools, or the REST API.

Next steps

Section titled “Next steps”