This file documents any backwards-incompatible changes in Superset and assists people when migrating to a new version.
Security simplification (SIP-19), the following permission domains were simplified:
can_write. Old permissions will be automatically migrated to these new permissions and applied to all existing security Roles.
11499: Breaking change:
STORE_CACHE_KEYS_IN_METADATA_DB config flag added (default=
False) to write
CacheKey records to the metadata DB.
CacheKey recording was enabled by default previously.
11704 Breaking change: Jinja templating for SQL queries has been updated, removing default modules such as
random and enforcing static template values. To restore or extend functionality, use
11714: Logs significantly more analytics events (roughly double?), and when using DBEventLogger (default) could result in stressing the metadata database more.
11509: Config value
TABLE_NAMES_CACHE_CONFIG has been renamed to
DATA_CACHE_CONFIG, which will now also hold query results cache from connected datasources (previously held in
CACHE_CONFIG), in addition to the table names. If you will set
DATA_CACHE_CONFIG to a new cache backend different than your previous
CACHE_CONFIG, plan for additional cache warmup to avoid degrading charting performance for the end users.
11575 The Row Level Security (RLS) config flag has been moved to a feature flag. To migrate, add
ROW_LEVEL_SECURITY: True to the
FEATURE_FLAGS dict in
11259: config flag ENABLE_REACT_CRUD_VIEWS has been set to
True by default, set to
False if you prefer to the vintage look and feel. However, we may discontine support on the vintage list view in the future.
REDUCE_DASHBOARD_BOOTSTRAP_PAYLOAD feature flag has been removed after being set to True for multiple months.
11098: includes a database migration that adds a
uuid column to most models, and updates
Dashboard.position_json to include chart UUIDs. Depending on number of objects, the migration may take up to 5 minutes, requiring planning for downtime.
11172: Turning off language selectors by default as i18n is incomplete in most languages and requires more work. You can easily turn on the languages you want to expose in your environment in superset_config.py
11172: Breaking change: SQL templating is turned off by default. To turn it on set
ENABLE_TEMPLATE_PROCESSING to True on
FAB_UPDATE_PERMS config parameter is no longer required as the Superset application correctly informs FAB under which context permissions should be updated.
10674: Breaking change: PUBLIC_ROLE_LIKE_GAMMA was removed is favour of the new PUBLIC_ROLE_LIKE so it can be set to whatever role you want.
10590: Breaking change: this PR will convert iframe chart into dashboard markdown component, and remove all
markup slices (and support) from Superset. If you have important data in those slices, please backup manually.
10562: EMAIL_REPORTS_WEBDRIVER is deprecated use WEBDRIVER_TYPE instead.
10567: Default WEBDRIVER_OPTION_ARGS are Chrome-specific. If you're using FF, should be
10241: change on Alpha role, users started to have access to “Annotation Layers”, “Css Templates” and “Import Dashboards”.
10324: Facebook Prophet has been introduced as an optional dependency to add support for timeseries forecasting in the chart data API. To enable this feature, install Superset with the optional dependency
prophet or directly
pip install fbprophet.
10320: References to blacklst/whitelist language have been replaced with more appropriate alternatives. All configs refencing containing
BLACK have been replaced with
DENY. Affected config variables that need to be updated:
uuidpython package is not supported on Jinja2 anymore, only uuid functions are exposed eg:
10233: a change which deprecates the
ENABLE_FLASK_COMPRESS config option in favor of the Flask-Compress
COMPRESS_REGISTER config option which serves the same purpose.
10222: a change which changes how payloads are cached. Previous cached objects cannot be decoded and thus will be reloaded from source.
10034: a change which deprecates the public security manager
rejected_tables methods with the
raise_for_access method which also handles assertion logic for SQL tables.
10031: a change which renames the following public security manager methods:
can_access_datasource. Regrettably it is not viable to provide aliases for the deprecated methods as this would result in a name clash. Finally the
can_access_database) method signature has changed, i.e., the optional
schema argument no longer exists.
10030: a change which renames the public security manager
schemas_accessible_by_user method to
9786: with the upgrade of
werkzeug from version
werkzeug.contrib.cache module has been moved to a standalone package cachelib. For example, to import the
RedisCache class, please use the following import:
from cachelib.redis import RedisCache.
create view as functionality in the sqllab. This change will require the
query table migration and potential service downtime as that table has quite some traffic.
9572: a change which by default means that the Jinja
url_param context calls no longer need to be wrapped via
cache_key_wrapper in order to be included in the cache key. The
cache_key_wrapper function should only be required for Jinja add-ons.
8867: a change which adds the
tmp_schema_name column to the
query table which requires locking the table. Given the
query table is heavily used performance may be degraded during the migration. Scheduled downtime may be advised.
9238: the config option
TIME_GRAIN_FUNCTIONS has been renamed to
TIME_GRAIN_EXPRESSIONS to better reflect the content of the dictionary.
9218: SQLite connections have been disabled by default for analytics databases. You can optionally enable SQLite by setting
False. It is not recommended to change this setting, as arbitrary SQLite connections can lead to security vulnerabilities.
9133: Security list of permissions and list views has been disable by default. You can optionally enable them back again by setting the following config keys:
9173: Changes the encoding of the query source from an int to an enum.
9120: Changes the default behavior of ad-hoc sharing of queries in SQLLab to one that links to the saved query rather than one that copies the query data into the KVStore model and links to the record there. This is a security-related change that makes SQLLab query sharing respect the existing role-based access controls. Should you wish to retain the existing behavior, set two feature flags:
"KV_STORE": True will re-enable the
/kv/store/ endpoints, and
"SHARE_QUERIES_VIA_KV_STORE": True will tell the front-end to utilize them for query sharing.
filter_immune_filter_fields to favor dashboard scoped filter metadata
all_query_access favoring a white list approach. Since a new permission is introduced use
superset init to create and associate it by default to the
Admin role. Note that, by default, all non
Admin users will not be able to access queries they do not own.
8901: The datasource‘s update timestamp has been added to the query object’s cache key to ensure updates to datasources are always reflected in associated query results. As a consequence all previously cached results will be invalidated when updating to the next version.
row_level_security_filters table has been added, which is many-to-many with
ab_roles. The applicable filters are added to the sqla query, and the RLS ids are added to the query cache keys. If RLS is enabled in config.py (
ENABLE_ROW_LEVEL_SECURITY = True; by default, it is disabled), they can be accessed through the
Security menu, or when editting a table.
8732: Swagger user interface is now enabled by default. A new permission
show on SwaggerView is created by
superset init and given to the
Admin Role. To disable the UI, set
FAB_API_SWAGGER_UI = False on config.
8721: When using the cache warmup Celery task you should now specify the
SUPERSET_WEBSERVER_PROTOCOL variable in your configuration (probably either “http” or “https”). This defaults to “http”.
DRUID_IS_ACTIVE now defaults to False. To enable Druid-API-based functionality, override the
DRUID_IS_ACTIVE configuration variable by setting it to
True for your deployment.
8450: The time range picker now uses UTC for the tooltips and default placeholder timestamps (sans timezone).
8418: FLASK_APP / Worker App have changed. FLASK_APP should be updated to
superset.app:create_app() and Celery Workers should be started with
SIP_15_ENABLED now defaults to True which ensures that for all new SQL charts the time filter will behave like [start, end). Existing deployments should either disable this feature to keep the status quo or inform their users of this change prior to enabling the flag. The
SIP_15_GRACE_PERIOD_END option provides a mechanism for specifying how long chart owners have to migrate their charts (the default is indefinite).
8370: Deprecates the
HTTP_HEADERS variable in favor of
OVERRIDE_HTTP_HEADERS. To retain the same behavior you should use
OVERRIDE_HTTP_HEADERS instead of
HTTP_HEADERS will still work but may be removed in a future update.
We're deprecating the concept of “restricted metric”, this feature was not fully working anyhow.
clusters.cluster_name non-nullable. Depending on the integrity of the data, manual intervention may be required.
7848: If you are running redis with celery, celery bump to 4.3.0 requires redis-py upgrade to 3.2.0 or later.
7667: a change to make all Unix timestamp (which by definition are in UTC) comparisons refer to a timestamp in UTC as opposed to local time.
7653: a change which deprecates the table_columns.database_expression column. Expressions should be handled by the DB engine spec conversion, Python date format, or custom column expression/type.
The repo no longer contains translation binaries (
.mo) files. If you want translations in your build, you now have to run the command
babel-compile --target superset/translations as part of your builds
5451: a change which adds missing non-nullable fields to the
datasources table. Depending on the integrity of the data, manual intervention may be required.
5452: a change which adds missing non-nullable fields and uniqueness constraints (which may be case insensitive depending on your database configuration) to the
table_columns tables. Depending on the integrity of the data, manual intervention may be required.
fabmanager command line is deprecated since Flask-AppBuilder 2.0.0, use the new
flask fab <command> integrated with Flask cli.
SUPERSET_UPDATE_PERMS environment variable was replaced by
FAB_UPDATE_PERMS config boolean key. To disable automatic creation of permissions set
FAB_UPDATE_PERMS = False on config.
5453: a change which adds missing non-nullable fields and uniqueness constraints (which may be case insensitive depending on your database configuration) to the metrics and sql_metrics tables. Depending on the integrity of the data, manual intervention may be required.
7616: this bug fix changes time_compare deltas to correctly evaluate to the number of days prior instead of number of days in the future. It will change the data for advanced analytics time_compare so
1 year from 5/1/2019 will be calculated as 365 days instead of 366 days.
npm run backend-syncis deprecated and no longer needed, will fail if called
If you use
Presto, we've moved some dependencies that were in the main package as optional now. To get these packages, run
pip install superset[presto] and/or
pip install superset[hive] as required.
Similarly, if you use Celery's
thrift-sasl, those dependencies have now been made optional in our package, meaning you may have to install them in your environment post 0.31.0
boto3 / botocore was removed from the dependency list. If you use s3 as a place to store your SQL Lab result set or Hive uploads, you may have to rely on an alternate requirements.txt file to install those dependencies.
From 0.31.0 onwards, we recommend not using the npm package
yarn in favor of good old
npm install. While yarn should still work just fine, you should probably align to guarantee builds similar to the ones we use in testing and across the community in general.
India was removed from the “Country Map” visualization as the geojson file included in the package was very large
Support for Python 2 is deprecated, we only support >=3.6 from
Superset 0.28 deprecates the previous dashboard layout. While 0.27 offered a migration workflow to users and allowed them to validate and publish their migrated dashboards individually, 0.28 forces the migration of all dashboards through an automated db migration script. We do recommend that you take a backup prior to this migration.
Superset 0.28 deprecates the
median cluster label aggregator for mapbox visualizations. This particular aggregation is not supported on mapbox visualizations going forward.
Superset 0.28 upgrades
>=0.3, which includes a backwards-incompatible change:
g.user.is_active are now properties instead of methods.
superset workerCLI, which is a simple wrapper around the
celery workercommand, forcing you into crafting your own native
celery workercommand. Your command should look something like
celery worker --app=superset.sql_lab:celery_app --pool=gevent -Ofair
Superset 0.25.0 contains a backwards incompatible changes. If you run a production system you should schedule downtime for this upgrade.
The PRs bellow have more information around the breaking changes:
9825: Support for Excel sheet upload added. To enable support, install Superset with the optional dependency
4587 : a backward incompatible database migration that requires downtime. Once the db migration succeeds, the web server needs to be restarted with the new version. The previous version will fail
4565 : we‘ve changed the security model a bit where in the past you would have to define your authentication scheme by inheriting from Flask App Builder’s
from flask_appbuilder.security.sqla.manager import SecurityManager, you now have to derive Superset's own derivative
superset.security.SupersetSecurityManager. This can provide you with more hooks to define your own logic and/or defer permissions to another system as needed. For all implementation, you simply have to import and derive
SupersetSecurityManager in place of the
4835 : our
setup.py now only pins versions where required, giving you more latitude in using versions of libraries as needed. We do now provide a
requirements.txt with pinned versions if you want to run the suggested versions that
Superset builds and runs tests against. Simply
pip install -r requirements.txt in your build pipeline, likely prior to
pip install superset==0.25.0