Skip to content
Snippets Groups Projects
Unverified Commit 9bf90b61 authored by flamber's avatar flamber Committed by GitHub
Browse files

Docs: cleanup (#12124) 


* Remove old FAQ and update a couple of other docs

* Prettier [ci skip]

* Reset password rewrite and cleanup [ci skip]

* Add note about MySQL requirement [ci skip]

* Maz suggestion [ci skip]

Co-Authored-By: default avatarMaz Ameli <maz@metabase.com>

Co-authored-by: default avatarMaz Ameli <maz@metabase.com>
parent 2b794ee0
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 106 additions and 236 deletions
docs/developers-guide-drivers.md
+ 23
− 16
View file @ 9bf90b61
......@@ -10,21 +10,28 @@ Want to build your own driver? Take a look at the [driver development](#driver-d
In order to install a community driver, you would typically download the latest jar file from the relevant repository release page and copy it into the plugins directory.
All Metabase plugins live in the plugins directory, which defaults to `./plugins` in the same directory as `metabase.jar`. The plugins directory can be changed by setting the env var `MB_PLUGINS_DIR`.
Please note that you install these at your own risk. The plugins will run as part of your Metabase instance and, as such, will have access to anything it does. These are the currently known 3rd-party database drivers for Metabase.
| Database | GitHub Stars | Last release (_if available_) |
| ---- | ---- | ----|
| [Amazon Athena](https://github.com/dacort/metabase-athena-driver) | ![GitHub stars](https://img.shields.io/github/stars/dacort/metabase-athena-driver) | ![GitHub (Pre-)Release Date](https://img.shields.io/github/release-date-pre/dacort/metabase-athena-driver) |
| [ClickHouse](https://github.com/enqueue/metabase-clickhouse-driver) | ![GitHub stars](https://img.shields.io/github/stars/enqueue/metabase-clickhouse-driver) | ![GitHub (Pre-)Release Date](https://img.shields.io/github/release-date-pre/enqueue/metabase-clickhouse-driver) |
| [CSV](https://github.com/Markenson/csv-metabase-driver) | ![GitHub stars](https://img.shields.io/github/stars/Markenson/csv-metabase-driver) ||
| [Cube.js](https://github.com/lili-data/metabase-cubejs-driver) | ![GitHub stars](https://img.shields.io/github/stars/lili-data/metabase-cubejs-driver) | ![GitHub (Pre-)Release Date](https://img.shields.io/github/release-date-pre/lili-data/metabase-cubejs-driver) |
| [Datomic](https://github.com/lambdaisland/metabase-datomic) | ![GitHub stars](https://img.shields.io/github/stars/lambdaisland/metabase-datomic) ||
| [DB2](https://github.com/dludwig-jrt/metabase-db2-driver) | ![GitHub stars](https://img.shields.io/github/stars/dludwig-jrt/metabase-db2-driver) ||
| [Firebird](https://github.com/evosec/metabase-firebird-driver) | ![GitHub stars](https://img.shields.io/github/stars/evosec/metabase-firebird-driver) | ![GitHub (Pre-)Release Date](https://img.shields.io/github/release-date-pre/evosec/metabase-firebird-driver) |
| [Teradata](https://github.com/swisscom-bigdata/metabase-teradata-driver) | ![GitHub stars](https://img.shields.io/github/stars/swisscom-bigdata/metabase-teradata-driver) | ![GitHub (Pre-)Release Date](https://img.shields.io/github/release-date-pre/swisscom-bigdata/metabase-teradata-driver) |
| [Spark Databricks](https://github.com/ifood/metabase-sparksql-databricks-driver) | ![GitHub stars](https://img.shields.io/github/stars/ifood/metabase-sparksql-databricks-driver) | ![GitHub (Pre-)Release Date](https://img.shields.io/github/release-date-pre/ifood/metabase-sparksql-databricks-driver) |
All Metabase plugins live in the plugins directory, which defaults to `./plugins` in the same directory as `metabase.jar`. The plugins directory can be changed by setting the env var `MB_PLUGINS_DIR`.
**Note:** You install these at your own risk. The plugins will run as part of your Metabase instance and, as such, will have access to anything it does.
These are the currently known 3rd-party database drivers for Metabase.
| Database | GitHub Stars | Last release (_if available_) |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| [Amazon Athena](https://github.com/dacort/metabase-athena-driver) | ![GitHub stars](https://img.shields.io/github/stars/dacort/metabase-athena-driver) | ![GitHub (Pre-)Release Date](https://img.shields.io/github/release-date-pre/dacort/metabase-athena-driver) |
| [ClickHouse](https://github.com/enqueue/metabase-clickhouse-driver) | ![GitHub stars](https://img.shields.io/github/stars/enqueue/metabase-clickhouse-driver) | ![GitHub (Pre-)Release Date](https://img.shields.io/github/release-date-pre/enqueue/metabase-clickhouse-driver) |
| [CSV](https://github.com/Markenson/csv-metabase-driver) | ![GitHub stars](https://img.shields.io/github/stars/Markenson/csv-metabase-driver) | |
| [Cube.js](https://github.com/lili-data/metabase-cubejs-driver) | ![GitHub stars](https://img.shields.io/github/stars/lili-data/metabase-cubejs-driver) | ![GitHub (Pre-)Release Date](https://img.shields.io/github/release-date-pre/lili-data/metabase-cubejs-driver) |
| [Datomic](https://github.com/lambdaisland/metabase-datomic) | ![GitHub stars](https://img.shields.io/github/stars/lambdaisland/metabase-datomic) | |
| [DB2](https://github.com/dludwig-jrt/metabase-db2-driver) | ![GitHub stars](https://img.shields.io/github/stars/dludwig-jrt/metabase-db2-driver) | |
| [Firebird](https://github.com/evosec/metabase-firebird-driver) | ![GitHub stars](https://img.shields.io/github/stars/evosec/metabase-firebird-driver) | ![GitHub (Pre-)Release Date](https://img.shields.io/github/release-date-pre/evosec/metabase-firebird-driver) |
| [Materialize](https://github.com/MaterializeInc/metabase-materialize-driver) | ![GitHub stars](https://img.shields.io/github/stars/MaterializeInc/metabase-materialize-driver) | ![GitHub (Pre-)Release Date](https://img.shields.io/github/release-date-pre/MaterializeInc/metabase-materialize-driver) |
| [Teradata](https://github.com/swisscom-bigdata/metabase-teradata-driver) | ![GitHub stars](https://img.shields.io/github/stars/swisscom-bigdata/metabase-teradata-driver) | ![GitHub (Pre-)Release Date](https://img.shields.io/github/release-date-pre/swisscom-bigdata/metabase-teradata-driver) |
| [Spark Databricks](https://github.com/ifood/metabase-sparksql-databricks-driver) | ![GitHub stars](https://img.shields.io/github/stars/ifood/metabase-sparksql-databricks-driver) | ![GitHub (Pre-)Release Date](https://img.shields.io/github/release-date-pre/ifood/metabase-sparksql-databricks-driver) |
If you don't see a driver for your database, then try looking in the comments of the [issue related to the database](https://github.com/metabase/metabase/labels/Database%2F). You might also find more by [searching on GitHub](https://github.com/search?q=metabase+driver).
If you are having problems with installing or using a community driver, your best bet is to contact the author of the driver.
## Driver development
......@@ -32,7 +39,7 @@ If the driver you're looking for isn't available, take a look at the [Writing a
- If your database has a JDBC driver, you'll be able to make use of some common classes that already exist in Metabase.
- We're still working on providing an independent test framework for drivers, but you can copy or symlink your driver into a local copy of the Metabase source code in order to utilize pre-existing tests. Take a look at [Test Extension Basics](https://github.com/metabase/metabase/wiki/Writing-a-Driver:-Adding-Test-Extensions,-Tests,-and-Setting-up-CI#test-extensions-basics) on the wiki.
- If you have questions related to driver development, feel free to post on our [driver development forum](https://discourse.metabase.com/c/driver-development).
- If you have questions related to driver development, feel free to post on our [driver development forum](https://discourse.metabase.com/c/driver-development).
## Driver development announcements
......
docs/enterprise-guide/serialization.md
+ 15
− 14
View file @ 9bf90b61
......@@ -4,31 +4,32 @@ Once you really get rolling with Metabase it's often the case that you'll have m
To help you out in situations like this, Metabase has a serialization feature which lets you create a snapshot, called a dump, of the contents of a Metabase instance that can then be loaded into another instance. This lets you do things like create a set of dashboards and charts in one Metabase instance and then easily copy those items to a number of other Metabase instances. You could also use this feature to enable a staging-to-production workflow for important dashboards or reports by dumping from a staging instance of Metabase and then loading that dump into your production instance(s). You can even put the dump files into version control and audit changes to them, as the YAML files contained within the dump are pretty readable.
If you're looking to do a one-time migration from H2 to MySQL/Postgres, then use the [migration guide instead](../operations-guide/migrating-from-h2.md).
### What gets dumped and loaded
**Currently, dumps consist of the following Metabase artifacts:**
* Collections
* Dashboards
* Saved questions
* Pulses
* Segments and Metrics defined in the Data Model
* Archived collections, dashboards, saved questions, or pulses
* Public sharing settings for questions and dashboards
- Collections
- Dashboards
- Saved questions
- Pulses
- Segments and Metrics defined in the Data Model
- Archived collections, dashboards, saved questions, or pulses
- Public sharing settings for questions and dashboards
**They also contain a number of system settings:**
* Admin Panel settings, except for permissions
* Database connection settings
* Data Model settings
- Admin Panel settings, except for permissions
- Database connection settings
- Data Model settings
**Dumps do _not_ contain:**
* Permission settings
* User accounts or settings
* Alerts on saved questions
* Personal Collections or their contents (except for the user specified with the `--user` flag; see below)
- Permission settings
- User accounts or settings
- Alerts on saved questions
- Personal Collections or their contents (except for the user specified with the `--user` flag; see below)
### Before creating or loading a dump
......
docs/faq.md
+ 2
− 146
View file @ 9bf90b61
# Frequently Asked Questions
## Frequently Asked Questions
## Logging in
### I can't log into Metabase. Can you reset my password?
If you are running the MacOS application on your laptop, you can click on the Help menu item and click `Reset Password`.
If you are using a browser to access Metabase, then someone downloaded our software and installed it on a server. We at Metabase don't host your instance. We write software that someone at your company decided to run. You should ask whomever it was that set up your company's Metabase for help resetting your password.
## Metabase on macOS
### How should I use the macOS application?
Our macOS application is best thought of as Metabase in single-player mode. It's meant to be a way to quickly try Metabase out and see if it's something you'd want to use across your team. It's also useful for use on your own.
When you need to share dashboards or pulses with others, we _strongly_ recommend you run our server application.
## Asking questions and running queries
### Can I use SQL with Metabase?
[Yes](users-guide/writing-sql.md).
### Do I need to know SQL to use Metabase?
[No](users-guide/04-asking-questions.md)
### Does Metabase support SQL Joins?
Yes. Joins were introduced in Metabase version 0.33 and can be used in the [Notebook-editor](users-guide/custom-questions.md).
For older versions, please see our [blog post on the subject](https://metabase.com/blog/Joins)
### Why can't I do X in the Query Builder?
The primary audience of the GUI querying interface is a non-technical user who doesn't SQL. Advanced users can always [use SQL](users-guide/writing-sql.md).
We're constantly trying to walk the line between putting more functionality into the GUI interface and creating a confusing mess. You can expect it to improve and change with time, but in the meantime, you can always lean on SQL directly for the complicated matters.
### Why can't I seem to use drill-through or question actions?
Metabase allows you to [click on your charts or tables to explore or zoom in](users-guide/03-basic-exploration.md), but these features don't currently work with SQL/native queries (this is because Metabase doesn't currently parse these kinds of queries). The same is true of the question actions menu in the bottom-right of the question detail page.
However, in [Metabase version 0.25 we introduced nested queries](https://metabase.com/blog/Metabase-0.25#nested-questions), a feature that lets you use the results of SQL/native queries as the starting table for GUI-based questions. This means you'll be able to use sophisticated SQL/native queries to create the exact segments you need, and you and your team will be able to use drill-through and actions if you create GUI-based questions from those segments.
## Why are my field or table names showing up with weird spacing?
By default, Metabase attempts to make field names more readable by changing things like `somehorriblename` to `Some Horrible Name`. This does not work well for languages other than English, or for fields that have lots of abbreviations or codes in them. If you'd like to turn this setting off, you can do so from the Admin Panel under Settings > General > Friendly Table and Field Names.
To manually fix field or table names if they still look wrong, you can go to the Metadata section of the Admin Panel, select the database that contains the table or field you want to edit, select the table, and then edit the name(s) in the input boxes that appear.
## Dashboards
### Can I add headings, free text, section dividers, or images to my dashboards?
Yes, by using [text cards](users-guide/07-dashboards.html#adding-headings-or-descriptions-with-text-cards).
### Why do my cards fade out when I use dashboard filters?
When one or more dashboard filters are active, any card on that dashboard that isn't connected to _every currently active filter_ will fade out a bit to clarify that they are not being affected by all active filters. We understand this behavior is contentious, so we're [actively discussing it on GitHub](https://github.com/metabase/metabase/issues/4220).
### Can I set permissions to choose which users can view which dashboards?
Not directly. But if a user does not have permission to view _any_ of the cards that a dashboard includes, she won't see that dashboard listed in the Dashboards section, and won't be allowed to see that dashboard if given a direct link to it. Additionally, we're currently actively considering placing dashboards inside collections, which would allow administrators to use collection permissions to restrict user group access to dashboards the same way they currently can to restrict access to saved questions.
### Why can't I make my dashboard cards smaller?
Metabase has minimum size limits for dashboard cards to ensure that numbers and charts on dashboards are legible. You might be asking this question because you're trying to fit a lot of things in a dashboard, and another way we're exploring to solve _that_ problem is by making it easier to put more than one series or metric in the same question, which would reduce the number of cards required to be on a dashboard in the first place.
### When I make a number card on a dashboard small, the number changes. Why?
In an effort to make sure that dashboards are legible, Metabase changes the way charts and numbers in cards look at different sizes. When a number card is small, Metabase abbreviates numbers like 42,177 to 42k, for example.
## Pulses and Metabot
### Why do my charts look different when I put them in a Pulse?
Metabase automatically changes the visualization type of saved questions you put in Pulses so that they fit better in emails and Slack. Here is [an inventory of how charts get changed](https://github.com/metabase/metabase/issues/5493#issuecomment-318198816), and here is [the logic for how this works](https://github.com/metabase/metabase/blob/8f1a287496899250d89a20ec57ac8477cd20bce5/src/metabase/pulse/render.clj#L385-L397).
We understand this behavior isn't expected, and are currently exploring ways to handle this better.
### Can I set more specific or granular schedules for Pulses?
Not yet, but [we'd love your help](https://github.com/metabase/metabase/issues/3846#issuecomment-318516189) working on implementing designs for this feature.
### Can I send Pulses to private Slack channels, or to multiple channels?
No, this is currently [a limitation with the way we're required to implement our Slack integration](https://github.com/metabase/metabase/issues/2694).
## Databases
### Does Metabase support database X?
Metabase currently supports:
- Amazon Redshift
- BigQuery
- Druid
- H2
- MongoDB (version 3.4 or higher)
- MySQL (and MariaDB)
- PostgreSQL
- Presto
- SQL Server
- SQLite
### Can Metabase support database X?
Metabase is built by a small core team, and we have very limited engineering bandwidth. Each additional database we connect to slows down overall product development, increases the time and cost of our automated testing and requires us to learn a lot about the edge cases of the specific database driver. While writing a given driver might only take a few days, supporting it places a cost on us indefinitely.
That said, we will build out additional database connectors as we are able to. We generally select additional drivers based on demand from the community and our ability to set up a test database server easily in our e2e testing environment.
We welcome community contributions of database connectors. If you're able to help, we have [open issues](https://github.com/metabase/metabase/labels/Database%2F) for a number of databases. We'd greatly appreciate your help!
### Can Metabase connect to Google Analytics, Salesforce, etc.?
Metabase currently supports Google Analytics as a data source. The connection can be set up by an admin the same way database connections are set. If you are using Google Analytics Premium, one of the features is direct access to a BigQuery database with your personal Google Analytics data. BigQuery is also supported by Metabase.
We do not currently offer a way to connect to other third-party APIs or services directly. What people do instead in these situations is download data from these services into a database they control and then use Metabase to access that database directly. This can be done either by writing code or more commonly using a third-party service. There are a large number of these services, and you can ask other users and discuss pros and cons at our [user forum](https://discourse.metabase.com).
### Can I upload data to Metabase?
Not exactly. Metabase provides access to data you have in an existing database you control. We currently do not add or modify the information in your database. You should ask whomever controls the database you are accessing how to upload the data you're interested in accessing.
## Support and troubleshooting
### Can you help me debug something?
Yes, to the extent that we are able to and have time.
If you're sure you've found a bug, please [open an issue](https://github.com/metabase/metabase/issues/new/choose). Otherwise, try checking out the [troubleshooting guide](troubleshooting/start.md) first to see if the answer to your problem is there.
If you're still having trouble, please start a conversation at our [discussion forum](https://discourse.metabase.com/) and check out the other threads. Someone else might have experienced the same problem.
### Do you offer paid support?
We are experimenting with offering paid support to a limited number of companies. [Contact us](https://metabase.com/contact/) if you want more information.
## Embedding
### Can I embed charts or dashboards in another application?
Yes, Metabase offers two solutions for sharing charts and dashboards:
- [Public links](administration-guide/12-public-links.md) let you share or embed charts with simplicity.
- A powerful [application embedding](administration-guide/13-embedding.md) let you to embed and customize charts in your own web applications.
This page has been moved [here](./faq/start.md).
docs/faq/general/how-do-i-ask-for-help.md
+ 2
− 0
View file @ 9bf90b61
......@@ -3,3 +3,5 @@
The best place to start when asking for help are our [Troubleshooting guides](../../troubleshooting-guide/index.md). We’ve compiled a list of common problems that users experience, along with common symptoms and error messages to help you self-diagnose and resolve your issues.
As hard as we’ve tried to make the documentation as complete as possible, we know that you might need additional help or have a general question about Metabase not answered here. The best way to get help in these cases is to post on our [Discourse](https://discourse.metabase.com/) and harness the power of our community to get your question answered.
If you're using the Enterprise Edition, then please contact support via email or use the [contact form](https://www.metabase.com/contact/).
docs/faq/setup/which-databases-does-metabase-support.md
+ 14
− 14
View file @ 9bf90b61
......@@ -2,18 +2,18 @@
The following databases are officially supported by Metabase:
* BigQuery
* Druid
* Google Analytics
* H2
* MongoDB
* MySQL
* PostgreSQL
* Presto
* Amazon Redshift
* Snowflake
* Spark SQL
* SQLite
* SQL Server
- BigQuery
- Druid
- Google Analytics
- H2
- MongoDB
- MySQL/MariaDB
- PostgreSQL
- Presto
- Amazon Redshift
- Snowflake
- Spark SQL
- SQLite
- SQL Server
You may find some community-built database drivers for databases that we do not currently support - and you are always welcome to build your own!
You may find some [community-built database drivers](../../developers-guide-drivers.md) for databases that we do not currently support - and you are always welcome to build your own!
docs/faq/using-metabase/how-do-i-reset-my-password.md
+ 31
− 2
View file @ 9bf90b61
# How do I reset my password?
## How do I reset my password?
If you're having trouble logging in due to a forgotten password, click the `I seem to have forgotten my password` button in the lower right of the log-in screen. If your Metabase administrator has already [configured your email settings](../../administration-guide/02-setting-up-email.md), you will be able to generate a Reset Password email. If email has not been configured, you will need to contact them to perform a password reset.
### Using the Mac App
If you're running the MacOS application on your laptop, you can click on the Help menu item and click `Reset Password`.
### Using the web app as a normal user
If you're having trouble logging in due to a forgotten password, click the link that reads, "I seem to have forgotten my password" in the lower-right of the log-in screen. If your Metabase administrator has already [configured your email settings](../../administration-guide/02-setting-up-email.md), you'll receive a password reset email. If email has not been configured, you will need to contact a Metabase admin to perform a password reset via Admin Panel > People.
### Using the web app as an administrator
If you're the administrator of Metabase and have access to the server console, but have forgotten the password for your admin account, then you can get a reset token, which can be used to setup a new password.
To get the token, stop the running Metabase application, then start Metabase with the parameters `reset-password email@example.com` (where "email@example.com" is the email associated with the admin account).
Example: `java -jar metabase.jar reset-password email@example.com`
This will return a token and stop Metabase again, like this:
```
...
Resetting password for email@example.com...
OK [[[1_7db2b600-d538-4aeb-b4f7-0cf5b1970d89]]]
```
Now start Metabase normally again and navigate to the URL where you're running it, with the following path appended: `/auth/reset_password/:token`, where ":token" is the token that was generated from the step above.
Example: `https://metabase.example.com/auth/reset_password/1_7db2b600-d538-4aeb-b4f7-0cf5b1970d89`
You should now see a page where you can input a new password for the admin account.
docs/operations-guide/migrating-from-h2.md
+ 2
− 2
View file @ 9bf90b61
......@@ -20,10 +20,10 @@ java -jar metabase.jar load-from-h2 /path/to/metabase.db # do not include .mv.db
It is expected that you will run the command against a brand-new (empty!) database; Metabase will handle all of the work of creating the database schema and migrating the data for you.
###### Notes
#### Notes
- Avoid upgrading and migrating at the same time, since it can cause problems with one of database schemas not matching.
- It is required that you can connect to the target MySQL or Postgres database in whatever environment you are running this migration command in. So, if you are attempting to move the data to a cloud database, make sure you take that into consideration.
- For MySQL or MariaDB, the minimum recommended version is MySQL 5.7.7 and MariaDB 10.2.2, while `utf8mb4` character set is required.
- For MySQL or MariaDB, the minimum recommended version is MySQL 5.7.7 and MariaDB 10.2.2, while `utf8mb4` character set is required and `innodb_large_prefix=ON`.
- The code that handles these migrations uses a Postgres SQL command that is only available in Postgres 9.4 or newer versions. Please make sure you Postgres database is version 9.4 or newer.
- H2 automatically adds a `.h2.db` or `.mv.db` extension to the database path you specify, so make sure the path to the DB file you pass to the command _does not_ include it. For example, if you have a file named `/path/to/metabase.db.h2.db`, call the command with `load-from-h2 /path/to/metabase.db`.
docs/troubleshooting-guide/bugs.md
+ 3
− 1
View file @ 9bf90b61
## Reporting a bug
If you come across something that looks like a bug, start by searching our [Github issues](https://github.com/metabase/metabase/issues) to see if it has already been reported. If it has, please let us know you're experiencing the same issue by reacting with a thumbs up emoji or adding a comment providing additional information.
If the bug has not yet been reported, go ahead and [open a bug report](https://github.com/metabase/metabase/issues/new/choose). We suggest collecting the following information to help us reproduce the issue:
......@@ -15,7 +17,7 @@ If the bug has not yet been reported, go ahead and [open a bug report](https://g
### Accessing the Metabase server logs
While you can always look for the logs Metabase leaves on your server file system (or however you collect logs), if you are logged into Metabase with an admin account, you can also access them from the gear drop down menu in the upper right hand corner -> Admin -> Troubleshooting -> Logs.
While you can always look for the logs Metabase leaves on your server file system (or however you collect logs), if you are logged into Metabase with an admin account you can also access them from the Logs tab in the Troubleshooting section of the Admin Panel. To get to the Admin Panel, click the gear icon in the top-right of Metabase.
### Checking for Javascript console errors
......
docs/troubleshooting-guide/datawarehouse.md
+ 3
− 27
View file @ 9bf90b61
......@@ -18,7 +18,6 @@ As silly as this sounds, occasionally database servers go down.
If you are using a hosted database service, go to its console and verify that its status is Green. If you have direct access to a command line interface, log in and make sure that it is up and running and accepting queries.
#### How to fix this:
It's out of the scope of this troubleshooting guide to get your data warehouse server back up. Check with whomever set it up for you!
......@@ -78,9 +77,10 @@ Fixing this depends on your specific setup. Here are some potentially helpful re
- [Heroku timeouts](https://devcenter.heroku.com/articles/request-timeout)
- [App Engine: Dealing with DeadlineExceededErrors](https://cloud.google.com/appengine/articles/deadlineexceedederrors)
### MySQL: Unable to log in with correct credentials
#### How to detect this
Metabase fails to connect to your MySQL server with the error message "Looks like the username or password is incorrect", but you are sure that the username and password is correct. You may have created the MySQL user with an allowed host other than that which you are connecting from.
For example, if the MySQL server is running in a Docker container, and your `metabase` user was created with `CREATE USER 'metabase'@'localhost' IDENTIFIED BY 'thepassword';`, the `localhost` will be resolved to the Docker container, and not the host machine, causing access to be denied.
......@@ -90,6 +90,7 @@ You can identify this issue, by looking in the Metabase server logs for the erro
You will see the same error message when attempting to connect to the MySQL server with the command-line client: `mysql -h 127.0.0.1 -u metabase -p`
#### How to fix this
Recreate the MySQL user with the correct host name: `CREATE USER 'metabase'@'172.17.0.1' IDENTIFIED BY 'thepassword';`. Otherwise, if necessary, a wildcard may be used for the host name: `CREATE USER 'metabase'@'%' IDENTIFIED BY 'thepassword';`
That user's permissions will need to be set:
......@@ -101,29 +102,6 @@ FLUSH PRIVILEGES;
Remember to `DROP USER 'metabase'@'localhost';` the old user.
### MySQL: Unable to log in to MySQL 8 with correct credentials
#### How to detect this
Metabase fails to connect to your MySQL 8 server with the error message "Looks like the username or password is incorrect", and the Metabase server logs include the error message `Access denied for user 'metabase'@'172.17.0.1' (using password: NO)`. Note the `using password: NO` at the end.
You may still be able to successfully connect to the server using another MySQL client, such as the command-line client: `mysql -h 127.0.0.1 -u metabase -p`
#### How to fix this
Change the authentication plugin used by the Metabase user to `mysql_native_password`: `ALTER USER 'metabase'@'%' IDENTIFIED WITH mysql_native_password BY 'thepassword';`
This is necessary because the MariaDB connector, used by Metabase to connect to MySQL servers, unfortunately does not support MySQL 8's default authentication plugin. From [StackOverflow](https://stackoverflow.com/a/54190598):
> MySQL 8 uses caching_sha2_password rather than mysql_native_password as of MySQL 5.7 (and MariaDB).
>
> "caching_sha2_password, it is as of MySQL 8.0 the preferred authentication plugin, and is also the default authentication plugin rather than mysql_native_password. This change affects both the server and the libmysqlclient client library:"
>
> https://dev.mysql.com/doc/refman/8.0/en/upgrading-from-previous-series.html#upgrade-caching-sha2-password
>
> MariaDB's Java Connector does not yet implement this, but has a task assigned:
>
> https://jira.mariadb.org/browse/CONJ-663
### Error message: "Connections cannot be acquired from the underlying database!"
#### How to detect this
......@@ -133,5 +111,3 @@ Metabase fails to connect to your data warehouse and the Metabase server logs in
#### How to fix this
Navigate to the options for your data warehouse and locate the Additional JDBC Connection Strings option, then add `trustServerCertificate=true` as an additional string.
docs/troubleshooting-guide/loggingin.md
+ 11
− 14
View file @ 9bf90b61
......@@ -6,6 +6,10 @@
## Specific Problems:
### Forgotten Password
[This FAQ](../faq/using-metabase/how-do-i-reset-my-password.md) will tell you what to do in the event of a forgotten password.
### Invalid Google Auth Token:
Sometimes your token from Google will expire.
......@@ -20,24 +24,17 @@ Also open up your server logs, and see if there are any errors related to authen
Remove the old token from the Google Auth SSO tab in the Admin Panel and create a new one. If the root cause was an invalid auth token, this should fix the problem.
### Forgotten Password
[This FAQ](../faq/using-metabase/how-do-i-reset-my-password.md) will tell you what to do in the event of a forgotten password.
## Helpful tidbits
### Accessing the Metabase server logs
While you can always look for the logs Metabase leaves on your server file system (or however you collect logs), if you are logged into Metabase with an admin account, you can view the server logs as well as task and job logs in the Admin Panel by clicking the Troubleshooting tab in the nav bar.
### Checking for JavaScript errors in your web browser
While you can always look for the logs Metabase leaves on your server file system (or however you collect logs), if you are logged into Metabase with an admin account you can also access them from the Logs tab in the Troubleshooting section of the Admin Panel. To get to the Admin Panel, click the gear icon in the top-right of Metabase.
Metabase will print debugging information and errors to your browser's JavaScript Console.
### Checking for Javascript console errors
You can open the JavaScript console by following the instructions for your specific browser:
Metabase will send debugging information and errors to your browser's developer console. To open the developer console, follow the instructions for your web browser of choice:
- [Google Chrome](https://developers.google.com/web/tools/chrome-devtools/console/)
- [Mozilla Firefox](https://developer.mozilla.org/en-US/docs/Tools/Web_Console)
- [Safari](https://developer.apple.com/library/content/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/Introduction/Introduction.html)
- [Internet Explorer](<https://msdn.microsoft.com/en-us/library/gg589530(v=vs.85).aspx>) (On many versions of IE you can also access the console by pressing the F12 key on your keyboard.)
- [Microsoft Edge](https://docs.microsoft.com/en-us/microsoft-edge/f12-devtools-guide/console)
- [Chrome](https://developers.google.com/web/tools/chrome-devtools/open#console)
- [Firefox](https://developer.mozilla.org/en-US/docs/Tools/Web_Console/Opening_the_Web_Console)
- [Safari](https://support.apple.com/guide/safari-developer/develop-menu-dev39df999c1/mac)
- [Edge](https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium)
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment