{"id":750,"library":"db-dtypes","title":"Pandas Data Types for SQL Systems","description":"db-dtypes is a specialized Python library that provides Pandas Extension Dtypes to represent and interact with data types commonly found in relational databases, particularly BigQuery and Spanner. It aims to ensure data integrity and improve performance by providing faithful representations of types like Date, Time, and JSON. The library is actively maintained by Google, with multiple releases per year, and its current version is 1.5.0.","status":"active","version":"1.5.0","language":"python","source_language":"en","source_url":"https://github.com/googleapis/python-db-dtypes-pandas","tags":["pandas","sql","bigquery","spanner","data-types","google-cloud"],"install":[{"cmd":"pip install db-dtypes","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides the DataFrame and Series structures that db-dtypes extends with custom data types.","package":"pandas","optional":false},{"reason":"Enhances performance for reading and writing data, especially with BigQuery, by leveraging the Apache Arrow format.","package":"pyarrow","optional":false},{"reason":"Underlying dependency for pandas and array operations.","package":"numpy","optional":false}],"imports":[{"note":"Importing the module registers the extension dtypes with pandas. The '# noqa: F401' is often added to suppress 'unused import' warnings as the import's primary purpose is side-effect registration.","symbol":"db_dtypes","correct":"import db_dtypes # noqa: F401"},{"note":"While 'import db_dtypes' registers all, explicit import is for direct reference, e.g., in `pd.Series(dtype=DateDtype())`.","wrong":"import db_dtypes.DateDtype","symbol":"DateDtype","correct":"from db_dtypes import DateDtype"},{"symbol":"TimeDtype","correct":"from db_dtypes import TimeDtype"},{"symbol":"JSONDtype","correct":"from db_dtypes import JSONDtype"}],"quickstart":{"code":"import datetime\nimport pandas as pd\nimport db_dtypes # noqa: F401\n\n# Using dbdate dtype\ndates = pd.Series([datetime.date(2023, 1, 1), '2023-01-02'], dtype='dbdate')\nprint('Dates Series:')\nprint(dates)\n\n# Using dbtime dtype\ntimes = pd.Series([datetime.time(10, 30, 0), '15:45:00.123'], dtype='dbtime')\nprint('\\nTimes Series:')\nprint(times)\n\n# Using dbjson dtype\njson_data = pd.Series([{'key': 'value'}, [1, 2, 3], 'null'], dtype='dbjson')\nprint('\\nJSON Series:')\nprint(json_data)","lang":"python","description":"This quickstart demonstrates how to initialize pandas Series with custom `dbdate`, `dbtime`, and `dbjson` dtypes provided by the `db-dtypes` library. The initial `import db_dtypes` is crucial for registering these extension types with pandas."},"warnings":[{"fix":"Ensure your environment uses Python 3.9 or newer.","message":"Python 2 support was dropped as of January 1, 2020. The library currently requires Python >= 3.9. Older versions of the library (1.4.3 onwards) also explicitly dropped support for Python 3.7 and 3.8.","severity":"breaking","affected_versions":"<= 1.4.2 (for Python < 3.9); < 1.4.3 (for Python 3.7, 3.8)"},{"fix":"Update `google-cloud-bigquery` to a compatible version and ensure `db-dtypes` is installed. Remove `date_as_object` parameter if previously used.","message":"With `google-cloud-bigquery` version 3.0.0, `db-dtypes` became a required dependency for the `pandas` extra. BigQuery's `DATE` and `TIME` data types now map directly to `dbdate` and `dbtime` dtypes, and the `date_as_object` parameter was removed.","severity":"breaking","affected_versions":"google-cloud-bigquery >= 3.0.0"},{"fix":"Always include `import db_dtypes` at the beginning of your script or session. It's often accompanied by `# noqa: F401` to prevent linting warnings about unused imports.","message":"For `db-dtypes` extension types (like `dbdate`, `dbtime`, `dbjson`) to be recognized by pandas, the `db_dtypes` module must be imported at least once. This import performs the necessary registration of the custom dtypes.","severity":"gotcha","affected_versions":"All"},{"fix":"Be aware of the valid date range when processing historical or futuristic date data from BigQuery that uses the `dbdate` dtype, and handle `object` dtype columns appropriately if out-of-bounds dates are expected.","message":"When converting BigQuery `DATE` data to pandas `dbdate` dtype, any date values falling outside the range of `pandas.Timestamp.min` (1677-09-22) and `pandas.Timestamp.max` (2262-04-11) will map to the generic `object` dtype in pandas instead of `dbdate`.","severity":"gotcha","affected_versions":"All"},{"fix":"Rely on the integration with BigQuery connectors (e.g., `google-cloud-bigquery`) to handle `DECIMAL` types. If working with generic SQL and Pandas, consider explicit conversion to Python's `decimal.Decimal` objects or using other libraries that provide exact decimal dtypes.","message":"Standard Pandas `float64` can introduce precision errors when dealing with database `DECIMAL` or `NUMERIC` types. While `db-dtypes` aims to improve type fidelity, there isn't a direct `DecimalDtype` class for explicit import like `DateDtype`.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-05-12T18:34:52.662Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Install or upgrade the `db-dtypes` package using pip: `pip install --upgrade db-dtypes`. If using `google-cloud-bigquery`, installing with the pandas extra (`pip install 'google-cloud-bigquery[pandas]'`) can also ensure `db-dtypes` is present.","cause":"This error occurs when a function, often within a dependent library like `google-cloud-bigquery` or `pandas-gbq`, requires the `db-dtypes` package but it is either not installed, not installed in the active Python environment, or is an outdated version.","error":"ValueError: Please install the 'db-dtypes' package to use this function."},{"fix":"Use the correct package name with a hyphen: `pip install db-dtypes`.","cause":"This is not an error message but a common incorrect command that leads to installation problems because the package name `db-dtypes` contains a hyphen, which is omitted in this command. Python's `pip` interprets 'db' and 'dtypes' as two separate packages.","error":"pip install db dtypes"},{"fix":"Ensure `numpy` and `db-dtypes` are compatible. It's often resolved by updating both packages: `pip install --upgrade numpy db-dtypes`. Check the documentation for specific version requirements if the issue persists.","cause":"This `AttributeError` typically arises from an incompatibility between `db-dtypes` (or a library that depends on it, such as `bigframes`) and the installed version of `numpy`, where a required `numpy` attribute or function is missing or has been renamed in the current `numpy` version.","error":"AttributeError: module 'numpy' has no attribute 'dtypes'"},{"fix":"Explicitly specify `db-dtypes` extension types when loading data using the `dtype` parameter in Pandas functions (e.g., `pd.read_sql(..., dtype={'my_decimal_col': 'db_decimal'})`) or by converting the column type after loading (`df['my_decimal_col'] = df['my_decimal_col'].astype('db_decimal')`). Also, ensure `import db_dtypes # noqa` is in your code to register the extension dtypes.","cause":"Pandas' default type inference may convert database-specific types (like BigQuery's `DECIMAL` or `NUMERIC`) to standard Pandas dtypes (e.g., `float64`), which can lead to precision loss or incorrect data representation if `db-dtypes` extension types are not explicitly used.","error":"Unexpected Pandas dtype after loading from DB (e.g., float64 instead of DecimalDtype) or Data precision loss"}],"ecosystem":"pypi","meta_description":null,"install_score":80,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"1.6.0","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":null,"pypi_latest":"1.6.0","is_stale":null,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"db-dtypes","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"340.3M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"db-dtypes","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"334.9M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"db-dtypes","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":10.1,"import_time_s":null,"mem_mb":null,"disk_size":"309M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"db-dtypes","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"304M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"db-dtypes","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"364.3M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"db-dtypes","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"358.7M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"db-dtypes","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":9.1,"import_time_s":null,"mem_mb":null,"disk_size":"332M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"db-dtypes","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"328M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"db-dtypes","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"348.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"db-dtypes","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"343.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"db-dtypes","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":9.8,"import_time_s":null,"mem_mb":null,"disk_size":"316M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"db-dtypes","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"312M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"db-dtypes","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"347.9M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"db-dtypes","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"342.3M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"db-dtypes","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":9.9,"import_time_s":null,"mem_mb":null,"disk_size":"315M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"db-dtypes","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"311M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"db-dtypes","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"329.4M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"db-dtypes","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"329.2M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"db-dtypes","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":11,"import_time_s":null,"mem_mb":null,"disk_size":"307M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"db-dtypes","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"306M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}