langgraph-checkpoint-oceanbase-es 3.0.0__tar.gz

langgraph_checkpoint_oceanbase_es-3.0.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv build *)"
+    ]
+  }
+}

langgraph_checkpoint_oceanbase_es-3.0.0/.github/workflows/_lint.yml

@@ -0,0 +1,83 @@
+name: lint
+
+on:
+  workflow_call
+
+env:
+  # This env var allows us to get inline annotations when ruff has complaints.
+  RUFF_OUTPUT_FORMAT: github
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # Only lint on the min and max supported Python versions.
+        # It's extremely unlikely that there's a lint issue on any version in between
+        # that doesn't show up on the min or max versions.
+        #
+        # GitHub rate-limits how many jobs can be running at any one time.
+        # Starting new jobs is also relatively slow,
+        # so linting on fewer versions makes CI faster.
+        python-version:
+          - "3.12"
+    name: "lint #${{ matrix.python-version }}"
+    steps:
+      - uses: actions/checkout@v6
+      - name: Get changed files
+        id: changed-files
+        uses: Ana06/get-changed-files@v2.3.0
+      - name: Set up Python ${{ matrix.python-version }}
+        if: steps.changed-files.outputs.all
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-suffix: lint-${{ inputs.working-directory }}
+
+      - name: Install dependencies
+        if: steps.changed-files.outputs.all
+        run: uv sync --frozen --group dev
+
+      - name: Get .mypy_cache to speed up mypy
+        if: steps.changed-files.outputs.all
+        uses: actions/cache@v4
+        env:
+          SEGMENT_DOWNLOAD_TIMEOUT_MIN: "2"
+        with:
+          path: |
+            .mypy_cache
+          key: mypy-lint-${{ runner.os }}-${{ runner.arch }}-py${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}
+
+      - name: Analysing package code with our lint
+        if: steps.changed-files.outputs.all
+        run: |
+          if make lint_package > /dev/null 2>&1; then
+            make lint_package
+          else
+            echo "lint_package command not found, using lint instead"
+            make lint
+          fi
+
+      - name: Install test dependencies
+        if: steps.changed-files.outputs.all
+        run: uv sync --group dev
+
+      - name: Get .mypy_cache_test to speed up mypy
+        if: steps.changed-files.outputs.all
+        uses: actions/cache@v4
+        env:
+          SEGMENT_DOWNLOAD_TIMEOUT_MIN: "2"
+        with:
+          path: |
+            .mypy_cache_test
+          key: mypy-test-${{ runner.os }}-${{ runner.arch }}-py${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}
+
+      - name: Analysing tests with our lint
+        if: steps.changed-files.outputs.all
+        run: |
+          if make lint_tests > /dev/null 2>&1; then
+            make lint_tests
+          else
+            echo "lint_tests command not found, skipping step"
+          fi

langgraph_checkpoint_oceanbase_es-3.0.0/.github/workflows/_test.yml

@@ -0,0 +1,68 @@
+name: test
+
+on:
+  workflow_call
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        database:
+          - db: "mysql"
+            version: "9.5"
+          - db: "mysql"
+            version: "8"
+          - db: "mysql"
+            version: "8.0.19"
+          - db: "mariadb"
+            version: "11"
+          - db: "mariadb"
+            version: "10"
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+
+    name: "test python ${{ matrix.python-version }} | ${{ matrix.database.db }} ${{ matrix.database.version }}"
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-suffix: test-${{ inputs.working-directory }}
+
+      - name: Install dependencies
+        shell: bash
+        run: uv sync --frozen --group dev
+
+      - name: Run MySQL tests
+        if: ${{ matrix.database.db == 'mysql' }}
+        shell: bash
+        env:
+          MYSQL_VERSIONS: ${{ matrix.database.version }}
+        run: make test
+
+      - name: Run MariaDB tests
+        if: ${{ matrix.database.db == 'mariadb' }}
+        shell: bash
+        env:
+          MARIADB_VERSIONS: ${{ matrix.database.version }}
+        run: |
+          make test-mariadb
+
+      - name: Ensure the tests did not create any additional files
+        shell: bash
+        run: |
+          set -eu
+
+          STATUS="$(git status)"
+          echo "$STATUS"
+
+          # grep will exit non-zero if the target message isn't found,
+          # and `set -e` above will cause the step to fail.
+          echo "$STATUS" | grep 'nothing to commit, working tree clean'

langgraph_checkpoint_oceanbase_es-3.0.0/.github/workflows/_test_release.yml

@@ -0,0 +1,88 @@
+name: test-release
+
+on:
+  workflow_call
+
+env:
+  PYTHON_VERSION: "3.10"
+
+jobs:
+  build:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+
+    outputs:
+      pkg-name: ${{ steps.check-version.outputs.pkg-name }}
+      version: ${{ steps.check-version.outputs.version }}
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          enable-cache: true
+          cache-suffix: "release"
+
+      # We want to keep this build stage *separate* from the release stage,
+      # so that there's no sharing of permissions between them.
+      # The release stage has trusted publishing and GitHub repo contents write access,
+      # and we want to keep the scope of that access limited just to the release job.
+      # Otherwise, a malicious `build` step (e.g. via a compromised dependency)
+      # could get access to our GitHub or PyPI credentials.
+      #
+      # Per the trusted publishing GitHub Action:
+      # > It is strongly advised to separate jobs for building [...]
+      # > from the publish job.
+      # https://github.com/pypa/gh-action-pypi-publish#non-goals
+      - name: Build project for distribution
+        run: uv build
+
+      - name: Upload build
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-dist
+          path: dist/
+
+      - name: Check Version
+        id: check-version
+        shell: bash
+        run: |
+          echo pkg-name=$(grep -m 1 "^name = " pyproject.toml | cut -d '"' -f 2)
+          echo version=$(grep -m 1 "^version = " pyproject.toml | cut -d '"' -f 2)
+
+  publish:
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    permissions:
+      # This permission is used for trusted publishing:
+      # https://blog.pypi.org/posts/2023-04-20-introducing-trusted-publishers/
+      #
+      # Trusted publishing has to also be configured on PyPI for each package:
+      # https://docs.pypi.org/trusted-publishers/adding-a-publisher/
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: test-dist
+          path: dist/
+
+      - name: Publish to test PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          verbose: true
+          print-hash: true
+          repository-url: https://test.pypi.org/legacy/
+
+          # We overwrite any existing distributions with the same name and version.
+          # This is *only for CI use* and is *extremely dangerous* otherwise!
+          # https://github.com/pypa/gh-action-pypi-publish#tolerating-release-package-file-duplicates
+          skip-existing: true
+          # Temp workaround since attestations are on by default as of gh-action-pypi-publish v1.11.0
+          attestations: false

langgraph_checkpoint_oceanbase_es-3.0.0/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+---
+name: CI
+
+on:
+  push:
+    branches: [oceanbase-es]
+  pull_request:
+
+# If another push to the same PR or branch happens while this workflow is still running,
+# cancel the earlier run in favor of the next run.
+#
+# There's no point in testing an outdated version of the code. GitHub only allows
+# a limited number of job runners to be active at the same time, so it's better to cancel
+# pointless jobs early so that more useful jobs can run sooner.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    uses: ./.github/workflows/_lint.yml
+    secrets: inherit
+
+  test:
+    uses: ./.github/workflows/_test.yml
+    secrets: inherit
+
+  ci_success:
+    name: "CI Success"
+    needs: [lint, test]
+    if: |
+      always()
+    runs-on: ubuntu-latest
+    env:
+      JOBS_JSON: ${{ toJSON(needs) }}
+      RESULTS_JSON: ${{ toJSON(needs.*.result) }}
+      EXIT_CODE: ${{!contains(needs.*.result, 'failure') && !contains(needs.*.result, 'cancelled') && '0' || '1'}}
+    steps:
+      - name: "CI Success"
+        run: |
+          echo $JOBS_JSON
+          echo $RESULTS_JSON
+          echo "Exiting with $EXIT_CODE"
+          exit $EXIT_CODE

langgraph_checkpoint_oceanbase_es-3.0.0/.github/workflows/release.yml

@@ -0,0 +1,59 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Tag to release (e.g., v3.0.0)'
+        required: true
+        type: string
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/langgraph-checkpoint-oceanbase-es
+    permissions:
+      id-token: write  # Required for trusted publishing
+    
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        ref: ${{ github.event.inputs.tag || github.ref }}
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+    
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+    
+    - name: Build package
+      run: python -m build
+    
+    - name: Check package
+      run: twine check dist/*
+    
+    - name: Publish to PyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: twine upload dist/*
+    
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: python-package-distributions
+        path: dist/

langgraph_checkpoint_oceanbase_es-3.0.0/.gitignore

@@ -0,0 +1,3 @@
+.mypy_cache/
+__pycache__/
+.idea/

langgraph_checkpoint_oceanbase_es-3.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Theodore Ni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langgraph_checkpoint_oceanbase_es-3.0.0/Makefile

@@ -0,0 +1,99 @@
+.PHONY: test test_watch lint format
+
+######################
+# TESTING AND COVERAGE
+######################
+
+start-mysql:
+	MYSQL_VERSION=$(MYSQL_VERSION) docker compose -f tests/compose-mysql.yml up -V --force-recreate --wait || ( \
+    echo "Failed to start MySQL, printing logs..."; \
+		docker compose -f tests/compose-mysql.yml logs; \
+		exit 1 \
+  )
+
+stop-mysql:
+	docker compose -f tests/compose-mysql.yml down --remove-orphans -v
+
+MYSQL_VERSIONS ?= 8
+test_mysql_version:
+	@echo "Testing MySQL $(MYSQL_VERSION)"
+	@MYSQL_VERSION=$(MYSQL_VERSION) make start-mysql
+	@uv run pytest --ignore=langgraph-tests $(TEST) && \
+	uv run pytest -n auto --dist worksteal langgraph-tests || ( \
+	  EXIT_CODE=$$?; \
+	  make stop-mysql; \
+	  echo "Finished testing MySQL $(MYSQL_VERSION); Exit code: $$EXIT_CODE"; \
+	  exit $$EXIT_CODE \
+	)
+
+test:
+	@for version in $(MYSQL_VERSIONS); do \
+		if ! make test_mysql_version MYSQL_VERSION=$$version; then \
+			echo "Test failed for MySQL $$version"; \
+			exit 1; \
+		fi; \
+	done
+	@echo "All MySQL versions tested successfully"
+
+start-mariadb:
+	MARIADB_VERSION=$(MARIADB_VERSION) docker compose -f tests/compose-mariadb.yml up -V --force-recreate --wait || ( \
+    echo "Failed to start MariaDB, printing logs..."; \
+		docker compose -f tests/compose-mariadb.yml logs; \
+		exit 1 \
+  )
+
+stop-mariadb:
+	docker compose -f tests/compose-mariadb.yml down --remove-orphans -v
+
+MARIADB_VERSIONS ?= 10
+test_mariadb_version:
+	@echo "Testing MariaDB $(MARIADB_VERSION)"
+	@MARIADB_VERSION=$(MARIADB_VERSION) make start-mariadb
+	@uv run pytest --ignore=langgraph-tests $(TEST) && \
+	uv run pytest -n auto --dist worksteal langgraph-tests || ( \
+	  EXIT_CODE=$$?; \
+	  make stop-mariadb; \
+	  echo "Finished testing MariaDB $(MARIADB_VERSION); Exit code: $$EXIT_CODE"; \
+	  exit $$EXIT_CODE \
+	)
+
+test-mariadb:
+	@for version in $(MARIADB_VERSIONS); do \
+		if ! make test_mariadb_version MARIADB_VERSION=$$version; then \
+			echo "Test failed for MariaDB $$version"; \
+			exit 1; \
+		fi; \
+	done
+	@echo "All MariaDB versions tested successfully"
+
+TEST ?= .
+test_watch:
+	MYSQL_VERSION=$(MYSQL_VERSION) make start-mysql; \
+	uv run ptw $(TEST); \
+	EXIT_CODE=$$?; \
+	make stop-mysql; \
+	exit $$EXIT_CODE
+
+######################
+# LINTING AND FORMATTING
+######################
+
+# Define a variable for Python and notebook files.
+PYTHON_FILES=.
+MYPY_CACHE=.mypy_cache
+lint format: PYTHON_FILES=.
+lint_diff format_diff: PYTHON_FILES=$(shell git diff --name-only --relative --diff-filter=d main . | grep -E '\.py$$|\.ipynb$$')
+lint_package: PYTHON_FILES=langgraph
+lint_tests: PYTHON_FILES=tests
+lint_tests: MYPY_CACHE=.mypy_cache_test
+
+lint lint_diff lint_package lint_tests:
+	uv run ruff check .
+	[ "$(PYTHON_FILES)" = "" ] || uv run ruff format $(PYTHON_FILES) --diff
+	[ "$(PYTHON_FILES)" = "" ] || uv run ruff check --select I $(PYTHON_FILES)
+	[ "$(PYTHON_FILES)" = "" ] || mkdir -p $(MYPY_CACHE)
+	[ "$(PYTHON_FILES)" = "" ] || uv run mypy $(PYTHON_FILES) --cache-dir $(MYPY_CACHE)
+
+format format_diff:
+	uv run ruff format $(PYTHON_FILES)
+	uv run ruff check --select I --fix $(PYTHON_FILES)

langgraph_checkpoint_oceanbase_es-3.0.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: langgraph-checkpoint-oceanbase-es
+Version: 3.0.0
+Summary: Library with an OceanBase/MySQL implementation of LangGraph checkpoint saver with Elasticsearch vector search support.
+Project-URL: Repository, https://www.github.com/tjni/langgraph-checkpoint-mysql
+Author-email: Theodore Ni <dev@ted.bio>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: checkpoint,elasticsearch,langgraph,mysql,oceanbase,vector-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: langgraph-checkpoint>=2.1.2
+Requires-Dist: orjson>=3.10.1
+Requires-Dist: typing-extensions>=4.12.2
+Provides-Extra: aiomysql
+Requires-Dist: aiomysql>=0.2.0; extra == 'aiomysql'
+Provides-Extra: asyncmy
+Requires-Dist: asyncmy>=0.2.10; extra == 'asyncmy'
+Provides-Extra: pymysql
+Requires-Dist: pymysql>=1.1.1; extra == 'pymysql'
+Description-Content-Type: text/markdown
+
+# LangGraph Checkpoint MySQL
+
+Implementation of LangGraph CheckpointSaver that uses MySQL.
+
+> [!TIP]
+> The code in this repository tries to mimic the code in [langgraph-checkpoint-postgres](https://github.com/langchain-ai/langgraph/tree/main/libs/checkpoint-postgres) as much as possible to enable keeping in sync with the official checkpointer implementation.
+
+> [!NOTE]
+> In order to keep the queries close to the Postgres queries, we use features that require MySQL >= 8.0.19 or MariaDB >= 10.7.1.
+
+> [!NOTE]
+> MySQL >= 9.6.0 discontinued using the MD5 function in generated columns, but we have not created a migration path for this yet.
+
+## Dependencies
+
+- To use synchronous `PyMySQLSaver`, install `langgraph-checkpoint-mysql[pymysql]`.
+- To use asynchronous `AIOMySQLSaver`, install `langgraph-checkpoint-mysql[aiomysql]`.
+- To use asynchronous `AsyncMySaver`, install `langgraph-checkpoint-mysql[asyncmy]`.
+
+There is currently no support for other drivers.
+
+## Usage
+
+> [!IMPORTANT]
+> When using MySQL checkpointers for the first time, make sure to call `.setup()` method on them to create required tables. See example below.
+
+> [!IMPORTANT]
+> When manually creating MySQL connections and passing them to `PyMySQLSaver` or `AIOMySQLSaver`, make sure to include `autocommit=True`.
+>
+> **Why this parameter is required:**
+> - `autocommit=True`: Required for the `.setup()` method to properly commit the checkpoint tables to the database. Without this, table creation may not be persisted.
+
+```python
+from langgraph.checkpoint.mysql.pymysql import PyMySQLSaver
+
+write_config = {"configurable": {"thread_id": "1", "checkpoint_ns": ""}}
+read_config = {"configurable": {"thread_id": "1"}}
+
+DB_URI = "mysql://mysql:mysql@localhost:3306/mysql"
+with PyMySQLSaver.from_conn_string(DB_URI) as checkpointer:
+    # call .setup() the first time you're using the checkpointer
+    checkpointer.setup()
+    checkpoint = {
+        "v": 4,
+        "ts": "2024-07-31T20:14:19.804150+00:00",
+        "id": "1ef4f797-8335-6428-8001-8a1503f9b875",
+        "channel_values": {
+            "my_key": "meow",
+            "node": "node"
+        },
+        "channel_versions": {
+            "__start__": 2,
+            "my_key": 3,
+            "start:node": 3,
+            "node": 3
+        },
+        "versions_seen": {
+            "__input__": {},
+            "__start__": {
+            "__start__": 1
+            },
+            "node": {
+            "start:node": 2
+            }
+        },
+    }
+
+    # store checkpoint
+    checkpointer.put(write_config, checkpoint, {}, {})
+
+    # load checkpoint
+    checkpointer.get(read_config)
+
+    # list checkpoints
+    list(checkpointer.list(read_config))
+```
+
+### Async
+
+```python
+from langgraph.checkpoint.mysql.aio import AIOMySQLSaver
+
+async with AIOMySQLSaver.from_conn_string(DB_URI) as checkpointer:
+    checkpoint = {
+        "v": 4,
+        "ts": "2024-07-31T20:14:19.804150+00:00",
+        "id": "1ef4f797-8335-6428-8001-8a1503f9b875",
+        "channel_values": {
+            "my_key": "meow",
+            "node": "node"
+        },
+        "channel_versions": {
+            "__start__": 2,
+            "my_key": 3,
+            "start:node": 3,
+            "node": 3
+        },
+        "versions_seen": {
+            "__input__": {},
+            "__start__": {
+            "__start__": 1
+            },
+            "node": {
+            "start:node": 2
+            }
+        },
+    }
+
+    # store checkpoint
+    await checkpointer.aput(write_config, checkpoint, {}, {})
+
+    # load checkpoint
+    await checkpointer.aget(read_config)
+
+    # list checkpoints
+    [c async for c in checkpointer.alist(read_config)]
+```