Guide to connect MariaDB to Velvet

Connect your MariaDB database to your Velvet workspace. You can skip some steps if you've previously connected to other services.

1. Create a read-only user

Create a user with read-only permissions in MariaDB.

Connect to your MariaDB server

Run the following SQL commands in a MariaDB client or command-line interface.

  1. Create a Velvet read-only user with your password.

    CREATE USER 'velvet_readonly'@'%' IDENTIFIED BY 'mypassword';

    The % in the command above means that user velvet_readonly can be used to connect from any host or IP. You can limit the access by defining the host or IP from where the user can connect.

  2. Grant read-only permissions to the user. Replace database_name with the name of your database.

    GRANT SELECT ON database_name.* TO 'velvet_readonly'@'%';

    If you want the user to have read-only access to all databases:

    GRANT SELECT ON *.* TO 'velvet_readonly'@'%';

    The % in the command above gives the user velvet_readonly read-only access to the database from any host or IP. You can limit the access by defining the host or IP from where the user can connect. To grant access to a single table, specify the table name instead of *.

  3. After granting permissions, reload the privileges to ensure the changes take effect:


2. Set static IPs

Configure network restrictions to allow Velvet's static IP addresses. Follow our static IP configuration guide.

3. Build your connection string

Read our general guide on URI construction here. The MariaDB-specific overview is below.

If you already have a connection string, skip to step #4.

Build your connection string (URI)

Ensure all characters that require encoding are converted to their percent encoded counterparts.

Characters to percent-encode:

  • %%25
  • &%26
  • /%2F
  • :%3A
  • =%3D
  • ?%3F
  • @%40
  • [%5B
  • ]%5D

The MariaDB connection string requires a username, followed by an optional password in the following format:


If you prefer to specify only the username, you can use:


The host (a name resolved by an external name system like DNS, an IP address or other direct address) and the port (port number on which the database server is running):


If the MariaDB server is running on the default port (3306) you can omit the port component:


The schema name is required and is provided after the host and port. The database name begins with a forward slash.


You can also include additional parameters to customize the connection. These parameters are appended to the connection string and start with a question mark (?).


Common parameters::

  • charset
  • sslmode
  • timeout

Examples to illustrate these formats:

  1. Only Username on Localhost


  2. Default port with Username and Password


  3. Multiple Additional Parameters


Once done, copy your connection string to paste it into Velvet.

4. Connect your database

Connect your database to Velvet using your connection string.

  1. Tap into a workspace in your Velvet dashboard
  2. Tap "Add a data source"
  3. Select type "Remote database"
  4. Name your database
  5. Paste in your database URI
  6. Press create

If you run into any errors, schedule a call or email [email protected].

Once your database is connected, you're ready to use the AI SQL editor. Close out of the modal to start using the editor on top of your database.

Schema mapping is optional, and only required if you want to query multiple sources at the same time.

5. [optional] Schema mapping for unified sources

This configuration is only required to query multiple data sources at the same time. For example - two databases at the same time, or stripe webhooks alongside your database tables.

You can set up this unified mapping any time.

Add schema mapping context

After you connect your database, you'll be prompted to configure the schema for each table you set up.

Name your table to create this source.

Repeat these schema mapping steps for each table you want included as a unified data source.

Get help

Email [email protected] if you need additional support.