finery 3.0.0

data/README.md

@@ -0,0 +1,1144 @@
+# Finery
+
+Explore your data with SQL. Easily create charts and dashboards, and share them with your team.
+
+## What exactly is this?
+
+Finery is a fork of [Blazer](https://github.com/ankane/blazer) with multiple new features and improvements.
+
+I use Blazer daily for personal projects, but I've felt like Blazer PRs take a long time to being merged and I really wanted a more frequently updated drop-in replacement.
+
+## Why is it called Finery?
+
+I've asked ChatGPT for name suggestions for a gem that is a fork of Blazer, but I wasn't happy with any of the results. Then I've asked it how would you call a fancier blazer and it suggested finery (which Merriam-Webster defines as _ornament, decoration, especially: dressy or showy clothing and jewels_). It's simple to type and easy to pronounce.
+
+## Should I send my PR here or to [ankane/blazer](https://github.com/ankane/blazer)?
+
+I'm keeping an eye on the open PRs and new code by @ankane. I plan on keeping the full compatibility with Blazer and if that ever changes I'll announce it with at least a couple months in advance.
+
+That being said I don't mind direct PRs to this repository, I'll try my best to review them as soon as I can. I reserve the right not to merge everything that got submitted to ankane/blazer, but if it gets accepted there I'll merge it here as well (with some possible changes to match Finery's code).
+
+[![Build Status](https://github.com/finery-bi/finery/workflows/build/badge.svg?branch=master)](https://github.com/finery-bi/finery/actions)
+
+## Features
+
+- **Multiple data sources** - PostgreSQL, MySQL, Redshift, and [many more](#full-list)
+- **Variables** - run the same queries with different values
+- **Checks & alerts** - get emailed when bad data appears
+- **Audits** - all queries are tracked
+- **Security** - works with your authentication system
+
+## Docs
+
+- [Installation](#installation)
+- [Queries](#queries)
+- [Charts](#charts)
+- [Dashboards](#dashboards)
+- [Checks](#checks)
+- [Cohorts](#cohorts)
+- [Anomaly Detection](#anomaly-detection)
+- [Forecasting](#forecasting)
+- [Uploads](#uploads)
+- [Data Sources](#data-sources)
+- [Query Permissions](#query-permissions)
+
+## Installation
+
+Add this line to your application’s Gemfile:
+
+```ruby
+gem "finery"
+```
+
+Run:
+
+```sh
+rails generate finery:install
+rails db:migrate
+```
+
+And mount the dashboard in your `config/routes.rb`:
+
+```ruby
+mount Finery::Engine, at: "finery"
+```
+
+For production, specify your database:
+
+```ruby
+ENV["BLAZER_DATABASE_URL"] = "postgres://user:password@hostname:5432/database"
+```
+
+When possible, Finery tries to protect against queries which modify data by running each query in a transaction and rolling it back, but a safer approach is to use a read-only user. [See how to create one](#permissions).
+
+#### Checks (optional)
+
+Be sure to set a host in `config/environments/production.rb` for emails to work.
+
+```ruby
+config.action_mailer.default_url_options = {host: "finery.dokkuapp.com"}
+```
+
+Schedule checks to run (with cron, [Heroku Scheduler](https://elements.heroku.com/addons/scheduler), etc). The default options are every 5 minutes, 1 hour, or 1 day, which you can customize. For each of these options, set up a task to run.
+
+```sh
+rake finery:run_checks SCHEDULE="5 minutes"
+rake finery:run_checks SCHEDULE="1 hour"
+rake finery:run_checks SCHEDULE="1 day"
+```
+
+You can also set up failing checks to be sent once a day (or whatever you prefer).
+
+```sh
+rake finery:send_failing_checks
+```
+
+Here’s what it looks like with cron.
+
+```
+*/5 * * * * rake finery:run_checks SCHEDULE="5 minutes"
+0   * * * * rake finery:run_checks SCHEDULE="1 hour"
+30  7 * * * rake finery:run_checks SCHEDULE="1 day"
+0   8 * * * rake finery:send_failing_checks
+```
+
+For Slack notifications, create an [incoming webhook](https://slack.com/apps/A0F7XDUAZ-incoming-webhooks) and set:
+
+```sh
+BLAZER_SLACK_WEBHOOK_URL=https://hooks.slack.com/...
+```
+
+Name the webhook “Finery” and add a cool icon.
+
+## Authentication
+
+Don’t forget to protect the dashboard in production.
+
+### Basic Authentication
+
+Set the following variables in your environment or an initializer.
+
+```ruby
+ENV["BLAZER_USERNAME"] = "andrew"
+ENV["BLAZER_PASSWORD"] = "secret"
+```
+
+### Devise
+
+```ruby
+authenticate :user, ->(user) { user.admin? } do
+  mount Finery::Engine, at: "finery"
+end
+```
+
+### Other
+
+Specify a `before_action` method to run in `finery.yml`.
+
+```yml
+before_action_method: require_admin
+```
+
+You can define this method in your `ApplicationController`.
+
+```ruby
+def require_admin
+  # depending on your auth, something like...
+  redirect_to root_path unless current_user && current_user.admin?
+end
+```
+
+Be sure to render or redirect for unauthorized users.
+
+## Permissions
+
+### PostgreSQL
+
+Create a user with read-only permissions:
+
+```sql
+BEGIN;
+CREATE ROLE finery LOGIN PASSWORD 'secret';
+GRANT CONNECT ON DATABASE dbname TO finery;
+GRANT USAGE ON SCHEMA public TO finery;
+GRANT SELECT ON ALL TABLES IN SCHEMA public TO finery;
+ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO finery;
+COMMIT;
+```
+
+### MySQL
+
+Create a user with read-only permissions:
+
+```sql
+CREATE USER 'finery'@'127.0.0.1' IDENTIFIED BY 'secret';
+GRANT SELECT, SHOW VIEW ON dbname.* TO 'finery'@'127.0.0.1';
+FLUSH PRIVILEGES;
+```
+
+## Sensitive Data
+
+If your database contains sensitive or personal data, check out [Hypershield](https://github.com/ankane/hypershield) to shield it.
+
+## Encrypted Data
+
+If you need to search encrypted data, use [blind indexing](https://github.com/ankane/blind_index).
+
+You can have Finery transform specific variables with:
+
+```ruby
+Finery.transform_variable = lambda do |name, value|
+  value = User.generate_email_bidx(value) if name == "email_bidx"
+  value
+end
+```
+
+## Queries
+
+### Variables
+
+Create queries with variables.
+
+```sql
+SELECT * FROM users WHERE gender = {gender}
+```
+
+Use `{start_time}` and `{end_time}` for time ranges. [Example](https://finery.dokkuapp.com/queries/9-time-range-selector?start_time=1997-10-03T05%3A00%3A00%2B00%3A00&end_time=1997-10-04T04%3A59%3A59%2B00%3A00)
+
+```sql
+SELECT * FROM ratings WHERE rated_at >= {start_time} AND rated_at <= {end_time}
+```
+
+### Smart Variables
+
+[Example](https://finery.dokkuapp.com/queries/1-smart-variable)
+
+Suppose you have the query:
+
+```sql
+SELECT * FROM users WHERE occupation_id = {occupation_id}
+```
+
+Instead of remembering each occupation’s id, users can select occupations by name.
+
+Add a smart variable with:
+
+```yml
+smart_variables:
+  occupation_id: "SELECT id, name FROM occupations ORDER BY name ASC"
+```
+
+The first column is the value of the variable, and the second column is the label.
+
+You can also use an array or hash for static data and enums.
+
+```yml
+smart_variables:
+  period: ["day", "week", "month"]
+  status: {0: "Active", 1: "Archived"}
+```
+
+### Linked Columns
+
+[Example](https://finery.dokkuapp.com/queries/3-linked-column) - title column
+
+Link results to other pages in your apps or around the web. Specify a column name and where it should link to. You can use the value of the result with `{value}`.
+
+```yml
+linked_columns:
+  user_id: "/admin/users/{value}"
+  ip_address: "https://www.infosniper.net/index.php?ip_address={value}"
+```
+
+### Smart Columns
+
+[Example](https://finery.dokkuapp.com/queries/2-smart-column) - occupation_id column
+
+Suppose you have the query:
+
+```sql
+SELECT name, city_id FROM users
+```
+
+See which city the user belongs to without a join.
+
+```yml
+smart_columns:
+  city_id: "SELECT id, name FROM cities WHERE id IN {value}"
+```
+
+You can also use a hash for static data and enums.
+
+```yml
+smart_columns:
+  status: {0: "Active", 1: "Archived"}
+```
+
+### Annotations
+
+Shows overlay lines or box ranges for line queries.
+
+Suppose your sales data and your deployments data, given a query:
+
+```sql
+SELECT date_trunc('hour', created_at), sum(value) FROM sales GROUP BY 1
+```
+
+You might want to see the influence of a deployment for those sales.
+
+```yml
+annotations:
+  deployments: SELECT date, name FROM deployments WHERE date BETWEEN {min_date} AND {max_date}
+```
+
+You can also show periods:
+
+```yml
+annotations:
+  holidays: SELECT min_date, max_date, name FROM holidays WHERE (min_date, max_date) OVERLAPS ({min_date}, {max_date})
+```
+
+Conditions for those queries are optional, but they will help to only fetch the relevant annotations for a particular chart.
+
+### Caching
+
+Finery can automatically cache results to improve speed. It can cache slow queries:
+
+```yml
+cache:
+  mode: slow
+  expires_in: 60 # min
+  slow_threshold: 15 # sec
+```
+
+Or it can cache all queries:
+
+```yml
+cache:
+  mode: all
+  expires_in: 60 # min
+```
+
+Of course, you can force a refresh at any time.
+
+## Charts
+
+Finery will automatically generate charts based on the types of the columns returned in your query.
+
+**Note:** The order of columns matters.
+
+### Line Chart
+
+There are two ways to generate line charts.
+
+2+ columns - timestamp, numeric(s) - [Example](https://finery.dokkuapp.com/queries/4-line-chart-format-1)
+
+```sql
+SELECT date_trunc('week', created_at), COUNT(*) FROM users GROUP BY 1
+```
+
+3 columns - timestamp, string, numeric - [Example](https://finery.dokkuapp.com/queries/5-line-chart-format-2)
+
+
+```sql
+SELECT date_trunc('week', created_at), gender, COUNT(*) FROM users GROUP BY 1, 2
+```
+
+### Column Chart
+
+There are also two ways to generate column charts.
+
+2+ columns - string, numeric(s) - [Example](https://finery.dokkuapp.com/queries/6-column-chart-format-1)
+
+```sql
+SELECT gender, COUNT(*) FROM users GROUP BY 1
+```
+
+3 columns - string, string, numeric - [Example](https://finery.dokkuapp.com/queries/7-column-chart-format-2)
+
+```sql
+SELECT gender, zip_code, COUNT(*) FROM users GROUP BY 1, 2
+```
+
+### Scatter Chart
+
+2 columns - both numeric - [Example](https://finery.dokkuapp.com/queries/16-scatter-chart)
+
+```sql
+SELECT x, y FROM table
+```
+
+### Pie Chart
+
+2 columns - string, numeric - and last column named `pie` - [Example](https://finery.dokkuapp.com/queries/17-pie-chart)
+
+```sql
+SELECT gender, COUNT(*) AS pie FROM users GROUP BY 1
+```
+
+### Maps
+
+Columns named `latitude` and `longitude` or `lat` and `lon` or `lat` and `lng` - [Example](https://finery.dokkuapp.com/queries/15-map)
+
+```sql
+SELECT name, latitude, longitude FROM cities
+```
+
+or a column named `geojson`
+
+```sql
+SELECT name, geojson FROM counties
+```
+
+To enable, get an access token from [Mapbox](https://www.mapbox.com/) and set `ENV["MAPBOX_ACCESS_TOKEN"]`.
+
+### Targets
+
+Use the column name `target` to draw a line for goals. [Example](https://finery.dokkuapp.com/queries/8-target-line)
+
+```sql
+SELECT date_trunc('week', created_at), COUNT(*) AS new_users, 100000 AS target FROM users GROUP BY 1
+```
+
+## Dashboards
+
+Create a dashboard with multiple queries. [Example](https://finery.dokkuapp.com/dashboards/1-dashboard-demo)
+
+If the query has a chart, the chart is shown. Otherwise, you’ll see a table.
+
+If any queries have variables, they will show up on the dashboard.
+
+## Checks
+
+Checks give you a centralized place to see the health of your data. [Example](https://finery.dokkuapp.com/checks)
+
+Create a query to identify bad rows.
+
+```sql
+SELECT * FROM ratings WHERE user_id IS NULL /* all ratings should have a user */
+```
+
+Then create check with optional emails if you want to be notified. Emails are sent when a check starts failing, and when it starts passing again.
+
+## Cohorts
+
+Create a cohort analysis from a simple SQL query. [Example](https://finery.dokkuapp.com/queries/19-cohort-analysis-from-first-order)
+
+Create a query with the comment `/* cohort analysis */`. The result should have columns named `user_id` and `conversion_time` and optionally `cohort_time`.
+
+You can generate cohorts from the first conversion time:
+
+```sql
+/* cohort analysis */
+SELECT user_id, created_at AS conversion_time FROM orders
+```
+
+(the first conversion isn’t counted in the first time period with this format)
+
+Or from another time, like sign up:
+
+```sql
+/* cohort analysis */
+SELECT users.id AS user_id, orders.created_at AS conversion_time, users.created_at AS cohort_time
+FROM users LEFT JOIN orders ON orders.user_id = users.id
+```
+
+This feature requires PostgreSQL or MySQL 8.
+
+## Anomaly Detection
+
+Finery supports three different approaches to anomaly detection.
+
+### Prophet
+
+Add [prophet-rb](https://github.com/ankane/prophet) to your Gemfile:
+
+```ruby
+gem "prophet-rb"
+```
+
+And add to `config/finery.yml`:
+
+```yml
+anomaly_checks: prophet
+```
+
+### Trend
+
+[Trend](https://trendapi.org/) uses an external service by default, but you can run it on your own infrastructure as well.
+
+Add [trend](https://github.com/ankane/trend) to your Gemfile:
+
+```ruby
+gem "trend"
+```
+
+And add to `config/finery.yml`:
+
+```yml
+anomaly_checks: trend
+```
+
+For the [self-hosted API](https://github.com/ankane/trend-api), create an initializer with:
+
+```ruby
+Trend.url = "http://localhost:8000"
+```
+
+### AnomalyDetection.rb
+
+Add [anomaly_detection](https://github.com/ankane/AnomalyDetection.rb) to your Gemfile:
+
+```ruby
+gem "anomaly_detection"
+```
+
+And add to `config/finery.yml`:
+
+```yml
+anomaly_checks: anomaly_detection
+```
+
+## Forecasting
+
+Finery supports for two different forecasting methods. [Example](https://finery.dokkuapp.com/queries/18-forecast?forecast=t)
+
+A forecast link will appear for queries that return 2 columns with types timestamp and numeric.
+
+### Prophet
+
+Add [prophet-rb](https://github.com/ankane/prophet) to your Gemfile:
+
+```ruby
+gem "prophet-rb", ">= 0.2.1"
+```
+
+And add to `config/finery.yml`:
+
+```yml
+forecasting: prophet
+```
+
+### Trend
+
+[Trend](https://trendapi.org/) uses an external service by default, but you can run it on your own infrastructure as well.
+
+Add [trend](https://github.com/ankane/trend) to your Gemfile:
+
+```ruby
+gem "trend"
+```
+
+And add to `config/finery.yml`:
+
+```yml
+forecasting: trend
+```
+
+For the [self-hosted API](https://github.com/ankane/trend-api), create an initializer with:
+
+```ruby
+Trend.url = "http://localhost:8000"
+```
+
+## Uploads
+
+Create database tables from CSV files. [Example](https://finery.dokkuapp.com/uploads)
+
+Run:
+
+```sh
+rails generate finery:uploads
+rails db:migrate
+```
+
+And add to `config/finery.yml`:
+
+```yml
+uploads:
+  url: postgres://...
+  schema: uploads
+  data_source: main
+```
+
+This feature requires PostgreSQL. Create a new schema just for uploads.
+
+```sql
+CREATE SCHEMA uploads;
+```
+
+## Data Sources
+
+Finery supports multiple data sources :tada:
+
+Add additional data sources in `config/finery.yml`:
+
+```yml
+data_sources:
+  main:
+    url: <%= ENV["BLAZER_DATABASE_URL"] %>
+    # timeout, smart_variables, linked_columns, smart_columns
+  catalog:
+    url: <%= ENV["CATALOG_DATABASE_URL"] %>
+    # ...
+  redshift:
+    url: <%= ENV["REDSHIFT_DATABASE_URL"] %>
+    # ...
+```
+
+### Full List
+
+- [Amazon Athena](#amazon-athena)
+- [Amazon Redshift](#amazon-redshift)
+- [Apache Drill](#apache-drill)
+- [Apache Hive](#apache-hive)
+- [Apache Ignite](#apache-ignite)
+- [Apache Spark](#apache-spark)
+- [Cassandra](#cassandra)
+- [ClickHouse](#clickhouse)
+- [Druid](#druid)
+- [Elasticsearch](#elasticsearch)
+- [Google BigQuery](#google-bigquery)
+- [IBM DB2 and Informix](#ibm-db2-and-informix)
+- [InfluxDB](#influxdb)
+- [MySQL](#mysql-1)
+- [Neo4j](#neo4j)
+- [OpenSearch](#opensearch)
+- [Oracle](#oracle)
+- [PostgreSQL](#postgresql-1)
+- [Presto](#presto)
+- [Salesforce](#salesforce)
+- [Socrata Open Data API (SODA)](#socrata-open-data-api-soda)
+- [Snowflake](#snowflake)
+- [SQLite](#sqlite)
+- [SQL Server](#sql-server)
+
+You can also [create an adapter](#creating-an-adapter) for any other data store.
+
+**Note:** In the examples below, we recommend using environment variables for urls.
+
+```yml
+data_sources:
+  my_source:
+    url: <%= ENV["BLAZER_MY_SOURCE_URL"] %>
+```
+
+### Amazon Athena
+
+Add [aws-sdk-athena](https://github.com/aws/aws-sdk-ruby) and [aws-sdk-glue](https://github.com/aws/aws-sdk-ruby) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    adapter: athena
+    database: database
+
+    # optional settings
+    output_location: s3://some-bucket/
+    workgroup: primary
+    access_key_id: ...
+    secret_access_key: ...
+    region: ...
+```
+
+Here’s an example IAM policy:
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Action": [
+                "athena:GetQueryExecution",
+                "athena:GetQueryResults",
+                "athena:StartQueryExecution"
+            ],
+            "Resource": [
+                "arn:aws:athena:region:account-id:workgroup/primary"
+            ]
+        },
+        {
+            "Effect": "Allow",
+            "Action": [
+                "glue:GetTable",
+                "glue:GetTables"
+            ],
+            "Resource": [
+                "arn:aws:glue:region:account-id:catalog",
+                "arn:aws:glue:region:account-id:database/default",
+                "arn:aws:glue:region:account-id:table/default/*"
+            ]
+        }
+    ]
+}
+```
+
+You also need to configure [S3 permissions](https://aws.amazon.com/premiumsupport/knowledge-center/access-denied-athena/).
+
+### Amazon Redshift
+
+Add [activerecord6-redshift-adapter](https://github.com/kwent/activerecord6-redshift-adapter) or [activerecord5-redshift-adapter](https://github.com/ConsultingMD/activerecord5-redshift-adapter) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    url: redshift://user:password@hostname:5439/database
+```
+
+Use a [read-only user](https://docs.aws.amazon.com/redshift/latest/dg/r_GRANT.html).
+
+### Apache Drill
+
+Add [drill-sergeant](https://github.com/ankane/drill-sergeant) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    adapter: drill
+    url: http://hostname:8047
+```
+
+Use a [read-only user](https://drill.apache.org/docs/roles-and-privileges/).
+
+### Apache Hive
+
+Add [hexspace](https://github.com/ankane/hexspace) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    adapter: hive
+    url: sasl://user:password@hostname:10000/database
+```
+
+Use a [read-only user](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+Authorization). Requires [HiveServer2](https://cwiki.apache.org/confluence/display/Hive/Setting+Up+HiveServer2).
+
+### Apache Ignite
+
+Add [ignite-client](https://github.com/ankane/ignite-ruby) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    url: ignite://user:password@hostname:10800
+```
+
+Use a [read-only user](https://www.gridgain.com/docs/latest/administrators-guide/security/authorization-permissions) (requires a third-party plugin).
+
+### Apache Spark
+
+Add [hexspace](https://github.com/ankane/hexspace) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    adapter: spark
+    url: sasl://user:password@hostname:10000/database
+```
+
+Use a read-only user. Requires the [Thrift server](https://spark.apache.org/docs/latest/sql-distributed-sql-engine.html).
+
+### Cassandra
+
+Add [cassandra-driver](https://github.com/datastax/ruby-driver) (and [sorted_set](https://github.com/knu/sorted_set) for Ruby 3+) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    url: cassandra://user:password@hostname:9042/keyspace
+```
+
+Use a [read-only role](https://docs.datastax.com/en/cql-oss/3.3/cql/cql_using/useSecurePermission.html).
+
+### ClickHouse
+
+Add [ClickHouse Ruby driver](https://github.com/shlima/click_house) to your Gemfile and set:
+```yml
+data_sources:
+  my_source:
+    adapter: clickhouse
+    url: http://user:password@hostname:8123/database
+
+    # optional settings
+    ssl_verify: true # false by default
+```
+>>>>>>> 41a6b49 (Added support for ClickHouse)
+
+### Druid
+
+Enable [SQL support](http://druid.io/docs/latest/querying/sql.html#configuration) on the broker and set:
+
+```yml
+data_sources:
+  my_source:
+    adapter: druid
+    url: http://hostname:8082
+```
+
+Use a [read-only role](https://druid.apache.org/docs/latest/development/extensions-core/druid-basic-security.html).
+
+### Elasticsearch
+
+Add [elasticsearch](https://github.com/elastic/elasticsearch-ruby) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    adapter: elasticsearch
+    url: http://user:password@hostname:9200
+```
+
+Use a [read-only role](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html).
+
+### Google BigQuery
+
+Add [google-cloud-bigquery](https://github.com/GoogleCloudPlatform/google-cloud-ruby/tree/master/google-cloud-bigquery) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    adapter: bigquery
+    project: your-project
+    keyfile: path/to/keyfile.json
+```
+
+### IBM DB2 and Informix
+
+Add [ibm_db](https://github.com/ibmdb/ruby-ibmdb) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    url: ibm-db://user:password@hostname:50000/database
+```
+
+Use a [read-only user](https://www.ibm.com/support/pages/creating-read-only-database-permissions-user).
+
+### InfluxDB
+
+Add [influxdb](https://github.com/influxdata/influxdb-ruby) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    adapter: influxdb
+    url: http://user:password@hostname:8086/database
+```
+
+Use a [read-only user](https://docs.influxdata.com/influxdb/v1.8/administration/authentication_and_authorization/). Supports [InfluxQL](https://docs.influxdata.com/influxdb/v1.8/query_language/explore-data/).
+
+### MySQL
+
+Add [mysql2](https://github.com/brianmario/mysql2) to your Gemfile (if it’s not there) and set:
+
+```yml
+data_sources:
+  my_source:
+    url: mysql2://user:password@hostname:3306/database
+```
+
+Use a [read-only user](#mysql).
+
+### Neo4j
+
+Add [neo4j-core](https://github.com/neo4jrb/neo4j-core) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    adapter: neo4j
+    url: http://user:password@hostname:7474
+```
+
+Use a [read-only user](https://neo4j.com/docs/cypher-manual/current/access-control/manage-privileges/).
+
+### OpenSearch
+
+Add [opensearch-ruby](https://github.com/opensearch-project/opensearch-ruby) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    adapter: opensearch
+    url: http://user:password@hostname:9200
+```
+
+Use a [read-only user](https://opensearch.org/docs/latest/security-plugin/access-control/permissions/).
+
+### Oracle
+
+Add [activerecord-oracle_enhanced-adapter](https://github.com/rsim/oracle-enhanced) and [ruby-oci8](https://github.com/kubo/ruby-oci8) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    url: oracle-enhanced://user:password@hostname:1521/database
+```
+
+Use a [read-only user](https://docs.oracle.com/cd/B19306_01/network.102/b14266/authoriz.htm).
+
+### PostgreSQL
+
+Add [pg](https://github.com/ged/ruby-pg) to your Gemfile (if it’s not there) and set:
+
+```yml
+data_sources:
+  my_source:
+    url: postgres://user:password@hostname:5432/database
+```
+
+Use a [read-only user](#postgresql).
+
+### Presto
+
+Add [presto-client](https://github.com/treasure-data/presto-client-ruby) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    url: presto://user@hostname:8080/catalog
+```
+
+Use a [read-only user](https://prestodb.io/docs/current/security/built-in-system-access-control.html).
+
+### Salesforce
+
+Add [restforce](https://github.com/restforce/restforce) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    adapter: salesforce
+```
+
+And set the appropriate environment variables:
+
+```sh
+SALESFORCE_USERNAME="username"
+SALESFORCE_PASSWORD="password"
+SALESFORCE_SECURITY_TOKEN="security token"
+SALESFORCE_CLIENT_ID="client id"
+SALESFORCE_CLIENT_SECRET="client secret"
+SALESFORCE_API_VERSION="41.0"
+```
+
+Use a read-only user. Supports [SOQL](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm).
+
+### Socrata Open Data API (SODA)
+
+Set:
+
+```yml
+data_sources:
+  my_source:
+    adapter: soda
+    url: https://soda.demo.socrata.com/resource/4tka-6guv.json
+    app_token: ...
+```
+
+Supports [SoQL](https://dev.socrata.com/docs/functions/).
+
+### Snowflake
+
+First, install ODBC. For Homebrew, use:
+
+```sh
+brew install unixodbc
+```
+
+For Ubuntu, use:
+
+```sh
+sudo apt-get install unixodbc-dev
+```
+
+For Heroku, use the [Apt buildpack](https://github.com/heroku/heroku-buildpack-apt) and create an `Aptfile` with:
+
+```text
+unixodbc-dev
+https://sfc-repo.snowflakecomputing.com/odbc/linux/2.21.5/snowflake-odbc-2.21.5.x86_64.deb
+```
+
+> This installs the driver at `/app/.apt/usr/lib/snowflake/odbc/lib/libSnowflake.so`
+
+Then, download the [Snowflake ODBC driver](https://docs.snowflake.net/manuals/user-guide/odbc-download.html). Add [odbc_adapter](https://github.com/localytics/odbc_adapter) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    adapter: snowflake
+    conn_str: Driver=/path/to/libSnowflake.so;uid=user;pwd=password;server=host.snowflakecomputing.com
+```
+
+Use a [read-only role](https://docs.snowflake.com/en/user-guide/security-access-control-configure.html).
+
+### SQLite
+
+Add [sqlite3](https://github.com/sparklemotion/sqlite3-ruby) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    url: sqlite3:path/to/database.sqlite3
+```
+
+### SQL Server
+
+Add [tiny_tds](https://github.com/rails-sqlserver/tiny_tds) and [activerecord-sqlserver-adapter](https://github.com/rails-sqlserver/activerecord-sqlserver-adapter) to your Gemfile and set:
+
+```yml
+data_sources:
+  my_source:
+    url: sqlserver://user:password@hostname:1433/database
+```
+
+Use a [read-only user](https://docs.microsoft.com/en-us/sql/relational-databases/security/authentication-access/getting-started-with-database-engine-permissions?view=sql-server-ver15).
+
+## Creating an Adapter
+
+Create an adapter for any data store with:
+
+```ruby
+class FooAdapter < Finery::Adapters::BaseAdapter
+  # code goes here
+end
+
+Finery.register_adapter "foo", FooAdapter
+```
+
+See the [Presto adapter](https://github.com/finery-bi/finery/blob/master/lib/finery/adapters/presto_adapter.rb) for a good example. Then use:
+
+```yml
+data_sources:
+  my_source:
+    adapter: foo
+    url: http://user:password@hostname:9200/
+```
+
+## Query Permissions
+
+Finery supports a basic permissions model.
+
+1. Queries without a name are unlisted
+2. Queries whose name starts with `#` are only listed to the creator
+3. Queries whose name starts with `*` can only be edited by the creator
+
+## Learn SQL
+
+Have team members who want to learn SQL? Here are a few great, free resources.
+
+- [The Data School](https://dataschool.com/learn-sql/)
+- [SQLBolt](https://sqlbolt.com/)
+
+## Useful Tools
+
+For an easy way to group by day, week, month, and more with correct time zones, check out [Groupdate.sql](https://github.com/ankane/groupdate.sql).
+
+## Standalone Version
+
+Looking for a standalone version? Check out [Ghost Finery](https://github.com/buren/ghost_finery).
+
+## Performance
+
+By default, queries take up a request while they are running. To run queries asynchronously, add to your config:
+
+```yml
+async: true
+```
+
+**Note:** Requires caching to be enabled. If you have multiple web processes, your app must use a centralized cache store like Memcached or Redis.
+
+```ruby
+config.cache_store = :mem_cache_store
+```
+
+## Archiving
+
+Archive queries that haven’t been viewed in over 90 days.
+
+```sh
+rake finery:archive_queries
+```
+
+## Content Security Policy
+
+If views are stuck with a `Loading...` message, there might be a problem with strict CSP settings in your app. This can be checked with Firefox or Chrome dev tools. You can allow Finery to override these settings for its controllers with:
+
+```yml
+override_csp: true
+```
+
+## Upgrading
+
+Note: Finery started as a fork of Blazer 3.0, so everything before that is strictly Blazer-only.
+
+### 3.0
+
+Maps now use Mapbox GL JS v1 instead of Mapbox.js, which affects Mapbox billing.
+
+### 2.6
+
+Custom adapters now need to specify how to quote variables in queries (there is no longer a default)
+
+```ruby
+class FooAdapter < Finery::Adapters::BaseAdapter
+  def quoting
+    :backslash_escape # single quote strings and convert ' to \' and \ to \\
+    # or
+    :single_quote_escape # single quote strings and convert ' to ''
+    # or
+    ->(value) { ... } # custom method
+  end
+end
+```
+
+### 2.3
+
+To archive queries, create a migration
+
+```sh
+rails g migration add_status_to_finery_queries
+```
+
+with:
+
+```ruby
+add_column :finery_queries, :status, :string
+Finery::Query.update_all(status: "active")
+```
+
+### 2.0
+
+To use Slack notifications, create a migration
+
+```sh
+rails g migration add_slack_channels_to_finery_checks
+```
+
+with:
+
+```ruby
+add_column :finery_checks, :slack_channels, :text
+```
+
+## History
+
+View the [changelog](https://github.com/finery-bi/finery/blob/master/CHANGELOG.md)
+
+## Thanks
+
+Finery uses a number of awesome open source projects, including [Rails](https://github.com/rails/rails/), [Vue.js](https://github.com/vuejs/vue), [jQuery](https://github.com/jquery/jquery), [Bootstrap](https://github.com/twbs/bootstrap), [Selectize](https://github.com/brianreavis/selectize.js), [StickyTableHeaders](https://github.com/jmosbech/StickyTableHeaders), [Stupid jQuery Table Sort](https://github.com/joequery/Stupid-Table-Plugin), and [Date Range Picker](https://github.com/dangrossman/bootstrap-daterangepicker).
+
+Demo data from [MovieLens](https://grouplens.org/datasets/movielens/).
+
+## Want to Make Finery Better?
+
+That’s awesome! Here are a few ways you can help:
+
+- [Report bugs](https://github.com/finery-bi/finery/issues)
+- Fix bugs and [submit pull requests](https://github.com/finery-bi/finery/pulls)
+- Write, clarify, or fix documentation
+- Suggest or add new features
+
+Check out the [dev app](https://github.com/finery-bi/finery-dev) to get started.