### Setup: Initialize Dolt repository and start SQL server Source: https://www.dolthub.com/docs/sql-reference/server/branch-permissions Run these commands in a dedicated terminal window to set up the example environment. It creates a directory, initializes a Dolt repository, removes the default branch control row, creates a test user, and starts the SQL server. The server runs on localhost:3306 by default. ```sql $ mkdir example $ cd example $ dolt init Successfully initialized dolt data repository. $ dolt sql -q "DELETE FROM dolt_branch_control;" Query OK, 0 rows affected (0.00 sec) $ dolt sql -q "CREATE USER testuser@localhost; GRANT ALL ON *.* TO testuser@localhost;" Query OK, 0 rows affected (0.00 sec) $ dolt sql-server Starting server with Config HP="localhost:3306"|T="28800000"|R="false"|L="info" ``` -------------------------------- ### Install and start MySQL with Homebrew Source: https://www.dolthub.com/docs/introduction/getting-started/versioned-mysql-replica Run these commands in a terminal to install MySQL and start it as a service. This sets up the primary database on port 3306. ```bash $ brew install mysql $ brew services start mysql ``` -------------------------------- ### GET deployment-options example response 200 Source: https://www.dolthub.com/docs/products/hosted/api/v1/deployment Example JSON response for a successful deployment-options request. Shows the available zones, instance types, and storage options for the specified cloud, with details like CPU, memory, and cost. ```json { "data": { "cloud": "aws", "zones": [ "us-east-1" ], "instance_types": [ { "id": "aws.t2.medium", "name": "t2.medium", "cpus": 2, "memory_gb": 4, "description": "Trial tier, the lowest spec that runs a Dolt SQL server.", "hourly_cost_usd": 0.06849315 } ], "storage_options": [ { "id": "aws.ebs.gp3_50", "name": "Trial 50GB EBS", "description": "Trial tier storage capped at 50GB", "min_size_gb": 50, "max_size_gb": 50, "monthly_cost_usd_per_gb": 0 } ] } } ``` -------------------------------- ### Setup example: main and mybranch branches Source: https://www.dolthub.com/docs/sql-reference/version-control/dolt-sql-procedures Shows the initial state of the main and mybranch branches before cherry-picking. Includes checking out branches, viewing commit logs, and viewing table contents. ```sql -- Checkout main branch CALL DOLT_CHECKOUT('main'); -- View a log of commits SELECT commit_hash, message FROM dolt_log; +----------------------------------+----------------------------+ | commit_hash | message | +----------------------------------+----------------------------+ | 7e2q0hibo2m2af874i4e7isgnum74j4m | create a new table | | omuqq67att6vfnka94drdallu4983gnr | Initialize data repository | +----------------------------------+----------------------------+ 2 rows in set (0.00 sec) -- View the table SELECT * FROM mytable; Empty set (0.00 sec) -- Checkout new branch CALL DOLT_CHECKOUT('mybranch'); -- View a log of commits SELECT commit_hash, message FROM dolt_log; +----------------------------------+----------------------------+ | commit_hash | message | +----------------------------------+----------------------------+ | 577isdjbq1951k2q4dqhli06jlauo51p | add 3, 4, 5 to the table | | k318tpmqn4l97ofpaerato9c3m70lc14 | add 1, 2 to the table | | 7e2q0hibo2m2af874i4e7isgnum74j4m | create a new table | | omuqq67att6vfnka94drdallu4983gnr | Initialize data repository | +----------------------------------+----------------------------+ 4 rows in set (0.00 sec) -- View the table SELECT * FROM mytable; +---+ | a | +---+ | 1 | | 2 | | 3 | | 4 | | 5 | +---+ 5 rows in set (0.00 sec) ``` -------------------------------- ### Example: inventory table schema at main tip Source: https://www.dolthub.com/docs/sql-reference/version-control/dolt-sql-functions Shows the schema of the 'inventory' table at the tip of the 'main' branch, used as the starting point for the example. ```text +----------+-------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +----------+-------------+------+-----+---------+-------+ | pk | int | NO | PRI | NULL | | | name | varchar(50) | YES | | NULL | | | metadata | json | YES | | NULL | | +----------+-------------+------+-----+---------+-------+ ``` -------------------------------- ### Clone and Install Dolt from Source Source: https://www.dolthub.com/docs/introduction/installation/source Clone the Dolt repository from GitHub and install the Dolt binary using `go install`. Requires Golang to be installed on the machine. The resulting binary is placed at `~/go/bin/dolt` unless `$GO_HOME` is set to a different location. ```text $ git clone git@github.com:dolthub/dolt.git Cloning into 'dolt'... remote: Enumerating objects: 25, done. remote: Counting objects: 100% (25/25), done. remote: Compressing objects: 100% (25/25), done. remote: Total 87117 (delta 4), reused 6 (delta 0), pack-reused 87092 Receiving objects: 100% (87117/87117), 93.77 MiB | 13.94 MiB/s, done. Resolving deltas: 100% (57066/57066), done.v $ cd dolt/go && go install ./cmd/dolt ``` -------------------------------- ### Install Dolt via install script Source: https://www.dolthub.com/docs/introduction/installation/mac Downloads and runs the official install script, placing the Dolt binary in /usr/local/bin. Requires sudo. ```text sudo bash -c 'curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash' ``` -------------------------------- ### Example response 202 for add instance Source: https://www.dolthub.com/docs/products/hosted/api/v1/deployment Shows the JSON response returned with status 202 when the instance is accepted and starting. The instance has no host yet and is still being provisioned. ```json { "data": { "id": "2c4e6a8b-1d3f-4a5c-8e9b-0f1a2b3c4d5e", "index": 1, "is_primary": false, "instance_type_name": "t2.medium", "volume_type_name": "Trial 50GB EBS", "volume_size_gb": 50 } } ``` -------------------------------- ### Start replica Source: https://www.dolthub.com/docs/introduction/getting-started/versioned-mysql-replica Starts the replica. The command returns Query OK. ```sql mysql> START REPLICA; Query OK, 0 rows affected (0.00 sec) ``` -------------------------------- ### Start Dolt SQL server with autocommit enabled Source: https://www.dolthub.com/docs/sql-reference/server/configuration Shows the config.yaml containing autocommit: true and the command to start the server. The server starts with the specified configuration. ```sh $ grep autocommit config.yaml autocommit: true $ dolt sql-server --config=config.yaml Starting server with Config HP="localhost:3310"|T="28800000"|R="false"|L="info"|S="/tmp/mysql.sock" ``` -------------------------------- ### dh config get example Source: https://www.dolthub.com/docs/products/dolthub/cli/commands Example of getting a configuration value using dh config get. ```bash dh config get db ``` -------------------------------- ### DOLT_BACKUP() example workflow Source: https://www.dolthub.com/docs/sql-reference/version-control/dolt-sql-procedures Complete example: set the current database, configure a backup, sync to it, and restore it to a new database name. Note the missing semicolon after the sync call in the source. ```sql -- Set the current database for the session USE mydb; -- Configure a backup to sync to. CALL dolt_backup('add', 'my-backup', 'https://dolthub.com/some_organization/some_dolthub_repository'); -- Upload the current database contents to that named backup CALL dolt_backup('sync', 'my-backup') -- Restore the uploaded database to a new database name CALL dolt_backup('restore', 'https://dolthub.com/some_organization/some_dolthub_repository', 'mydb_restored'); ``` -------------------------------- ### Install Dolt from source Source: https://www.dolthub.com/docs/guides/contributing Build Dolt from source by navigating to the go directory and running go install. ```bash ~/dolt_workspace $ cd ./dolt/go ~/dolt_workspace/dolt/go $ go install ./cmd/dolt ``` -------------------------------- ### Start Dolt SQL server Source: https://www.dolthub.com/docs/guides/binlog-replication Start the Dolt SQL server on the replica. Use a port of your choice; the example uses 11223. ```bash dolt sql-server --port 11223 ``` -------------------------------- ### GET /api/v1/deployments/{org} Source: https://www.dolthub.com/docs/products/hosted/api/v1/authentication Example endpoint showing how to use an environment variable for the token in a script. The endpoint itself is not detailed in the source, but the example demonstrates authentication usage. ```APIDOC ## GET /api/v1/deployments/{org} ### Description Example endpoint demonstrating authentication with an environment variable. The full endpoint details are not provided in the source. ### Method GET ### Endpoint /api/v1/deployments/{org} ### Parameters #### Path Parameters - **org** (string) - Required - The organization name. #### Headers - **Authorization** (string) - Required - Bearer token with format `Bearer $HOSTED_API_TOKEN` ### Request Example ```sh export HOSTED_API_TOKEN='hsat.v1.YOUR_TOKEN_HERE' curl 'https://hosted.doltdb.com/api/v1/deployments/acme' \ -H "Authorization: Bearer $HOSTED_API_TOKEN" ``` ### Response (No response details provided in source.) ### Error Handling - **401** - `UNAUTHENTICATED` - The `Authorization` header was missing, malformed, or the token is invalid or expired. - **403** - `PERMISSION_DENIED` - The token is valid, but its user is not permitted to perform this action. Both errors are returned as Problem documents. ``` -------------------------------- ### Configure and start Dolt SQL server with mcp_server Source: https://www.dolthub.com/docs/sql-reference/server/configuration Shows a config.yaml excerpt with mcp_server settings and the command to start the SQL server. The output includes server startup logs and warnings about secure_file_priv. ```sh $ grep -5 mcp_server config.yaml # remotesapi: # port: 8000 # read_only: false mcp_server: port: 7007 user: root password: "" database: "" $ dolt sql-server --config config.yaml Starting server with Config HP="0.0.0.0:3306"|T="28800000"|R="false"|L="debug" DEBU[0000] Loading events DEBU[0000] privileges.db already exists, not creating root superuser INFO[0000] Server ready. Accepting connections. WARN[0000] secure_file_priv is set to "", which is insecure. WARN[0000] Any user with GRANT FILE privileges will be able to read any file which the sql-server process can read. WARN[0000] Please consider restarting the server with secure_file_priv set to a safe (or non-existent) directory. ``` -------------------------------- ### POST /api/v1/deployments Source: https://www.dolthub.com/docs/products/hosted/api/v1/deployment Provisions a new deployment and returns 202 with the deployment in its starting state. Provisioning continues after the response: poll GET /api/v1/deployments/{owner}/{deployment} until state becomes started. ```APIDOC ## POST /api/v1/deployments ### Description Provisions a new deployment and returns `202` with the deployment in its `starting` state. Provisioning continues after the response: poll `GET /api/v1/deployments/{owner}/{deployment}` until `state` becomes `started`. ### Method POST ### Endpoint /api/v1/deployments ### Parameters #### Request Body - **owner** (string) - Required - The user or organization that will own the deployment. The caller must have permission to create deployments for it. 3–32 characters of letters, digits, hyphens, and underscores. - **name** (string) - Required - The deployment name, unique within the owner. 3–32 characters of letters, digits, hyphens, and underscores. - **cloud** (CloudProvider) - Required - The cloud the deployment runs in. - **zone** (string) - Required - The cloud region to provision in, as listed by the deployment options. - **cluster_type** (ClusterType) - Optional - The database engine the deployment runs. `mysql_with_dolt_replicas` is a MySQL primary with Dolt read replicas. - **instance_type_id** (string) - Required - The **id** of the instance type, from the deployment options endpoint. Note a deployment reports `instance_type_name` on a read β€” the id and the display name are different values. - **volume_type_id** (string) - Required - The **id** of the storage type, from the deployment options endpoint. As with `instance_type_id`, this is the id rather than the display name. - **volume_size_gb** (integer) - Required - The size of the storage volume, in gigabytes. Must fall within the selected storage type's supported range. - **replicas** (integer) - Optional - The number of read replicas. Defaults to `0` when omitted. - **webpki_cert** (boolean) - Optional - Serve a publicly-trusted (WebPKI) TLS certificate rather than a Hosted-issued one. Defaults to `false` when omitted. - **expose_remotesapi_endpoint** (boolean) - Optional - Expose a Dolt remotes API endpoint. Defaults to `false` when omitted. - **expose_mcp** (boolean) - Optional - Expose an MCP endpoint. Defaults to `false` when omitted. - **expose_stats** (boolean) - Optional - Expose a statistics endpoint. Defaults to `false` when omitted. ### Request Example ```sh curl -X POST 'https://hosted.doltdb.com/api/v1/deployments' \ -H 'Authorization: Bearer YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"owner":"acme","name":"analytics","cloud":"aws","zone":"us-east-1","instance_type_id":"aws.t2.medium","volume_type_id":"aws.ebs.gp3_50","volume_size_gb":50}' ``` ### Response #### Success Response (202) - The deployment has been accepted and is provisioning. `state` is `starting`. - Schema: Deployment #### Error Responses - **400** - The request was malformed or failed input validation. - **401** - Authentication credentials were missing or invalid. - **403** - Authenticated, but not permitted to perform this action. - **405** - The HTTP method is not supported for this resource. - **409** - The request conflicts with the current state of the resource (e.g. it already exists). - **422** - The request was well-formed but semantically invalid. - **500** - An unexpected server error occurred. - **503** - The service is temporarily unavailable. ``` -------------------------------- ### DOLT_STASH full example workflow Source: https://www.dolthub.com/docs/sql-reference/version-control/dolt-sql-procedures Complete example showing creating a table, making changes, stashing them, viewing stashes, and restoring changes. Includes SQL statements and their outputs. ```sql -- Create a table and make some changes CREATE TABLE employees (id INT PRIMARY KEY, name VARCHAR(100)); INSERT INTO employees VALUES (1, 'Alice'), (2, 'Bob'); CALL DOLT_ADD('.'); -- Stash the changes CALL DOLT_STASH('push', 'stash1'); -- Working directory is now clean SELECT * FROM employees; Empty set (0.00 sec) -- View stashes SELECT * FROM dolt_stashes; +--------+----------+--------+----------------------------------+-------------------------------------+ | name | stash_id | branch | hash | commit_message | +--------+----------+--------+----------------------------------+-------------------------------------+ | stash1 | stash@{0}| main | abc123def456789... | Initialized Data Repository | +--------+----------+--------+----------------------------------+-------------------------------------+ -- Restore the changes CALL DOLT_STASH('pop', 'stash1'); -- Changes are restored SELECT * FROM employees; +----+-------+ | id | name | +----+-------+ | 1 | Alice | | 2 | Bob | +----+-------+ ``` -------------------------------- ### DOLT_VERSION() usage example Source: https://www.dolthub.com/docs/sql-reference/version-control/dolt-sql-functions Shows how to call DOLT_VERSION() to get the version string of the Dolt binary. ```sql mysql> select dolt_version(); +----------------+ | dolt_version() | +----------------+ | 0.40.4 | +----------------+ ``` -------------------------------- ### Show databases and use a database in Dolt Source: https://www.dolthub.com/docs/concepts/dolt/sql/databases Example SQL session showing how to list databases with SHOW DATABASES and select one with USE. The output displays the databases 'docs' and 'information_schema', then shows tables in the selected database. ```sql mysql> show databases; +--------------------+ | Database | +--------------------+ | docs | | information_schema | +--------------------+ mysql> use docs; mysql> show tables; +----------------+ | Tables_in_docs | +----------------+ | docs | +----------------+ ``` -------------------------------- ### Example response 200 for GET /api/v1/user Source: https://www.dolthub.com/docs/products/hosted/api/v1/user Shows the JSON structure of a successful response, including username, display_name, company, and email_addresses. ```json { "data": { "username": "acme-ops", "display_name": "Acme Operations", "company": "Acme Corp", "email_addresses": [ { "address": "ops@acme.com", "is_verified": true, "is_primary": true } ] } } ``` -------------------------------- ### Example: initial inventory data at main tip Source: https://www.dolthub.com/docs/sql-reference/version-control/dolt-sql-functions Shows the initial state of the 'inventory' table at the tip of 'main', with JSON data in the metadata column. ```text +----+-------+----------------------------------------------------------------+ | pk | name | metadata. | +----+-------+----------------------------------------------------------------+ | 1 | shirt | {"colors": ["red"] } | | 2 | shoes | {"colors": ["black"], "size": "small" } | | 3 | pants | {"colors": ["blue", "beige"], "materials": ["denim", "silk"] } | | 4 | tie | {"colours": ["red"], "clip-on": true } | +----+-------+----------------------------------------------------------------+ ``` -------------------------------- ### dolt ci init synopsis Source: https://www.dolthub.com/docs/cli-reference/cli Shows the command syntax for initializing Dolt CI configuration tables. ```bash dolt ci init ``` -------------------------------- ### Get a database (GET /api/v2/databases/{owner}/{database}) with example response Source: https://www.dolthub.com/docs/products/dolthub/api/v2/database Returns metadata for the database {owner}/{database}. Public databases are readable without authentication; private databases require a credential with access and return 404 otherwise so their existence is not leaked. ```sh curl -X GET 'https://www.dolthub.com/api/v2/databases/{owner}/{database}' \ -H 'Authorization: Bearer YOUR_TOKEN' ``` ```json { "data": { "owner": "dolthub", "name": "us-jails", "description": "Open data about incarceration in the United States.", "visibility": "public", "fork_network_count": 3, "star_count": 42, "size_bytes": 10485760, "last_write_at": "2024-01-15T12:34:56Z" } } ``` -------------------------------- ### GET database-version response 200 Source: https://www.dolthub.com/docs/products/hosted/api/v1/deployment Example JSON response for a successful request. Shows the current version and the list of available versions for the deployment. ```json { "data": { "current": "1.59.2", "available": [ "1.60.0", "1.59.2", "1.59.1", "1.58.4", "1.58.3" ] } } ``` -------------------------------- ### Get table hash with DOLT_HASHOF_TABLE() Source: https://www.dolthub.com/docs/sql-reference/version-control/dolt-sql-functions SQL example showing how to get the value hash of a table named 'color'. The hash is based on all rows and serialization format; a changed hash guarantees data changed, but same rows may have different hashes if format changes. ```sql mysql> SELECT dolt_hashof_table('color'); +----------------------------------+ | dolt_hashof_table('color') | +----------------------------------+ | q8t28sb3h5g2lnhiojacpi7s09p4csjv | +----------------------------------+ 1 row in set (0.01 sec) ``` -------------------------------- ### Create database and tables in MySQL client Source: https://www.dolthub.com/docs/introduction/getting-started/database Executes SQL statements to create the 'getting_started' database with three tables: employees, teams, and employees_teams. Includes foreign key constraints and shows the resulting table list. ```sql mysql> create database getting_started; Query OK, 1 row affected (0.04 sec) mysql> use getting_started; Database changed mysql> create table employees ( id int, last_name varchar(255), first_name varchar(255), primary key(id)); Query OK, 0 rows affected (0.01 sec) mysql> create table teams ( id int, team_name varchar(255), primary key(id)); Query OK, 0 rows affected (0.00 sec) mysql> create table employees_teams( team_id int, employee_id int, primary key(team_id, employee_id), foreign key (team_id) references teams(id), foreign key (employee_id) references employees(id)); Query OK, 0 rows affected (0.01 sec) mysql> show tables; +---------------------------+ | Tables_in_getting_started | +---------------------------+ | employees | | employees_teams | | teams | +---------------------------+ 3 rows in set (0.00 sec) ``` -------------------------------- ### DOLT_SCHEMA_DIFF() example query Source: https://www.dolthub.com/docs/sql-reference/version-control/dolt-sql-functions Query to get the schema diff between two tags (schema_diff_v1 and schema_diff_v2) in the DoltHub docs_examples DB. The query is embedded in a DoltHub SQL console. ```sql SELECT * FROM dolt_schema_diff('schema_diff_v1', 'schema_diff_v2'); ``` -------------------------------- ### Initialize Dolt CI and view commit Source: https://www.dolthub.com/docs/products/dolthub/continuous-integration/getting-started Run `dolt ci init` to create Dolt's internal CI tables and write a new commit, then verify with `dolt log`. ```bash % dolt ci init % dolt log -n 1 commit mptat9ijrblrb2q4j2digq9miav3vfv0 (HEAD -> master) Author: 😺😺😺😺 Date: Wed Nov 13 15:36:27 -0800 2024 Successfully initialized Dolt CI % ``` -------------------------------- ### Example response 200 for get deployment Source: https://www.dolthub.com/docs/products/hosted/api/v1/deployment Shows the JSON response for a successful deployment retrieval, including fields such as owner, name, state, cloud, and instance details. ```json { "data": { "owner": "acme", "name": "analytics", "state": "started", "cloud": "aws", "zone": "us-east-1", "cluster_type": "dolt", "instance_type_name": "t2.medium", "volume_type_name": "Trial 50GB EBS", "volume_size_gb": 50, "replicas": 0, "database_version": "1.58.4", "host": "analytics.dbs.hosted.doltdb.com", "port": 3306, "hourly_cost_usd": 0.06849315, "webpki_cert": true, "expose_remotesapi_endpoint": false, "expose_mcp": false, "expose_stats": false, "disable_automatic_dolt_updates": false, "caller_role": "admin", "created_by": "acme-ops", "created_at": "2026-07-01T18:22:04Z" } } ``` -------------------------------- ### Start replication Source: https://www.dolthub.com/docs/guides/binlog-replication Start the replica to begin applying binlog events from the source. ```sql START REPLICA; ``` -------------------------------- ### GET /api/v1/deployments/{owner}/{deployment}/logs - 200 response with empty window Source: https://www.dolthub.com/docs/products/hosted/api/v1/deployment Example 200 response when the requested time window contains no log lines. The data array is empty. ```json { "data": [] } ``` -------------------------------- ### Run the sample remote server Source: https://www.dolthub.com/docs/sql-reference/version-control/remotes Starts the sample remote server locally with HTTP port 1234 and storage directory './remote_storage'. The server listens on port 50051 for gRPC requests and provides file upload/download on port 1234. ```bash remotesrv --http-port 1234 --dir ./remote_storage ``` -------------------------------- ### DOLT_BRANCH examples: list, create, rename, delete branches Source: https://www.dolthub.com/docs/sql-reference/version-control/dolt-sql-procedures Shows how to list branches, create a new branch from HEAD and switch to it, create a branch from an existing branch, rename a branch, and delete a branch using DOLT_BRANCH and DOLT_CHECKOUT. ```sql -- List the available branches SELECT * FROM DOLT_BRANCHES; +--------+----------------------------------+ | name | hash | +--------+----------------------------------+ | backup | nsqtc86d54kafkuf0a24s4hqircvg68g | | main | dvtsgnlg7n9squriob3nq6kve6gnhkf2 | +--------+----------------------------------+ -- Create a new branch for development work from the tip of head and switch to it CALL DOLT_BRANCH('myNewFeature'); CALL DOLT_CHECKOUT('myNewFeature'); -- View your current branch select active_branch(); +----------------+ | active_branch | +----------------+ | myNewFeature | +----------------+ -- Create a new branch from an existing branch CALL DOLT_BRANCH('-c', 'backup', 'bugfix-3482'); -- Rename a branch CALL DOLT_BRANCH('-m', 'bugfix-3482', 'critical-bugfix-3482'); -- Delete a branch CALL DOLT_BRANCH('-d', 'old-unused-branch'); ``` -------------------------------- ### DOLT_HASHOF_DB() usage example Source: https://www.dolthub.com/docs/sql-reference/version-control/dolt-sql-functions Shows how to call DOLT_HASHOF_DB() to get the hash of the entire database. The hash includes all tables, stored procedures, and triggers, but excludes ignored tables. The default call is equivalent to 'WORKING'. ```sql mysql> SELECT dolt_hashof_db(); +----------------------------------+ | dolt_hashof_db() | +----------------------------------+ | 1q8t28sb3h5g2lnhiojacpi7s09p4csj | +----------------------------------+ ``` -------------------------------- ### MySQL server configuration example Source: https://www.dolthub.com/docs/guides/import Example configuration for a MySQL server that will be migrated to Dolt. Shows the user, password, host, port, and database settings. ```yaml user: root password: host: 0.0.0.0 port: 3306 database: test ``` -------------------------------- ### Configure remotesapi and start sql-server Source: https://www.dolthub.com/docs/sql-reference/version-control/remotes Set up the remotesapi port in config.yaml, create a database and user, grant CLONE_ADMIN, and start the sql-server process. The remotesapi endpoint will listen on the same IP as the SQL server, on the specified port. ```bash $ cat config.yaml remotesapi: port: 8080 $ dolt sql -q "create database exampledb" $ dolt sql -q "create user 'exampleuser'@'%' identified by 'examplepassword'" $ dolt sql -q "grant clone_admin on *.* to 'exampleuser'@'%'" $ dolt sql-server --config config.yaml & ```