Registry / database / dataset

dataset

JSON →
library2.0.0pypypi✓ verified 24d ago

The Python 'dataset' library (version 1.6.2) is a lightweight toolkit for simplified Python-based database access, abstracting away much of the direct SQL interaction. It enables reading and writing data in SQL data stores with an API designed to feel as straightforward as working with JSON files, offering features like implicit table and column creation, upserts, and convenient query helpers. Built on SQLAlchemy, it ensures compatibility with major databases such as SQLite, PostgreSQL, and MySQL. The library maintains a steady release cadence with bug fixes and feature enhancements.

pip install dataset
INSTALL
IMPORT
SIG · DATASET
D
dataset
databasepythonv2.0.0
Install
3.9s avg
Import
1081ms
Disk
44MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 1.144s · 46.5MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 3.9s · import 1.018s · 45MB
44MB installed
● package 44MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

dataset
import dataset

This quickstart demonstrates how to connect to a database (using an in-memory SQLite for simplicity), create a table implicitly, insert and update data, and query records using the `dataset` library.

import dataset import os # Connect to an in-memory SQLite database db = dataset.connect('sqlite:///:memory:') # Get a table reference; it will be created if it doesn't exist table = db['users'] # Insert new records; columns are created automatically table.insert(dict(name='John Doe', age=30, city='New York')) table.insert(dict(name='Jane Smith', age=25, city='London')) # Update an existing record table.update(dict(name='John Doe', age=31), ['name']) # Find all records all_users = table.all() print("All users:") for user in all_users: print(user) # Find one record by a specific field john = table.find_one(name='John Doe') print(f"\nJohn Doe's updated age: {john['age']}") # Find records with a filter london_users = table.find(city='London') print("\nUsers in London:") for user in london_users: print(user) # Using environment variable for database URL (example) # os.environ['DATABASE_URL'] = 'sqlite:///mydb.db' # db_env = dataset.connect() # print(f"\nConnected via env var to: {db_env.url}")
dataset --version
Debug
Known issues
breakingVersion 1.7.0 (released March 28, 2026, on GitHub, though not yet on PyPI at time of verification) introduces significant breaking changes. It requires Python 3.9+ and full support for SQLAlchemy 2.0+ (with backward compatibility to 1.4.0). The build system migrated to Hatchling, linting to Ruff, and testing to pytest. Users should review the Changelog for a full list of changes and potential migration steps.
fix
Upgrade Python to 3.9+ and SQLAlchemy to a compatible version (>=1.4.0, preferably 2.0+). Consult the official Changelog and migration guides.
affects: >=1.7.0
breakingAs of `dataset` version 1.0, the data export features (e.g., freezing data to CSV or JSON) were extracted into a separate, standalone package named `datafreeze`. Projects relying on these export capabilities will need to install and use `datafreeze` in addition to `dataset`.
fix
Install `datafreeze` separately (`pip install datafreeze`) and adjust code to use its API for data export functionality.
affects: >=1.0
gotchaDatabase-specific drivers (e.g., `psycopg2` for PostgreSQL, `mysqlclient` for MySQL) are NOT automatically installed with the `dataset` package. You must install the appropriate driver separately for the database backend you intend to use. SQLite is built into Python and does not require an additional driver.
fix
Install the required database driver using `pip install <driver_package_name>` (e.g., `pip install psycopg2-binary` for PostgreSQL, `pip install mysqlclient` for MySQL), or use the optional installation syntax like `pip install "dataset[postgresql]"`.
affects: All versions
gotchaFor configuring database connections, `dataset.connect()` can automatically use a database URL defined in the `DATABASE_URL` environment variable if no URL is explicitly passed. While convenient, ensure sensitive credentials in this environment variable are managed securely, especially in production environments.
fix
For production, use environment variables or a configuration management system to securely inject database credentials. For local development, pass the URL explicitly or ensure the environment variable is set safely.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'dataset'
The 'dataset' library is not installed in your Python environment, or there's a confusion with the similarly named 'datasets' library (often used for machine learning).
fix
Ensure you install the correct library using pip: `pip install dataset`.
sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) no such table: my_table
You are trying to access a table that does not exist in the connected database, either because it was never created (though 'dataset' creates tables implicitly on first insert if not specified) or its name is misspelled.
fix
Verify the table name is correct. If expecting implicit creation, ensure you perform an `insert()` operation first, or explicitly create it if working with an existing schema.
AttributeError: 'Table' object has no attribute 'something'
You are attempting to call a method or access an attribute on a `dataset.Table` object that does not exist or is misspelled according to the 'dataset' library's API.
fix
Consult the 'dataset' library documentation for the correct methods and attributes available on `Table` objects. For example, to find a record, use `table.find_one()` or `table.find()`, not a custom 'get' method.
OperationalError: cannot commit - no transaction is active
This error typically occurs when attempting to commit a database transaction outside of an active transaction block, often due to improper transaction management (e.g., trying to commit without first calling `begin()`, or after a previous transaction has already been committed or rolled back).
fix
Ensure transaction operations are correctly nested within `db.begin()` and `db.commit()` or `db.rollback()` calls. For example: `with db as tx: tx['mytable'].insert({'key': 'value'})` or manually: `db.begin(); db['mytable'].insert({'key': 'value'}); db.commit()`.
Upgrade
Version history
2.0.0latest on PyPI · released Apr 12, 2026
Audit
Dependencies
SQLAlchemyrequiredCore ORM dependency for database interaction.
psycopg2optionalRequired for PostgreSQL support.
mysql-dboptionalRequired for MySQL support.
datafreezeoptionalFor data export features, extracted into a separate package as of dataset v1.0.
Agent activity
22 hits · last 30 days
node
20
OpenAI (training)
1
Resources
dataset — pip install dataset · libregistry