Local Datastore (FactDB)
FactDB is an embedded datastore built to handle massive data volumes within the PDP, making it the default choice for all new Permit customers. Designed specifically for scalability, FactDB overcomes the limitations of traditional solutions like OPA, whose native data handling struggles with large datasets required by organizations with tens of millions of users.
To achieve this, FactDB uses an embedded SQLite database stored directly in the PDP. During a permission check, it identifies the user and resource involved, queries the SQLite database to extract a targeted slice of relevant data, and sends this refined data to OPA for evaluation. This process ensures fast, efficient permission evaluations while maintaining the scalability needed to support enterprise-level use cases.
This feature is available under Early Access Program. Please contact with us on Slack for more information.
Enabling FactDB
By default, the Permit Environment has FactDB disabled. To use FactDB with your PDPs, you can enable it within the Permit Environment settings.
This version is available on PDP v0.7.0 and above. Please make sure to upgrade all PDPs in the environment to the latest version to use FactDB.
To enable FactDB in a Permit Environment, you'll need an API Key. Once you have it, follow these steps:
Allow FactDB on Permit.io Environment Settings
Update your environment settings to enable FactDB.
If you have existing settings in your environment, you must include them in the PATCH request. Check it using the following request:
Enable FactDB on your PDPs
Set the PDP_FACTDB_ENABLED=true
environment variable to enable FactDB on every PDP connected to the environment.
FactDB is currently an opt-in feature, requiring you to explicitly enable it on all PDPs in the environment. This is to allow environments to run both with FactDB and without it.
Running both FactDB and Legacy PDPs in the same environment
To simplify the migration process, you can run both FactDB-enabled PDPs and Legacy PDPs within the same environment. To achieve this, simply enable the following setting in the environment.
With this setting enabled, you can run both FactDB PDPs with PDP_FACTDB_ENABLED=true
and Legacy PDPs in the same environment.
We recommend you to migrate all your PDPs in the environment to FactDB. Please contact us on Slack for more information.
FactDB Architecture
When a PDP starts, FactDB downloads the latest snapshot and keeps it up-to-date by syncing with the Permit Cloud and other PDPs in the environment.
When the PDP receives a query, it retrieves the relevant data from FactDB and passes it to the OPA engine for policy evaluation.
PDP Offline Mode with FactDB
FactDB can be used in conjunction with the PDP Offline Mode feature.
When the PDP is in Offline Mode
, the FactDB will boot from the locally stored disk volume, preserved from previous runs.
Here is an example of how to start the PDP in Offline Mode
with FactDB enabled.
Create a volume for the PDP backup
Start a new PDP container with the volume attached at /app/backup
Let's try to run the container with no network and see how's the offline mode loads the FactsDB, the policies and configurations from the previous run.
Troubleshooting & Debugging
Refreshing Data
Each time the PDP starts, it downloads the latest snapshot from the Permit Cloud and saves it in the /app/backup/
directory.
Restarting the PDP ensures FactDB retrieves the most up-to-date data from the Permit Cloud.
Extracting Data
To extract the FactsDB store from the PDP, just mount the /app/backup
directory to your local machine and use the data locally.
Inside you can observe the data stored in the FactDB. Each database snapshot is stored in a dedicated SQLite fact.[id].db
file.
./pdp-backup
|-- policy_store_backup.json // When Offline Mode enabled
|-- pdp_cloud_config_backup.json // When Offline Mode enabled
|-- factdb
| |-- fact.[id].db
| |-- fact.[id].db-shm
| |-- fact.[id].db-wal
This file structure is internal and may be changed in the future.
Inspecting Data
You can use the SQLite3 CLI to inspect the data stored in FactDB.
We recommend you to not modify the data stored in the FactDB directly.
Here are the available table schemas:
To explore the data, you can query specific tables. For example, to view the contents of the role_assignments
table, run
the following commands:
The output will look something like this:
id actor role tenant resource
------------------------------------------- ------------ ------ ------- ---------------------
user:alice-admin-Blog:how-to-code user:alice admin default Blog:how-to-code
user:bob-editor-Blog:react-tutorial user:bob editor default Blog:react-tutorial
user:charlie-viewer-Comment:great-post user:charlie viewer default Comment:great-post
user:dan-admin-Blog:javascript-tips user:dan admin default Blog:javascript-tips
user:eve-editor-Blog:css-tricks user:eve editor default Blog:css-tricks
user:frank-viewer-Comment:very-helpful user:frank viewer default Comment:very-helpful
user:grace-admin-Blog:nodejs-guide user:grace admin default Blog:nodejs-guide
user:heidi-editor-Blog:html-basics user:heidi editor default Blog:html-basics
user:ivan-viewer-Comment:thanks-for-sharing user:ivan viewer default Comment:thanks-for-sharing
user:judy-admin-Blog:testing-in-js user:judy admin default Blog:testing-in-js
This table schema is internal and may be changed in the future.