Getting Started & Installation
Relevant source files
The following files were used as context for generating this wiki page:
The Meltano Singer SDK is a Python framework designed to streamline the creation of Singer-compliant taps (data extractors), targets (data loaders), and mappers (inline transformers). It provides a standardized architecture that significantly reduces the amount of boilerplate code required, typically by around 70%, while ensuring compatibility with the Singer Specification.
Sources: README.md:1-15, README.md:65-72
Prerequisites and Environment Setup
Development within the Meltano Singer SDK ecosystem requires Python 3.10 or higher. The project primarily utilizes uv for dependency management and environment synchronization.
System Requirements
| Component | Requirement |
|---|---|
| Python | 3.10 to 3.14 (3.14 is the primary development version) |
| Package Manager | uv (recommended) |
| Operating Systems | Windows, Linux, Darwin (macOS) |
Sources: CLAUDE.md:144, pyproject.toml:39, cookiecutter/tap-template/{{cookiecutter.tap_id}}/README.md:73-77
Development Environment Initialization
To set up a full development environment including all groups, extras, and workspace packages, the uv sync command is used.
# Initialize a development environment for the SDK
uv sync --all-groups --all-extras --all-packages
# Initialize a specific tap/target generated from a template
uv sync
Sources: CLAUDE.md:7-9, cookiecutter/tap-template/{{cookiecutter.tap_id}}/README.md:81
Plugin Architecture
The SDK is built on a series of abstract base classes that define the lifecycle of data extraction and loading.
The architecture uses specialized classes for different protocols: RESTStream and GraphQLStream for APIs, SQLStream for databases, and BatchSink for high-throughput data loading.
Sources: CLAUDE.md:118-124, cookiecutter/tap-template/{{cookiecutter.tap_id}}/AGENTS.md:18-25
Installation Procedures
Installing Taps and Targets
Taps and targets built with the SDK can be installed directly from PyPI or GitHub using uv tool.
# Install from PyPI
uv tool install tap-example
# Install from GitHub
uv tool install git+https://github.com/ORG_NAME/tap-example.git%40main
Sources: cookiecutter/tap-template/{{cookiecutter.tap_id}}/README.md:14-26, packages/meltano-tap-dummyjson/README.md:14-22
SDK Core Dependencies
The core SDK relies on several key libraries for its functionality:
- Networking:
requests,urllib3 - Data Handling:
jsonschema,simplejson,jsonpath-ng - Databases:
sqlalchemy - CLI/Utilities:
click,python-dotenv,python-backoff
Sources: pyproject.toml:41-62
Configuration and Usage
Plugins generated via the SDK support configuration through JSON files or environment variables.
Environment Variable Integration
The Singer tap/target will automatically import variables from a .env file if the --config=ENV flag is provided.
# Execute tap with environment variable configuration
tap-example --config ENV --discover > ./catalog.json
Sources: cookiecutter/tap-template/{{cookiecutter.tap_id}}/README.md:46-48, cookiecutter/tap-template/{{cookiecutter.tap_id}}/README.md:65
Discovery and Metadata
All SDK-based plugins provide built-in CLI commands to output metadata and supported settings.
| Command | Purpose |
|---|---|
--version | Display plugin version |
--about | List supported settings, capabilities, and descriptions |
--discover | Generate a catalog JSON describing available streams and schemas |
Sources: cookiecutter/tap-template/{{cookiecutter.tap_id}}/README.md:39-42, cookiecutter/tap-template/{{cookiecutter.tap_id}}/README.md:63-65
Development Workflow
When developing new plugins, the following flow is typically followed:
Testing Strategy
The SDK provides standard test suites that can be leveraged to verify compliance with the Singer specification.
# Run the plugin's core test suite
uv run pytest
# Run SDK-specific tests with nox
nox -s tests
Sources: CLAUDE.md:13-18, cookiecutter/tap-template/{{cookiecutter.tap_id}}/README.md:87, cookiecutter/tap-template/{{cookiecutter.tap_id}}/AGENTS.md:179-183
Summary
The Meltano Singer SDK provides the necessary tooling to quickly build, test, and deploy data connectors. By installing the uv tool and synchronizing the environment, developers gain access to a framework that handles the complexities of the Singer Specification—including state management, schema discovery, and pagination—allowing them to focus on source-specific logic.