JawsDB Documentation

Table of Contents

Welcome to JawsDB

JawsDB is a Database-as-a-Service (DBaaS) provider supplying a fully functional, fully managed, relational database for use with your application. Rather than going through the hassle of hosting, configuring, patching, and managing a database, JawsDB provides one-click delivery and management of a relational database in the cloud.

JawsDB is easy to use and requires no custom coding or libraries to interact with it. Simply select a plan that meets your needs, and we will provide you with the hostname and credentials necessary to dive in and start swimming with the big fish.

MySQL

MySQL is the world’s most widely used open-source relational database and is trusted by companies such as Google, Facebook, Twitter, and Youtube. Its power, stability, security, and wealth of online documentation has cemented it as a premiere option for start-ups and established businesses alike.

Provisioning

JawsDB databases can be created via the JawsDB website or via the Manifold dashboard. Both methods require a Manifold account, which you can sign up for free here.

Plan Changes

JawsDB provides situational support for automatic upgrades and downgrades between plans. See the below sections for when an up/downgrade may be possible. In all cases where automatic up/downgrading is allowed, your data should be preserved. However, it is always a good idea to backup your database before a plan change. See the section in this documentation entitled Manual Backups with mysqldump for information on how to do this.

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

Depending on whether a desired plan is a single-tenant or multi-tenant (Shared) plan and whether the storage of the desired plan is greater or less than the current plan, a user may be able to change their plan automatically by following the relevant process flow of the platform where JawsDB was purchased.

Plan changes can be made from your Manifold dashboard. Click edit on the resource you’d like to change, select the new plan that you’d like to change to, and then confirm. If successful you will see a confirmation message.

In order to tell whether an automatic plan-change is supported, please reference the table below keeping in mind the current plan and the desired plan.

PLAN To Multi-tenant To Single-tenant (storage < source storage) To Single-tenant (storage >= source storage)
From Multi-tenant Automatic Manual Manual
From Single-tenant Manual Manual Automatic

Deprovisioning

JawsDB can be removed from your account by going to the Manifold dashboard and clicking to edit a resource, then clicking “deprovision resource”.

SSO Dashboard

JawsDB provides a Dashboard where users can view important information about their Database. This information includes:

  • Connection String
  • Credentials
  • Server Status
  • Allocated Storage
  • Backup Window
  • Maintenance Window
  • Latest Restorable Time
  • SSL Information

Users can reset their Database password from the Dashboard and they may also create, view, and delete Databites.

Databites

Once your database is listed with a status of ‘AVAILABLE’, the dashboard will allow you to create Databites. As a simple, yet powerful reporting tool, Databites provide users the ability to run basic (read-only) SQL queries against their provisioned database and save those queries for later execution. Once a Databite is created, it is saved to your dashboard where it can be re-run, edited, or deleted with ease.

On your dashboard, under the section labeled ‘Databites’, select “Create New Databite”. This will direct your browser to the Databite page where custom queries can be entered into the editor which features SQL syntax highlighting. Clicking “Update” underneath the editor will execute the query against your database and return the result set in the same browser window in a tabular format.

Using the “Back” link will return you to the dashboard where your Databite will now be listed in the Databite section. Clicking on an existing Databite will redirect the browser to the Databite page and re-execute the query.

For security reasons, Databites are read-only, i.e. they do not support statements that create database objects or that alter data in your database. Think of Databites as a way to create windows into the most important information stored in your database.

Database Backups

JawsDB is based on Amazon’s AWS cloud infrastructure. Because of this, our internal backups are in an Amazon proprietary format (similar to VMWare snapshots) and cannot be downloaded. These backups are taken once per day during your server’s backup window and are stored for a fixed length of time depending on the plan purchased.

Users who have purchased a single-tenant plan (Whitetip and higher) have their snapshots listed on their JawsDB dashboard. The Snapshot ID listed there, along with the Password displayed on that same dashboard page are all that is needed to restore their database to the time when the snapshot was taken. The snapshot can be restored onto that same single-tenant plan, OR another purchased single-tenant plan. The requirement is that whichever JawsDB plan is used to host the restored snapshot must be of equal or greater storage capacity than the snapshot.

Warning: Restoring a snapshot replaces the host plan’s server entirely. Including its own snapshots.

Example 1: A user purchases a Whitetip instance and needs to revert to a snapshot. The user takes the Snapshot ID of the snapshot they wish to restore to and places it in the Snapshot ID field of the form labeled Restore from Snapshot in their JawsDB Dashboard. They also take the password from their dashboard and place it in that same form’s Password field. After clicking the Restore button, the Snapshot is restored onto a 2nd new single-tenant host. After the restore is complete, the user’s current server is replaced entirely by the server made from the snapshot. The snapshots originally listed on the Dashboard page are now replaced by those of the newly created server.

Example 2: A user purchases a Thresher instance and wishes to restore a snapshot but without replacing their current Thresher instance. The user purchases a second plan of at least Thresher value (we’ll use Tiger for this illustration), and notes the desired snapshot’s Snapshot ID along with the Password of the first Thresher server. The user then navigates to the JawsDB Dashboard of the new blank Tiger server, and enters the noted Snapshot ID and Password into the relevant fields of the form labeled Restore from Snapshot and hits the Restore button. The snapshot is then restored onto a 3rd new single-tenant host. After the restore is complete, the user’s newly created Tiger instance is replaced entirely by the server made from the snapshot. The snapshots originally listed on the Tiger plan’s Dashboard page are now replaced by those of the newly created server.

Customers are also free to take and keep their own backups using mysqldump or some other service or utility.

Below we provide a quick primer on how to use mysqldump to create and restore backups.

Manual Backups and Migrations with mysqldump

mysqldump is a powerful client utility packaged with the MySQL clients available on the MySQL downloads page. With this utility, users can backup their database into flat files as well as restore those backups to any MySQL or compatible server of their choice.

In order to complete either operation, the connection credentials and information of the relevant server(s) must be know in advance.

Connection strings provided by JawsDB contain all of the relevant info in the following format:

mysql://username:password@hostname:port/database

username, password, hostname, port, and database will be referenced in the following sections.

The mysqldump tutorials below are simplistic and general. The full range of options and configurations that mysqldump supports can be seen here and in the tool’s own man pages.

Manual Backups with mysqldump

The following command will backup the specified database into a local file called backup.sql

mysqldump -h hostname -u username -ppassword database > backup.sql

Note that there is no space between the -p flag and password

Manual Migrations

Backup files created with mysqldump can be loaded onto a target server the way any SQL file would be loaded. Below is a way to do this with the mysql command-line utlity.

mysql -h hostname -u username -ppassword database < backup.sql

Note again how there is no space between the -p flag and password

FAQ

I am unable to insert records into my database. What gives?

If you are on one of JawsDB’s shared plans, you may have breached the database size allotted via your plan. When a database grows larger than the plan allows, INSERT privileges are revoked on the database user until the database is brought back into compliance. SELECT, UPDATE, and DELETE privileges are still available during this time. Once the database size is reduced back under the maximum allowed size, the INSERT privilege will be granted back.

The following can be run against the database or placed into a databite in order to see current database size in MB and whether the account currently has INSERT privileges.

select
    s.schema_name
    ,sp.grantee user
    ,cast(round(sum(coalesce(t.data_length + t.index_length, 0)) / 1024 / 1024, 3) as char) db_size_mb
    ,sp.has_insert
from
    information_schema.schemata s
    inner join
    information_schema.tables t on s.schema_name = t.table_schema
    inner join (
        select
            spi.grantee
            ,spi.table_schema
            ,max(
                case
                    when spi.privilege_type = 'INSERT' then 1
                    else 0
                end
            ) has_insert
        from
            information_schema.schema_privileges spi
        group by
            spi.grantee
            ,spi.table_schema
    ) sp on s.schema_name = sp.table_schema
group by
    s.schema_name;

I am getting an error saying I have exceeded the ‘max_questions’ resource. What is that?

The ‘max_questions’ value is a limit that is placed on shared plan accounts to help preserve computing power for other shared plan users on the same server. It is essentially a limit on the number of queries that can be executed from that account in an hour. After 1 hour of reaching the limit, the limit will be reset and queries can again be executed.

HINT: Cached queries do not count against the query limit of ‘max_questions’. Taking advantage of the cache is a good way around this limit.

Single-tenant plans (such as Whitetip and above) carry no ‘max_questions’ limits.

How do I access my database backups?

JawsDB backups are in an Amazon-proprietary snapshot format and must be restored by the JawsDB team. Please see the section entitled Database Backups for more information.

Why do I get an error when attempting to change my plan?

In some specific situations, changing plan requires a manual migration. Please check the section entitled Plan Changes to find out whether this applies to your particular situation.

Does JawsDB support Encryption at Rest? Encryption at Rest (EAR) is a new feature applying transparent AES-256 encryption to the underlying data storage of a JawsDB database and is available on a subset of our plans. Check the desired plan’s description to see if EAR is supported.

Support

Account support and runtime issues should be sent to JawsDB’s support email address.

For news, non-critical questions, and feedback, check out the @jawsdb Twitter account