Singer

Singer defines a standardized JSON message protocol (SCHEMA, RECORD, STATE, ACTIVATE_VERSION) that enables any data extraction tool (tap) to pipe output directly into any data loading tool (target) without custom integration code. Messages flow via stdout/stdin using Unix pipes, with each message type serving a specific function: SCHEMA defines table structure using JSON Schema, RECORD contains individual data rows, STATE checkpoints extraction progress for resumability, and ACTIVATE_VERSION manages versioning. This protocol-first design decouples extractors from loaders, allowing composition of 200+ community connectors without modification.

Singer taps emit STATE messages containing extraction progress metadata (e.g., last-synced timestamp, cursor position, offset) that targets write to persistent storage. On subsequent runs, taps read the previous STATE and resume extraction from that checkpoint rather than re-extracting all data. This pattern enables efficient incremental syncs without requiring the tap to maintain state itself — state is external and passed via messages. Taps can implement various incremental strategies: timestamp-based (modified_at > last_sync), cursor-based (id > last_id), or API-native pagination tokens, all serialized in the STATE message as JSON.

Singer taps and targets are configured via JSON config files (passed via `--config` flag) containing source/destination credentials, extraction parameters (e.g., table names, filters), and loading parameters (e.g., schema, batch size). Config files are tap/target-specific — there's no standardized schema. Credentials can also be passed via environment variables, allowing secure credential management without embedding secrets in config files. Orchestration tools (Airflow, Meltano) typically manage config file generation and environment variable injection. Config files are human-readable JSON, enabling version control and templating. No built-in encryption or secret management — credentials are stored as plaintext in config files or environment variables.

Singer taps and targets are standalone CLI executables that read/write JSON messages via stdin/stdout, enabling implementation in any programming language (Python, Node.js, Go, Rust, etc.). The framework does not mandate a language-specific SDK or runtime — only that the executable implements the Singer protocol specification. This is enforced by the Unix pipe model: a tap is invoked as `tap-name [args]` and outputs JSON to stdout; a target is invoked as `target-name [args]` and reads JSON from stdin. Community taps/targets are typically distributed as pip packages (Python) but can be any compiled binary or script.

Singer provides a curated directory of 200+ open-source, community-maintained data connectors (taps for extraction, targets for loading) covering SaaS APIs (Salesforce, HubSpot, Stripe, Shopify, Zendesk, Jira, GitHub), databases (MySQL, PostgreSQL, Oracle, DynamoDB), analytics platforms (Google Analytics, Mixpanel, Amplitude), and file sources (S3, SFTP, Google Sheets). These connectors are distributed as pip-installable Python packages and implement the Singer protocol, allowing users to compose pipelines without writing custom code. The ecosystem is maintained by the Singer community and Meltano (a Singer-based orchestration platform), with varying levels of maintenance (some actively updated, others community-supported).

Singer pipelines are constructed by piping a tap executable's stdout directly into a target executable's stdin using standard Unix shell pipes (e.g., `tap-salesforce | target-postgres`). The tap streams SCHEMA, RECORD, and STATE messages as JSON lines to stdout; the target reads these messages from stdin and loads data into the destination. This composition model requires no orchestration framework, configuration files, or intermediate storage — the pipe itself is the data transport. Multiple taps can be composed into a single target using shell redirection, and targets can be chained (though this is less common). The simplicity enables ad-hoc pipelines via command line or integration into shell scripts, Makefiles, or orchestration tools (Airflow, Meltano, etc.).

Singer taps emit SCHEMA messages containing a JSON Schema definition of the table structure (column names, data types, constraints) before emitting RECORD messages. Targets use this schema to validate incoming records, infer destination table structure, and handle type mapping (e.g., JSON Schema 'string' → PostgreSQL 'text'). The schema is embedded in the data stream, not stored separately, allowing targets to dynamically create tables or validate records without external schema artifacts. JSON Schema supports nested objects and arrays, enabling representation of complex data types. Targets can enforce strict schema validation (reject records with unexpected fields) or lenient validation (ignore extra fields), depending on implementation.

Developers can build custom Singer taps by implementing the Singer protocol specification: reading a config file (JSON with source credentials), emitting SCHEMA messages for each table, emitting RECORD messages for each row, and emitting STATE messages for incremental checkpoints. Taps must handle source-specific concerns: authentication (OAuth, API keys, database credentials), pagination (cursor-based, offset-based, keyset pagination), rate limiting, and error handling. Singer provides no framework scaffolding — developers implement these concerns directly in their tap code. Community libraries (e.g., singer-python for Python) provide utilities for JSON serialization and common patterns, but are optional. Taps are typically distributed as pip packages with a CLI entry point that accepts `--config`, `--state`, and `--catalog` arguments.

Developers can build custom Singer targets by implementing the Singer protocol specification: reading SCHEMA messages to infer destination table structure, reading RECORD messages to load data, and persisting STATE messages for resumable syncs. Targets must handle destination-specific concerns: data type mapping (JSON Schema types → destination database types), table creation/alteration, duplicate handling (idempotency), and error recovery. Singer provides no framework scaffolding — developers implement these concerns directly. Targets typically implement upsert logic (insert or update based on primary key) to handle duplicate records from resumed extractions. Targets are distributed as pip packages with a CLI entry point accepting `--config` argument.

Singer taps support two primary sync modes: full refresh (re-extract all data from source, ignoring previous STATE) and incremental (extract only new/changed data since last STATE checkpoint). Targets can be configured to replace existing data (full refresh mode) or merge with existing data (incremental mode). Full refresh is useful for initial data loads or when source data is small; incremental is essential for large sources where repeated full extracts are prohibitively expensive. Taps implement incremental logic by filtering source queries (e.g., WHERE modified_at > last_sync_time) or using pagination cursors; targets implement merge logic by upserting records based on primary keys. The choice between modes is typically made at pipeline invocation time (e.g., via command-line flags or orchestration tool configuration).

Singer pipelines can be invoked from external orchestration tools (Apache Airflow, Meltano, cron jobs, shell scripts) because taps and targets are CLI executables. Orchestration tools can invoke Singer pipelines via subprocess calls, passing configuration files and managing scheduling, error handling, and monitoring. Meltano (a Singer-based orchestration platform) provides native Singer integration with YAML-based pipeline definitions, environment variable management, and built-in tap/target discovery. Airflow can invoke Singer via BashOperator or custom operators. Cron jobs can invoke Singer pipelines via shell scripts. This flexibility allows Singer to integrate into existing data infrastructure without requiring a centralized Singer orchestration platform.