A Stacktape relational database provisions a fully managed SQL database on AWS. Stacktape provisions the database, configures credentials, network access, backup retention, and maintenance windows. AWS RDS or Aurora runs the database operations — patching, automated backups, and recovery. You pick an engine (PostgreSQL, MySQL, MariaDB, or others) and deploy.
Pricing context: RDS instances start at ~$12/month (db.t4g.micro). Aurora instances start at ~$35/month (db.t3.small). Aurora Serverless v2 bills per ACU-hour with no minimum instance commitment.
When to use
Use a Stacktape relational database when your application needs a traditional SQL database with ACID transactions, relational data modeling, or compatibility with PostgreSQL, MySQL, or MariaDB client libraries. This covers most web applications, APIs, and backend services that store structured data.
Aurora Serverless v2 is the recommended engine for most new projects. It auto-scales compute, handles traffic spikes without manual intervention, and costs less than fixed instances during low-usage periods. If your workload is steady and predictable, standard RDS with a fixed instance size gives simpler cost forecasting.
When NOT to use
A relational database adds operational weight — schema migrations, connection pooling, and capacity planning. Consider alternatives when the data model doesn't need relational semantics:
- Key-value or document access patterns — use a DynamoDB table for single-digit-millisecond reads at any scale with zero capacity planning.
- Caching or ephemeral data — use Redis for session storage, rate limiting, or caching layers.
- Full-text search — use OpenSearch for search-heavy workloads with facets and relevance scoring.
- MongoDB compatibility — use MongoDB Atlas if your team already uses MongoDB or needs a document database.
If your data model is genuinely relational but you need to minimize fixed cost, Aurora Serverless v2 with minCapacity: 0.5 scales down to ~1 GB RAM and charges only for what you use.
Basic example
The simplest relational database configuration uses standard RDS with a fixed instance size. Store the password in a Stacktape secret using the $Secret() directive to keep it out of your config file.
This creates a PostgreSQL 16 database on a db.t4g.micro instance (~$12/month, 2 vCPU, 1 GB RAM). The default masterUserName is db_master_user. The default accessibility mode is internet, which lets anyone with credentials connect — fine for development.
Engine types
Stacktape supports three database engine families, each backed by a different AWS service tier. Pick the one that matches your workload's performance, cost, and operational requirements.
| Feature | RDS | Aurora | Aurora Serverless v2 |
|---|---|---|---|
| Scaling | Fixed instance | Fixed instances | Auto (0.5–128 ACUs) |
| High availability | Multi-AZ (doubles cost) | Built-in (3-AZ replication) | Built-in (3-AZ replication) |
| Read replicas | ✓ | ✓ | ✓ |
| Starting cost | ~$12/month | ~$35/month | Pay per ACU-hour |
| PostgreSQL | ✓ | ✓ | ✓ |
| MySQL | ✓ | ✓ | ✓ |
| MariaDB, Oracle, SQL Server | ✓ | ✕ | ✕ |
| Best for | Predictable workloads, non-Aurora engines | High-performance production | Most new projects |
Standard RDS
Standard RDS runs a single database instance with a fixed size. You pick an instance class (CPU/memory) and pay hourly. AWS handles patching, automated backups, and recovery. Available engine types: postgres, mysql, mariadb, oracle-ee, oracle-se2, sqlserver-ee, sqlserver-ex, sqlserver-se, and sqlserver-web. The corresponding TypeScript classes are RdsEnginePostgres, RdsEngineMysql, RdsEngineMariadb, RdsEngineOracleEE, RdsEngineOracleSE2, RdsEngineSqlServerEE, RdsEngineSqlServerEX, RdsEngineSqlServerSE, and RdsEngineSqlServerWeb.
Use RDS when you need MariaDB, Oracle, or SQL Server (which Aurora doesn't support), or when you want predictable hourly pricing on a fixed instance. RDS is also simpler to reason about — one instance, one price, no ACU math.
The instanceSize determines CPU, memory, and network capacity. Common choices:
| Instance | vCPU | RAM | Approximate cost |
|---|---|---|---|
db.t4g.micro | 2 | 1 GB | ~$12/month |
db.t4g.medium | 2 | 4 GB | ~$50/month |
db.r6g.large | 2 | 16 GB | ~$180/month |
The t family is burstable — good for development and variable workloads where CPU usage spikes occasionally but averages low. Burstable instances accumulate CPU credits during idle time and spend them during spikes; if your workload sustains high CPU for extended periods, the instance throttles. The r family is memory-optimized — better for steady production workloads where you need consistent performance. For production databases handling real traffic, start with db.t4g.medium and monitor CPU metrics; move to r family if you see sustained utilization above 60%.
Aurora
Aurora is a high-performance clustered database compatible with PostgreSQL or MySQL. Underneath, AWS Aurora replicates data across three availability zones automatically. If the primary instance fails, a read replica is promoted, usually within 30 seconds. Available engine types: aurora-postgresql and aurora-mysql, with corresponding classes AuroraEnginePostgresql and AuroraEngineMysql.
Use Aurora when you need high availability with fast failover, read replicas for distributing query load, or when your workload is large enough that Aurora's performance advantage over standard RDS justifies the higher per-instance cost. Aurora is not worth the premium for small development databases — use RDS or Aurora Serverless v2 instead.
The instances array defines the cluster topology. The first entry is the primary (writer) instance; subsequent entries are read replicas. Reads are load-balanced across all instances. Aurora instances start at ~$35/month for db.t3.small. A two-instance cluster (writer + reader) provides automatic failover — if the primary fails, the reader is promoted in seconds. Adding more readers distributes read traffic but does not improve write performance.
Aurora Serverless v2
Aurora Serverless v2 scales compute automatically from 0.5 to 128 ACUs in 0.5-ACU increments (~1 ACU ≈ 2 GB RAM). You pay only for the capacity consumed. Available engine types: aurora-postgresql-serverless-v2 and aurora-mysql-serverless-v2, with corresponding classes AuroraServerlessV2EnginePostgresql and AuroraServerlessV2EngineMysql.
This is the recommended engine for most new projects. It handles traffic spikes without manual intervention and costs less than fixed instances during quiet periods. The tradeoff is less predictable monthly costs — billing depends on actual usage, which varies. For development and staging stages, set minCapacity to 0.5 to minimize cost. For production, size maxCapacity to handle your expected peak traffic with headroom.
The minCapacity (default 0.5) controls how far down the database scales during idle periods. The maxCapacity (default 10) caps both compute scaling and cost. A maxCapacity of 16 provides up to ~32 GB RAM — enough for most production workloads. You can add read replicas with serverlessReadersCount (default 0, meaning writer only); each reader scales independently between the same min/max bounds.
vpc or scoping-workloads-in-vpc accessibility modes. The global default is internet, which is not valid for Aurora Serverless v2 — you must set one of the VPC modes explicitly. Standard RDS and provisioned Aurora support all four modes including internet.Aurora Serverless v1 is retired
AWS retired Aurora Serverless v1 on 31 March 2025, and Stacktape v4 no longer deploys it. The aurora-postgresql-serverless and aurora-mysql-serverless engine types fail validation with a migration error. Use the Serverless v2 engines above. Serverless v2 does not pause when idle; it scales down to minCapacity (0.5 ACU at the lowest). To move a deployed v1 database, follow Upgrading from v3.
Database name and port
The dbName property sets the name of the database created when the instance first launches. For Aurora and Aurora Serverless engines, the default is defdb. For standard RDS, no default database is created unless you specify dbName explicitly. For Oracle engines, dbName sets the SID. The dbName property is not applicable to SQL Server engines.
The port property overrides the default listening port. Most users should leave port unchanged unless integrating with tooling that requires a non-default port. Default ports by engine:
| Engine | Default port |
|---|---|
| PostgreSQL, Aurora PostgreSQL | 5432 |
| MySQL, MariaDB, Aurora MySQL | 3306 |
| Oracle | 1521 |
| SQL Server | 1433 |
Aurora Serverless v2 engines do not expose a configurable port property — they use the default port for the underlying engine.
Supported versions
The version property on each engine specifies the database compatibility version. Supported versions are engine-specific and updated by AWS over time. Here are some current examples:
| Engine | Example versions |
|---|---|
| PostgreSQL (RDS) | 18.1, 17.7, 16.11 |
| MySQL (RDS) | 8.4.8, 8.0.45 |
| MariaDB (RDS) | 11.8.5, 11.4.9, 10.11.15 |
| Aurora PostgreSQL | 17.7, 16.11, 15.15 |
| Aurora MySQL | 8.0.mysql_aurora.3.11.1 |
| Aurora PostgreSQL Serverless v2 | 16.11, 15.15, 14.20 |
| Aurora MySQL Serverless v2 | 8.0.mysql_aurora.3.11.1 |
By default, minor version upgrades are applied automatically (e.g., PostgreSQL 16.10 to 16.11). Set disableAutoMinorVersionUpgrade: true on the engine to control upgrade timing manually.
Accessibility
Stacktape relational databases support four network access modes that control who can connect. The default is internet, which is the simplest for development but should be tightened for production.
| Mode | Who can connect | Best for |
|---|---|---|
internet (default) | Anyone with credentials | Development, quick prototyping |
vpc | Resources in the same VPC + whitelisted IPs | Shared dev environments |
scoping-workloads-in-vpc | Only resources with this DB in their connectTo | Production |
whitelisted-ips-only | Only listed IP addresses/CIDRs | External-only access |
For production, use scoping-workloads-in-vpc. This restricts network access to only the compute resources that explicitly declare a dependency on the database via connectTo. The database is still protected by username/password in all modes — accessibility controls the network layer on top of credentials. If you skip this for production, any client on the internet that guesses the credentials can connect.
In vpc and scoping-workloads-in-vpc modes, whitelistedIps adds external IP addresses on top of VPC access — useful for allowing connections from your office or CI environment. In whitelisted-ips-only mode, only listed IPs can connect. The whitelistedIps option has no effect in internet mode.
vpc or scoping-workloads-in-vpc modes. Standard RDS and provisioned Aurora support all four modes.The forceDisablePublicIp option removes the database's public IP entirely (VPC-only access). For Aurora, this can only be set at creation time and cannot be changed later.
Credentials
Every relational database requires a masterUserPassword. The masterUserName defaults to db_master_user. Store the password in a Stacktape secret using $Secret() to keep it out of your config file and version control.
masterUserName after the database is created replaces the database and deletes all data. Choose a username before your first deploy and do not change it afterward.Avoid special characters in both username and password: []{}(),;?*=!@. These characters can cause issues with connection string parsing in many database drivers and ORMs.
High availability and read replicas
How you achieve high availability depends on your engine type. Each approach has different cost and operational tradeoffs.
Standard RDS supports multiAz on the primary instance. This creates a standby replica in a second availability zone. If the primary fails, traffic fails over to the standby automatically. Multi-AZ also reduces downtime during maintenance windows. It doubles the instance cost but is worth it for any production database where downtime costs more than the mirror instance price.
Aurora replicates data across three availability zones by default. Add read replicas by including more entries in the instances array. If the primary fails, a replica is promoted automatically. Unlike RDS multi-AZ, Aurora replicas serve read traffic — you pay for additional instances but get both failover and read scaling.
Aurora Serverless v2 also replicates across three AZs. Add read replicas with serverlessReadersCount. Each reader scales independently, which means idle readers cost very little (0.5 ACU minimum). This makes Aurora Serverless v2 replicas significantly cheaper than provisioned Aurora replicas at low utilization.
For standard RDS, you can also add readReplicas to offload read traffic. Each replica gets its own endpoint, and data is replicated asynchronously from the primary. Read replicas are separate instances that add cost proportional to their size.
Connecting from workloads
Use connectTo to give your compute resources access to a database. Stacktape opens network access (security group rules) and injects environment variables with connection details.
For workload connectTo, Stacktape injects STP_MAIN_DATABASE_CONNECTION_STRING, STP_MAIN_DATABASE_HOST, and STP_MAIN_DATABASE_PORT; Aurora also injects STP_MAIN_DATABASE_READER_CONNECTION_STRING and STP_MAIN_DATABASE_READER_HOST. For scripts in the scripts section, script connectTo also injects JDBC variants: STP_MAIN_DATABASE_JDBC_CONNECTION_STRING and, for Aurora, STP_MAIN_DATABASE_READER_JDBC_CONNECTION_STRING. The $ResourceParam() directive exposes all referenceable parameters including jdbcConnectionString, dbName, and replica-specific endpoints.
Inside your handler, read the connection string from the environment:
The auto-generated connection string includes the database credentials and connection details. Most ORMs (Prisma, Drizzle, TypeORM) accept it directly. For cases that need individual parts (host, port, database name), use the $ResourceParam() directive or the dedicated environment variables listed above. All available parameters are listed in the Referenceable parameters section.
Storage
Storage configuration applies to standard RDS engines only — Aurora manages storage automatically and scales transparently up to 128 TB.
RDS storage defaults to 20 GB initial size (storage.initialSize) with auto-scaling up to 200 GB (storage.maxSize). When free space is low, AWS automatically expands the volume. You only pay for allocated storage, not the maximum. AWS RDS storage costs a few cents per GB/month (varies by region and storage type).
For write-heavy workloads or larger datasets, increase initialSize to avoid frequent auto-scaling events, which can briefly reduce I/O performance. Set maxSize to cap storage costs and prevent runaway growth from application bugs or data retention issues.
Logging
Database logs are sent to CloudWatch and retained for 90 days by default. Available log types depend on the engine:
| Engine | Available log types |
|---|---|
| PostgreSQL | postgresql |
| MySQL / MariaDB | audit, error, general, slowquery |
| Oracle | alert, audit, listener, trace |
| SQL Server | agent, error |
PostgreSQL supports fine-grained logging via engineSpecificOptions. The log_min_duration_statement option (default 10000 ms) logs queries slower than the threshold — set to 1000 (1 second) for production to surface the slowest queries without flooding logs. The log_statement option (default ddl) controls which SQL statements are logged. For PostgreSQL, log_statement can be none, ddl (CREATE/ALTER/DROP), mod (ddl + INSERT/UPDATE/DELETE), or all; use mod or all only when the audit value is worth the extra log volume. Additional options include log_connections, log_disconnections, and log_lock_waits for connection tracking and lock contention debugging.
MySQL supports server_audit_events (default ['QUERY_DDL']) to control what the audit log records. Supported values are CONNECT, QUERY, QUERY_DDL, QUERY_DML, QUERY_DML_NO_SELECT, and QUERY_DCL. Enabling QUERY or QUERY_DML logs every data operation and can generate significant log volume — use them for short-term audits rather than permanent monitoring. The long_query_time option (default 10 seconds) controls slow query detection.
View logs with stacktape logs or in the Stacktape Console.
Set logging.disabled to true to disable CloudWatch logging entirely — useful for cost-sensitive dev stages where you don't need persistent logs. You can also forward logs to external services using log forwarding.
Alarms
Stacktape supports built-in alarm triggers for relational databases. You can monitor CPU utilization, free memory, free storage, connection count, and read/write I/O latency. Alarms can notify via Slack, MS Teams, email, Discord, or webhook. See alarms for details on setting up alert channels.
Available database alarm triggers:
| Trigger type | Threshold unit | What it monitors |
|---|---|---|
database-cpu-utilization | Percent | CPU usage |
database-free-memory | MB | Available RAM |
database-free-storage | MB | Available disk space |
database-connection-count | Count | Active connections |
database-read-latency | Seconds | Read I/O latency |
database-write-latency | Seconds | Write I/O latency |
At minimum, set up a database-free-storage alarm on every production database. Running out of storage causes the database to become read-only and can be difficult to recover from quickly.
Each alarm trigger supports optional evaluation settings to control the evaluation window and avoid alerting on brief spikes. Define alarms in the database config and deploy to apply changes. Export legacy Console rules into config; disabledGlobalAlarms excludes named legacy rules during migration.
Backups and maintenance
AWS automatically takes daily backups of your database. The automatedBackupRetentionDays property controls how many days to keep backups (default 1, range 0–35). Set to 0 to disable automated backups for RDS engines. For Aurora engines, keep the retention value at 1 or higher. For production databases, increase this to at least 7 — a 1-day retention means you can only recover to yesterday, which is rarely enough when a data corruption issue is discovered days later.
The preferredMaintenanceWindow property sets when AWS applies patches and minor version upgrades (format: Sun:02:00-Sun:04:00 in UTC). The database may be briefly unavailable during this window. Multi-AZ and Aurora reduce downtime during maintenance. Pick a window during your lowest-traffic period.
Set deletionProtection to true on production databases to prevent accidental deletion. You must deploy with deletionProtection: false before Stacktape can delete the database. Until then, stacktape delete stops before deleting anything and lists the protected databases, and a deploy cannot remove or replace them.
Dev mode
The dev property controls how this database behaves during stacktape dev. By default, databases run locally in Docker during dev mode. Set dev.remote to true to connect to the real deployed resource instead (must be deployed first). Using remote: true is useful when local emulation doesn't match production behavior closely enough, or when you need to work with real data. See local databases for details on how local database emulation works.
Referenceable parameters
The following parameters can be easily referenced using $ResourceParam directive directive.
To learn more about referencing parameters, refer to referencing parameters.
Fully-formed connection string that can be used to access the primary instance. For aurora databases, this is connectionString to cluster endpoint, which can be used for both reads and writes. Includes host, port, username, password and dbName.
- Usage:
$ResourceParam('<<resource-name>>', 'connectionString')
Fully-formed connection string in JDBC form that can be used to access the primary instance. Includes host, port, username, password and dbName.
- Usage:
$ResourceParam('<<resource-name>>', 'jdbcConnectionString')
Hostname (address) of the primary instance that can be used for both reads and writes. For aurora databases, this is hostname of a cluster endpoint, which can be used for both reads and writes.
- Usage:
$ResourceParam('<<resource-name>>', 'host')
Port of the database.
- Usage:
$ResourceParam('<<resource-name>>', 'port')
Name of the automatically created database (can be configured using the
dbNameproperty).- Usage:
$ResourceParam('<<resource-name>>', 'dbName')
Hostname (address) used for reads only. (only available for
aurora-postgresqlandaurora-mysqlengines). If you have multiple instances, it is advised to use readerHost for reads to offload the primary (read/write) host. ReaderHost automatically balances requests between available instances. Connections are auto-balanced among available reader hosts.- Usage:
$ResourceParam('<<resource-name>>', 'readerHost')
Same as connectionString but targets readerHosts (only available for
aurora-postgresqlandaurora-mysqlengines). Connections are auto-balanced among available reader hosts.- Usage:
$ResourceParam('<<resource-name>>', 'readerConnectionString')
Same as readerConnectionString but in JDBC format (only available for
aurora-postgresqlandaurora-mysqlengines).- Usage:
$ResourceParam('<<resource-name>>', 'readerJdbcConnectionString')
Comma-separated list of read replica hostnames (only available if read replicas are configured). Read replicas can only be used for read operations.
- Usage:
$ResourceParam('<<resource-name>>', 'readReplicaHosts')
Comma-separated list of connection strings (URLs) used to connect to read replicas (only available when read replicas are configured). Read replicas can only be used for read operations.
- Usage:
$ResourceParam('<<resource-name>>', 'readReplicaConnectionStrings')
Same as readReplicaConnectionStrings but in JDBC format (only available when read replicas are configured).
- Usage:
$ResourceParam('<<resource-name>>', 'readReplicaJdbcConnectionStrings')
API Reference
RelationalDatabasePropsRelational Database FAQ
When should I use Aurora Serverless v2 vs standard RDS?
Aurora Serverless v2 is the best default for most new projects. It auto-scales compute so you don't need to predict traffic, and it costs less than a fixed instance during low-usage periods. Use standard RDS when you need MariaDB, Oracle, or SQL Server (which Aurora doesn't support), or when your workload is steady enough that a fixed instance gives simpler cost forecasting. Standard RDS also starts cheaper at ~$12/month for db.t4g.micro vs Aurora Serverless v2's per-ACU-hour pricing.
How do I run database migrations with Stacktape?
Define a script of type local-script in the scripts section of your config with connectTo set to include the database resource name, then reference the script from hooks.afterDeploy using scriptName. Stacktape injects the connection string environment variable into your script automatically. For databases behind a VPC, use a script of type local-script-with-bastion-tunneling to tunnel through a bastion host. See hooks and scripts for the full setup.
How much does a Stacktape relational database cost?
Standard RDS starts at $12/month for $50/month) or db.t4g.micro and scales up with instance size — db.t4g.medium (db.r6g.large (~$180/month). Storage is billed separately (a few cents per GB/month for the allocated, not maximum, size) and multiAz roughly doubles the instance cost. Aurora instances start at ~$35/month. Aurora Serverless v2 bills per ACU-hour between your minCapacity and maxCapacity with no fixed instance commitment, so it costs less during quiet periods but has less predictable monthly totals.
Can I connect to my Stacktape database from my local machine?
Yes. By default, databases use internet accessibility mode (except Aurora Serverless, which requires VPC modes), so you can connect from anywhere with the credentials. For VPC-restricted databases, use a bastion host and the stacktape bastion tunnel command to create a secure tunnel. You can also whitelist your IP address using accessibility.whitelistedIps in vpc or scoping-workloads-in-vpc modes.
How do I back up and restore my database?
AWS automatically takes daily backups and retains them based on automatedBackupRetentionDays (default 1 day, range 0–35); for production, raise this to at least 7 so you can recover from corruption discovered days later. Restoring from a snapshot creates a new database instance and is done through the AWS console, not through Stacktape config. Note that deletionProtection: true blocks deletion entirely — you must redeploy with it set to false before Stacktape can delete the database.
How do I choose the right RDS instance size?
Start with db.t4g.micro (2 vCPU, 1 GB RAM, ~$12/month) for development and testing. For small production workloads, db.t4g.medium (2 vCPU, 4 GB RAM, ~$50/month) handles most low-traffic applications. The t family is burstable — cost-effective for variable workloads but throttled under sustained high CPU. For production with consistent traffic, use the r family (memory-optimized), starting with db.r6g.large (2 vCPU, 16 GB RAM, ~$180/month). Monitor CPU and memory metrics through alarms and resize when you see sustained high utilization.